Page tree

A new Single Sign-On module has been released as part of DX Core.

Refer to SSO module in the main product documentation for up-to-date information. This page and the incubator module are no longer maintained.

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 module. Add the following dependency to your bundle:



2.1Magnolia 6.2
2.1Magnolia 6.1
2.1Magnolia 5.7
2.1Magnolia 5.6.5


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 can be supported via the Keycloak service or other intermediator solutions like the commercial Airlock.

    SAML, AD and LDAP are not directly supported by this module. For that please see LDAP Connector module.

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 Depending on the servlet container you use the configuration for JAAS is slightly different.

JAAS for Tomcat

Inside 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:

jaas.config syntax
<realm> { 
   <LoginModule> <flag> <options>;
   <LoginModule> <flag> <options>;
   <LoginModule> <flag> <options>;




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.


  • info.magnolia.connector.sso.jaas.SSOAuthenticationModule authenticates against an external login service.



The flag indicates whether success of the preceding LoginModule is required , requisite , sufficient , or optional . If you only have one LoginModule then the flag must be required.
See the flag values in



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.

Options for JCRAuthenticationModule module:

  • realm : Restrict the login to a certain realm. Valid values: system , external , admin , public.
  • use_realm_callback : Allow the client to define the realm he logs into. Values: true , false . Default is false .
  • skip_on_previous_success : A Magnolia-specific option to define if this module needs to be skipped based on previous (in JAAS module chain) module status. Values: true , false . If true this module is skipped if the previous module did a successful login.


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 /WEB-INF/config:

 * options for JCRAuthenticationModule module:
 *   realm: to restrict the login to a certain realm
 *   use_realm_callback: to allow the GUI to pass the realm to login into
 *   skip_on_previous_success: if true the login is scipped if a former module proceeded a successfull login
 * example:
 *    info.magnolia.jaas.sp.jcr.JCRAuthenticationModule requisite realm=public;
 *    info.magnolia.jaas.sp.jcr.JCRAuthenticationModule requisite realm=admin skip_on_previous_success=true;

magnolia {
  // ensure user is who he claims he is (check pwd for the user)
  info.magnolia.jaas.sp.jcr.JCRAuthenticationModule requisite;
  // retrieve users ACLs
  info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;

sso-authentication {
  info.magnolia.connector.sso.jaas.SSOAuthenticationModule requisite;
  info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;

User manager

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.

Login handler

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.

Security Callbacks

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

    • 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.

  • The logout mechanism has been only tested on Biocryptology OpenID server and Google OpenID server. 
  • There is no SAML support provided by this module. It cannot be used with ADFS for example.

    If you need to directly connect to Microsoft AD, then your choice is the LDAP Connector module.


  • Future improvements planned
  • Version 2.1
  • Version 2.0 - Initial release of the extensions version of the module.


  1. Hi,

    this page states "SAML 2.0" as an option under "Usage", and at the same time "There is no SAML support provided by this module" under "Warnings". As there is no further details on configuring SAML, I guess mentioning of SAML 2.0 should be removed from "Usage"?

    1. Hi Joerg-

      I think they key phrase here is that SAML can be supported via keycloak. SAML is not supported directly through this module. I will try and rephrase the docs a bit so that is clearer.

      Thanks for your comments

      1. Richard Gange  when you say that this can be supported via keycloak, do you have any information on how to achieve that?

  2. Great module! Just a general remark about the code: Some fields are neither named meaningfully nor are they commented. It would be very helpful to either have identifier names that use the OAuth/OIC terminology or a javaDoc that explains the purpose/usage of the field (or method).

    Take `info.magnolia.connector.sso.oic.service.OICServiceRequest#requestedUrl` for example. It's semantic meaning is rather ambiguous and you'd have to dig through the code to get it.