SSO module


DX Core





Maven site




The SSO module handles authentication for the instance on which it is installed. Read this page carefully and test the module on a development environment before proceeding to ensure installation does not break your instance.

The Magnolia SSO (single sign-on) module delegates authentication from a Magnolia instance to an OpenID Connect identity and access management application. The current iteration of the module has been successfully tested with open source Keycloak and cloud identity management software Okta, but all providers that follow the protocol should also be supported.

As Magnolia is already capable of full-fledged security, the intent is to only replace the authentication mechanism. A user on a third-party system with roles and groups is mapped to the equivalent Magnolia user roles and groups.

The SSO module version 3.0.0+ is compiled with Java 11, so you need Java 11 or higher for runtime.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:




A running Open ID Connect IAM instance on which you have administrative rights is required for the setup to work. As Keycloak is open source and can be deployed locally, it’ll be used as an example in the instructions below. But any IAM instance should work, as long as it is configured in a similar manner.

Keycloak’s own Server Administration Guide is an excellent resource to help with configuring the properties that’ll get brought up below.
If you use Keycloak and intend to deploy it by code, then take a look at the SsoModuleIT class and the module’s test Docker Compose setup. The module’s integration tests configure Keycloak from scratch.
Prerequisite Description

a user


Its username and password are used to access Admincentral. It should have names as well as an email.

a group


When the user logs in, it has to belong (in Keycloak’s eyes, that is either in Keycloak directly, or in a user federation provider) to at least one group defined in the group mappings. That’s how the necessary access to Magnolia is granted.

an OIDC client


With the following properties:

     a name


Must be the same as the one used in the YAML configuration of the module.

     the openid-connect protocol


     a confidential access type


This is required in order for Keycloak to generate credentials.



Those must be shared with the YAML configuration of the module.

     a redirect URI


That points back to Magnolia, e.g. http://localhost:8080/*.

     a Group Membership mapper


By convention, this is required in order to include the user’s groups in the groups property, see GroupsAuthorizationGenerator. Without this data, a user won’t be assigned any Magnolia permission, and hence won’t be able to go past the login screen. Here’s how to configure the mapper in various applications:

azure keycloak okta

YAML configuration for Magnolia 6.2

This section explains how to configure the SSO module for Magnolia 6.2. This has to be done with a resource file located in /magnolia-sso/config.yaml.

See Resources for more details if needed.
From version 3.x, the SSO module no longer supports configuration via a YAML decorator.

From magnolia.resources.dir, use the following path structure:

path: /.magnolia/admincentral (1)
callbackUrl: http://localhost:8080/.auth (2)
postLogoutRedirectUri: http://localhost:8080/.magnolia/admincentral (3)
authorizationGenerators: (4)
  - name: fixedRoleAuthorization
        - superuser
        - …
  - name: groupsAuthorization
        - name: magnolia-sre
            - publishers
            - …
clients: (5) 0oa1imrwonnyHpIvI0x7
  oidc.secret: aKzLmsj...tIL8HKkh6
  oidc.scope: openid profile email
  oidc.preferredJwsAlgorithm: RS256
  oidc.authorizationGenerators: groupsAuthorization 0oa1imrwonnyHpIvI0x7
  http.bearer.secret: aKzLmsj...tIL8HKkh6
  http.bearer.scope: openid profile email
  http.bearer.preferredJwsAlgorithm: RS256
  http.bearer.authorizationGenerators: fixedRoleAuthorization
  http.bearer.authenticator: oidc-userinfo

userFieldMappings: (6)
  name: preferred_username
  removeEmailDomainFromUserName: true
  removeSpecialCharactersFromUserName: false
  fullName: name
  email: email
  language: locale

Callout descriptions

Callout Description


Required Describes on which path the SSO module should kick in. /.magnolia/admincentral is the default for most cases.


