Login handlers

This page lists all the login handlers provided out of the box. For each handler, you can read about how it works, which security it provides, and any limitations you should consider when using it. This information lets you choose a login handler best suited for your DX Core installation safety level needs.

BasicLogin and FormLogin are both login handlers used in Magnolia’s Login filter. The filter’s fully qualified class name is info.magnolia.cms.security.auth.login.LoginFilter. The login filter verifies that user credentials are authenticated to ensure that only authenticated users become active users. Magnolia uses Java Authentication and Authorization Service (JAAS) for authentication.

📁 server

     📁 filters

         📁 login

             ⸬ loginHandlers

                 ⸬ Basic

                     ⬩ class


                 ⸬ Form

                     ⬩ class


                 ⬩ class


BasicLogin login handler

You should only use basic authentication when the transport layer security is good, such as HTTPS. The basic authentication protocol is defined in the Hypertext Transfer Protocol standard RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication). A client connects to a web server by sending a WWW-Authenticate: Basic message in the HTTP header. Shortly after, it sends the login credentials to the server using a base64 encoding. When HTTPS is used, the credentials are encrypted and considered secure.

The biggest limitation with basic authentication relates to logging off the server. Most web browsers store sessions and don’t always close and clear them, which can prevent others from logging in by refreshing the browser. Digest authentication transmits the username and hash of the password, whereas basic authentication uses a non-encrypted base64 encoding.

FormLogin login handler

Form-based authentication doesn’t rely on any RFC; developers use standard HTML form fields to pass credentials to the server. Furthermore, the server creates a session with a unique ID. When a user logs off, the open session is closed. Similarly to basic authentication, login credentials are not encrypted and must be used with a security layer like HTTPS.

Login via GET disabled by default

Logging in with query parameters using the GET method is now disabled by default. Trying to do so results in a 401 Unauthorized error.

To allow GET or other HTTP methods, add them as a list to info.magnolia.cms.security.auth.login.FormLogin#allowedMethods. See this configuration as an example.

Enable other methods in the form login via allowedMethods only on non-production systems.

Other login handlers

This section outlines some Magnolia modules that use login handlers. The ones listed below are under the loginHandlers configuration but separate from BasicLogin and FormLogin. All login handlers use JAAS for authentication.

  • CAS module

  • WeChat Login module

    • Filter class name: info.magnolia.cms.security.auth.login.SSOAuthenticationLoginFilter

    • Configuration details

  • The SSO and LDAP modules

    • Magnolia LDAP Connector is a JAAS login module that connects to any LDAP v3 directory service. Go to JAAS login configuration for more details.

    • The SSO module delegates authentication away from Magnolia to an OpenID Connect identity and access management application. The delegation and setting of a successful login process is handled by info.magnolia.sso.auth.login.SsoLoginHandler.

Custom login handlers

You can also create a custom login handler from info.magnolia.cms.security.auth.login.LoginHandlerBase.

It can listen for your request parameter in the handle() method. If the parameter is present:

LoginResult result = authenticate(mycallbackhandler, "magnolia");
return result;

If the parameter is not present, return:

return LoginResult.NOT_HANDLED; (1)
1 Returning the NOT_HANDLED results lets another login handler deal with the request.

The authenticate() method defers to the Magnolia JAAS authentication to perform the login. It also takes care of all ACLs and sets up the context.

The JAAS layer needs the callback handler to access the information about the user credentials supplied for the login. For this, you should instantiate info.magnolia.cms.security.auth.callback.CredentialsCallbackHandler. An example of this instantiation is shown below.

CredentialsCallbackHandler mycallbackhandler = new CredentialsCallbackHandler("myusername", "mypasswd", "admin"); (1)
1 This causes JAAS to try to authenticate the user myusername from the admin users.

Deploy your login handler to Magnolia’s WEB-INF/lib in a JAR file, and then configure it in Magnolia under Configuration → /server/filters/login/loginHandlers/myHandler.

Make sure you test it out on a non-production system first, as a misconfigured login handler or a programming error in the handler could render your Magnolia instance inaccessible.

DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.