The Single Sign On (SSO) module provides login with the OAuth and OpenID Connect protocols. It can be used to protect a part of your website from anonymous access. It can also be used to provide an alternative login to Magnolia admincentral. By using an external login service, Magnolia doesn't have to care about the specific authentication process at all. Instead it is handled completely transparently by the service that is configured to be used. For example the external authentication service could use a two-factor authentication before a user can be successfully authorized.
Maven is the easiest way to install the modules. Add the following dependencies to your bundle:
Depending on the authentication provider you want to integrate with, the following user storage mechanisms can be used:
- Social logins (Google, Twitter, Facebook, GitHub, Instagram, LinkedIn, Xing, etc.)
- LDAP, Active Directory, SAML 2.0 via the Keycloak service or comparable solutions (like the commercial Airlock)
See Authentication Services for configuration settings.
JAAS login configuration
Magnolia uses the Java Authentication and Authorization Service (JAAS) to authenticate users. When you store users in a directory outside of Magnolia configure the directory as a LoginModule. You can list several LoginModules. Authentication proceeds down the module list in the order you specify with flags, see javax.security.auth.login.Configuration. Depending on the servlet container you use the configuration for JAAS is slightly different.
JAAS for Tomcat
WEB-INF/config you will find the JAAS configuration file. Here you can configure the as many realms with as many LoginModules as needed using the following format:
A realm is a security policy domain defined for a web or application server. The protected resources on a server can be partitioned into a set of protection spaces, each with its own authentication scheme and/or authorization database containing a collection of users and groups.
A class that implements the desired authentication technology.
The flag indicates whether success of the preceding LoginModule is
Options is a space-separated list of LoginModule-specific values which are passed directly to the LoginModule. The options are defined by the LoginModule itself, and control its behavior.
Be sure to add the JAAS configuration to be used by the SSO Connector.
The realm name sso-authentication in this example must match the name you will use later when adjusting Magnolia login filter configuration.
Add the sso block to the file jaas.config located under
The module provides a user manager configuration that is bootstrapped on installation. You can find it here
/server/security/userManagers/sso-authentication. There is no additional configuration changes that need to be made here but it should be noted that the realm must match the one declared in in your jaas.config.
The module provides a login handler configuration that is bootstrapped on installation. You can find it here
/server/filters/login/loginHandlers/SSOConnector. In order for the new handler to work properly you must also configure a new login filter class.
It the job of the SecurityCallbackFilter to handle 401 and 403 HTTP response codes and
AccessDeniedExceptions. The filter renders an appropriate "login form" that can consist of a redirect or anything else. This is a very sensitive configuration since the order of the callback nodes has meaning. The top node is triggered first so this node can overrule all the others and prevent login if not configured correctly.
- This module is at INCUBATOR level.
- Changing security settings and/or altering the filter chain can create situations of being locked out of the system. Never go to production with such manual changes. Changes should be applied via versions handlers or bootstrap files that have been tested for accuracy. For more information on best practices contact the Magnolia support team.
- State Parameter
The state parameter is treated as additional security element for handling OAuth based logins. The OAuth Authorization Server has to deliver back the state parameter with whatever value was originally send by the client. If the original value created by the client does not match the value delivered to the callback URL, login will fail. This behavior is used for adding cross site protection: If the state is not matched with the original value, the client will just take any code provided and try to post it to the authorization server. If the state parameter doesn't match, it's very likely that someone tries to hack the system or fish for a valid authorization code. Therefore, the login handler immediately stops all processing.
- Refresh Tokens
- OAuth can handle refresh tokens to automatically refresh the "real" token when expired.The SSO Connector is used for login and not for accessing arbitrary resources. Refresh tokens are not used at the moment. After a successful login to Magnolia, the access token is not needed any more because the session will end when the user is logged out and there are no intermediate requests to protected resources.
OpenID Connect is an open standard built on top of OAuth 2.0. It defines a way to interoperate with OAuth 2.0 especially in the context of user authentication. The problem with OAuth 2.0 (bearer) tokens is that anyone who has the token can get access to the protected resource as long as the token is valid. There will be no verification if a machine or an actual user has logged in to the system (the token carries no information about the authentication event).
Adding OpenID Connect to your OAuth 2.0 authentication workflow solves this problem by exchanging secured information between the client and the server to make sure an actual authentication event has happened.