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 |
|
📁 login |
|
⸬ loginHandlers |
|
⸬ Basic |
|
⬩ class |
info.magnolia.cms.security.auth.login.BasicLogin |
⸬ Form |
|
⬩ class |
info.magnolia.cms.security.auth.login.FormLogin |
⬩ class |
info.magnolia.cms.security.auth.login.LoginFilter |
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 |
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
-
Filter class name: info.magnolia.cms.security.auth.login.CASLogin
-
-
WeChat Login module
-
Filter class name: info.magnolia.cms.security.auth.login.SSOAuthenticationLoginFilter
-
The SSO and LDAP modules handle login authentication differently, as the linked sections below explain.
-
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.
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. |