Required The URL of Magnolia’s callback servlet. This URL is made up of the instance’s absolute URL (in this case, http://localhost:8080) as well as the relative path to SSOCallbackServlet, which is /.auth by default.

Since SSO Module 1.1.1, if the supplied callbackUrl is a relative path, it is automatically prefixed with the instance’s defaultBaseUrl property. This requires the property to be properly defined in the first place. All users including anonymous must have access to /.auth. From SSO module 2.0.3, this is possible by assigning users the sso-redirect-uri-authorizer role.


Optional The URI to where the user is returned after logging out. If the property is not defined, it falls back to the user’s current URL. This must be an absolute URL.

Property defined::

Jane is working on http://localhost:8080/.magnolia/admincentral and she logs out. Jane is redirected to http://localhost:8080/.magnolia/admincentral/logout.

Property not defined

Jane is working on http://localhost:8080/.magnolia/admincentral and she logs out. Jane is redirected back to http://localhost:8080/.magnolia/admincentral.


Required A list of configured authorization generators as part of a specified client. Currently, we support both Fixed and Group authorization.

Fixed Role Generator: allows you to give all users the same permissions. This generator shouldn’t be used in production but it can be a good starting point:

  • When you are setting things up.

  • Where group mappings are not possible. For instance, with Google Cloud, where manual verification of the application must happen before the user’s groups can be queried.

      - superuser
      - …

Groups Generator: This generator should be used when different security levels in the IDP should be mapped to equivalent Magnolia roles and groups. Given a user’s groups on a third-party IAM management instance, the generator maps the group(s) to one or multiple Magnolia roles. The following example assigns the superuser role to a group of administrators.

      - name: magnolia-sre
          - publishers
          - …
When working with Azure Active Directory, group IDs (rather than names) must be used. To increase transparency, add the actual group’s name as a comment. See the following example.
      - name: ea0b1d9f-c8fc-4b99-9f76-8a92abbbb496: # sysadmins
          - …


Required A set of properties for different clients (Oidc and DirectBearerAuthClient with oidc and http.bearer prefix respectively). This is where you define the client IDs, secrets, and scopes. You can enter multiple clients here as shown in the example. Each client requires a name, secret, scope, discoveryUri, authorizationGenerators and authenticator (only requires for Pac4j’s DirectBearerAuthClient with http.bearer properties prefix) as shown below.

Notice that you can define multiple clients of the same type by adding a number at the end of the properties:,…​Please find below as an example:

clients: 0oa1imrwonnyHpIvI0x7
  oidc.secret: aKzLmsj...tIL8HKkh6
  oidc.scope: openid profile email
  oidc.preferredJwsAlgorithm: RS256
  oidc.authorizationGenerators: groupsAuthorization <another client id>
  oidc.secret.2: <another client secret>
  oidc.scope.2: openid profile email
  oidc.preferredJwsAlgorithm.2: RS256
  oidc.authorizationGenerators.2: groupsAuthorization <client id>
  ... <second http client id>

An additional client can be configured (properties prefix http.bearer) to support a use case like getting resources or content from Magnolia via REST calls with Bearer authentication. Check out the Okta concepts docs for more details: Resource Owner Password flow and Client Credentials flow. Find out more in Pac4j Clients concepts.

Expand for further details

  • name: The name of the client that is configured to allow the Magnolia instance to access the IAM instance. This can be anything but must share the same name as configured in the IAM instance.

  • id: The client ID.

  • secret: The client secret.

  • scope: Defines the user data that the Magnolia instance should be allowed to request from OIDC.

    The openid, profile, and email scopes are mandatory in order for Magnolia to create a user account with basic information about the user. For users that implement refresh tokens with Azure, you can add the offline_access scope as well.
  • discoveryUri: The IAM instance’s auth endpoint URL. This must be tweaked according to your project.

  • authorizationGenerators: Defines the authorization generator names to use for the client. Refer to the name of the configured authorization generators (callout 4).

    You can define multiple authorization generators separated by commas, e.g.,: groupsAuthorization, editorGroupsAuthorization
  • authenticator: The HTTP clients require that you define an Authenticator to handle the credentials validation. This property is required for the http.bearer properties prefix only. It only supports 2 authenticators. Possible values for this property are: oidc-userinfo and token-introspection.

    • oidc-userinfo: This UserInfoOidcAuthenticator is provided by Pac4j which authenticates the request with a Bearer Token using the Oidc UserInfo endpoint.

    • token-introspection: This implementation of Authenticator will authenticate the request with a Bearer Token using the Token Introspection endpoint. Please note that some Identity providers (IdP) do not support the Token Introspection endpoint, please make sure it is fully supported before configuring this authenticator.



Authentication services use different attribute names for user information. Because of this, it is necessary to map the retrieved response to a standard set of user attributes used within the SSO module. This contains key-value pair mappings where the key is the property name which will be stored within the properties of Magnolia’s and the value is the attribute name in the OIDC profile.
You can find more details at Map OIDC attributes to Magnolia properties.

If the identity provider does not return a name attribute in the OIDC profile, Magnolia deduces it from the email attribute by excluding the domain.

Where becomes fabien.

Configure JAAS

The instance’s JAAS configuration (see JAAS security set up) must be edited and only contain the following:

JAAS configuration
sso-authentication {
  info.magnolia.sso.jaas.SsoAuthenticationModule requisite;
  info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;

Module compatibility

Module version Third-party APIs tested against


Keycloak 16.1.1

See here for more on Keycloak 16.1.1.


Azure Active Directory

We exclusively support the 2.0 version of the endpoint. This means the URL should look like…/v2.0/.well-known/openid-configuration.


Google Cloud Identity


Keycloak 9.0.3


Okta 2021.03.3+