SSO module

Security and authentication Unbundled: Extension

Edition

DX Core

License

MLA

Issues

MGNLSSO

Maven site

SSO

Latest

4.0.1

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.

SSO module version 4.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:

<dependency>
  <groupId>info.magnolia.sso</groupId>
  <artifactId>magnolia-sso</artifactId>
  <version>4.0.1</version> (1)
</dependency>

1	Should you need to specify the module version, do it using `<version>`.

Prerequisites

A running Open ID Connect (OIDC) IAM instance on which you have administrative rights is required for the setup to work. Any IAM instance should work, as long as it is configured in the manner described in this document.

If using Keycloak: 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

required

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

a group

required

When the user logs in, they have to belong to at least one group defined in the group mappings. That’s how the necessary access to Magnolia is granted.

A user may only belong to a maximum number of 200 groups, including nested groups, for JSON web tokens (JWT). For more information, see Microsoft group overages.

an OIDC client

required

With the following properties:

a name

required

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

the openid-connect protocol

required

a confidential access type

required

This is required to generate credentials.

credentials

required

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

a redirect URI

required

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

a Group Membership mapper

required

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

Okta
Azure
Keycloak

okta

azure

If you leave Full group path toggle On as shown below, make sure it’s reflected in your yaml configuration as the path (/group-name, not just group-name). Otherwise, toggle this option to Off and use the group name.

keycloak

If you are not using a default Magnolia bundle, check that your Apache Tomcat cookie processor implementation has sameSiteCookies set to lax: <CookieProcessor sameSiteCookies="Lax" />. For more information, see Troubleshooting .

SSO user profile information

User profile preferences related to the Magnolia instance for SSO users is stored in the profiles workspace that may only be accessed by the superuser.

The following information is stored in the profiles workspace for SSO users:

Full name
Email
Favorite apps
Language
Last login
Previous login
Timezone
Completed intro status (Magnolia app launcher tour)
Usage metrics acknowledgement status

SSO users can set their user preferences for timezone and language in AdminCentral.

The information for each user is stored based on the username from the third-party IdP. If you change a user’s username in your IdP, their preferences are reset in Magnolia.

Configuring via yaml

This section explains how to configure the SSO module for Magnolia 6.3. It focuses on configuring the setup for an OIDC provider. This must be done with a resource file located by default in /magnolia-sso/config.yaml. If the magnolia.sso.config property is added to the magnolia.properties file, this path can be configured so that environment-specific configurations may be defined.

From version 3.x, the SSO module no longer supports configuration via a YAML decorator.

Create config.yaml under <magnolia.resources.dir>/magnolia-sso/.

Take a look at the full .yaml file here. Required fields are marked with callouts. We’ll go through each part of it in the subsequent steps.

config.yaml

callbackUrl: /.auth (1)
postLogoutRedirectUri: http://localhost:8080
authorizationGenerators: (1)
  - name: fixedRoleAuthorization
    fixed:
      targetRoles:
        - superuser
      targetGroups:
        - publishers
  - name: groupsAuthorization
    groups:
      targetProperty: groups
      mappings:
        - name: superusers
          targetGroups:
            - publishers
          targetRoles:
            - superuser
clients: (1)
  oidc.name: defaultOidcClient (2)
  oidc.id: 0o...x7
  oidc.secret: aK...th6
  oidc.clientAuthenticationMethod: client_secret_basic
  oidc.scope: openid profile email
  oidc.discoveryUri:  https://YOUR_URI/oauth2/aus...0x7/.well-known/openid-configuration
  oidc.preferredJwsAlgorithm: RS256
  oidc.authorizationGenerators: groupsAuthorization
  oidc.callbackUrl: /.auth
  oidc.postLogoutRedirectUri: http://localhost:8080 (2)

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

1	Required field.
2	Optional field.

callbackUrl requires a global configuration (this step) or a configuration in the clients section. Skip this step to specify it in the clients section.

If you specify callbackUrl at the top of the configuration and in the clients section, the client configuration overrides the general setting at the top. Any client configuration overrides the general setting at the top.

Specify the callbackUrl for each client. It is a relative path to the SSOCallbackServlet (For example, /.auth).

callbackUrl: /.auth (1)
...

1	This relative URL doesn’t need to match defaultBaseURL, the default base URL of the server root. `DefaultUrlResolver` completes relative URLs using `defaultUrlResolver.setCompleteRelativeUrl(true)` from pac4j. For more details, see Field descriptions.

If desired, set a postLogoutRedirectUri. This is optional and is the URI to which users are redirected after logging out. Skip this step to specify it in the clients section.

If you specify postLogoutRedirectUri at the top of the configuration and in the clients section, the client configuration overrides the general setting at the top. If it isn’t set to a value either globally or in the clients section, it redirects to the requestUrl when logging out.

callbackUrl: /.auth
postLogoutRedirectUri: http://localhost:8080 (1)
...

1	If undefined, it goes back to the user’s current URL. For more details, see Field descriptions.

List the authorizationGenerators.

This defines the groups and roles for your client. These are needed for groups generators and fixed role generators. If you want a custom generator, follow the steps here.

callbackUrl: /.auth
postLogoutRedirectUri: http://localhost:8080
authorizationGenerators: (1)
  - name: groupsAuthorization
    groups:
      targetProperty: groups (2)
      mappings:
        - name: superusers (3)
          targetGroups:
            - publishers
          targetRoles:
            - superuser

1	This step simply defines your mappings. You need to call it inside your `clients:` configuration in this `config.yaml` to use it. For more details, see Field descriptions.
2	`targetProperty` maps to the groups in your IDP. By default, the value is `groups` but if your IDP uses a different term, you can configure it here.
3	If you are using a full path option (such as the option with Keycloak), ensure that is reflected here (`/superusers`). Otherwise, specify the group `name` as shown in the example.

Configure the clients section.

You can define general settings for callbackUrl and postLogoutRedirectUri at the top of the configuration. Any client configuration overrides the general setting at the top.

Specify the callbackUrl for each client. It is a relative path to the SSOCallbackServlet (For example, /.auth).

clients:
...
  oidc.callbackUrl: /.auth (1)
...

1	This relative URL doesn’t need to match defaultBaseURL, the default base URL of the server root. `DefaultUrlResolver` completes relative URLs using `defaultUrlResolver.setCompleteRelativeUrl(true)` from pac4j. For more details, see Field descriptions.

Optionally, set a postLogoutRedirectUri for each client. It is the URI to which users are redirected after logging out.
```
clients:
...
  oidc.callbackUrl: /.auth
  oidc.postLogoutRedirectUri: http://localhost:8080 (1)
...
```
1 If undefined, it goes back to the user’s current URL. For more details, see Field descriptions.

Specify the remaining oidc properties for each client.

...
clients:
  oidc.id: 0o...x7 (1)
  oidc.secret: aK...th6 (1)
  oidc.clientAuthenticationMethod: client_secret_basic (2)
  oidc.scope: openid profile email (3)
  oidc.discoveryUri:  https://YOUR_URI/.well-known/openid-configuration (4)
  oidc.preferredJwsAlgorithm: RS256 (5)
  oidc.authorizationGenerators: groupsAuthorization (6)
  oidc.callbackUrl: /.auth
  oidc.postLogoutRedirectUri: http://localhost:8080

  oidc.id.2: 0o...g3 (7)
  oidc.secret.2: l3...jE3
  oidc.clientAuthenticationMethod.2: client_secret_basic
  oidc.scope.2: openid profile email
  oidc.discoveryUri.2:  https://YOUR_URI/.well-known/openid-configuration
  oidc.preferredJwsAlgorithm.2: RS256
  oidc.authorizationGenerators.2: groupsAuthorization
  oidc.callbackUrl.2: http://localhost:8080/.auth
  oidc.postLogoutRedirectUri.2: http://localhost:8080

  oidc.id.3: 0o...x7
  oidc.secret.3: aK...th6
  oidc.authorizationGenerators.3: CustomAuthorizationGenerator (8)

1	You’ll find the `id` and `secret` with your OIDC provider configuration.
2	Defines how the client credentials (client ID and secret) are passed to the token endpoint. Supported methods are: `client_secret_basic`, `client_secret_post` and `private_key_jwt`.
3	Defines the user data that the Magnolia instance should be allowed to request from OIDC. For more on `scope`, see here. The `openid`, `profile`, and `email` scopes are mandatory. For more details, see Field descriptions.
4	The IAM instance’s auth endpoint URL. This must be tweaked according to your OIDC provider.
5	The `preferredJwsAlgorithm`. This is typically `RS256.`
6	Defines the authorization generator names to use for the client as set in the `authorizationGenerators` section in this `config.yaml` file. For more details, see Field descriptions.
7	Define a second client with the `.2` suffix. For more details, see Field descriptions.
8	It’s possible to define custom authorization generators as well. If you want a custom generator, follow the steps here.

Update your custom field mappings under userFieldMappings property. For more details, see Field descriptions.

...
userFieldMappings:
  name: preferred_username (1)
  removeEmailDomainFromUserName: false (2)
  removeSpecialCharactersFromUserName: false (3)
  fullName: name
  email: email
  language: locale

1	Required `name` is a required field for the Magnolia User. Typically the value that you get from the Oidc profile attribute name is `preferred_username` or `email`.
2	Optional `removeEmailDomainFromUserName` is `false` by default. This is a built-in formatter to remove the email domain from the name attribute (e.g., `test-user@domain.com` will be `test-user` if this config is set to `true`).
3	Optional `removeSpecialCharactersFromUserName` is `false` by default. This is a built-in formatter to remove all special characters from the attribute except dots, hyphens, and underscores.

Field descriptions

Callout Description

callbackUrl

Required

The URL of Magnolia’s callback servlet. You can set callbackUrl to an absolute path or path relative to SSOCallbackServlet, which is /.auth by default.

You can force the protocol by prefixing the URL with either [https] or [http], for example, [https]/.auth. It must be enclosed in single quotes if a protocol is added to escape the brackets, for example:

oidc.callbackUrl: '[https]/.auth'

Adding a scheme to define the protocol type isn’t required in DX Cloud since the X-Forwarded header is always present.

Since SSO Module 4.0.1, for the relative path, our custom resolver MagnoliaPac4jUrlResolve completes it. When resolving, the highest priority is protocol, followed by the existence of X-Forwarded headers in case the installation is behind a proxy or load balancer.

URL resolution is only done according to the behavior defined in DefaultUrlResolver (using defaultUrlResolver.setCompleteRelativeUrl(true) from pac4j) if no protocol is specified or no X-Forwarded headers are found.

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.

postLogoutRedirectUri

Optional

The URI to where the user is returned after logging out. This must be an absolute URL.

If the property isn’t defined, it falls back to the user’s current request URL. For example, if the URL is set to http://localhost:8080/magnoliaAuthor/.magnolia/admincentral, upon logging out, the user is redirected to http://localhost:8080/magnoliaAuthor.

If the property is defined, for example as http://localhost:8080/.magnolia/admincentral/logout, then the user is redirected to http://localhost:8080/.magnolia/admincentral/logout.

authorizationGenerators

Required

A list of configured authorization generators as part of a specified client. Currently, we support both Fixed and Group authorization. After defining these here, you need to call them in the clients: field in this config.yaml file.

Groups generator
Fixed role 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 maps the the IDP superusers group to the Magnolia group publishers with the Magnolia role superuser.

authorizationGenerators:
  - name: groupsAuthorization
    groups:
      targetProperty: groups
      mappings:
        - name: superusers
          targetGroups:
            - publishers
          targetRoles:
            - superuser

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.

authorizationGenerators:
  groups:
    targetProperty: groups
    mappings:
      - name: ea0b1d9f-c8fc-4b99-9f76-8a92abbbb496: # sysadmins
        targetRoles:
          - …

The fixed role generator gives all users the same permissions.

authorizationGenerators:
  - name: fixedRoleAuthorization
    fixed:
      targetRoles:
        - superuser
      targetGroups:
        - publishers

This generator shouldn’t be used in production but it can be a good starting point for settings things up or where group mappings aren’t possible. For instance, with Google Cloud, where manual verification of the application must happen before the user’s groups can be queried.

clients

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, clientAuthenticationMethod, scope, discoveryUri, authorizationGenerators and authenticator (only requires for Pac4j’s DirectBearerAuthClient with http.bearer properties prefix) as shown below.

You can define multiple clients of the same type by adding a number at the end of the properties: oidc.id.2, http.bearer.id.2.

http.bearer client

An http.bearer client can be configured 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.

clients:
  http.bearer.id: 0oa1imrwonnyHpIvI0x7
  http.bearer.secret: aKzLmsj...tIL8HKkh6
  http.bearer.clientAuthenticationMethod: client_secret_basic
  http.bearer.scope: openid profile email
  http.bearer.discoveryUri:  https://YOUR_URI/oauth2/aus...0x7/.well-known/openid-configuration
  http.bearer.preferredJwsAlgorithm: RS256
  http.bearer.authorizationGenerators: fixedRoleAuthorization
  http.bearer.authenticator: oidc-userinfo

oidc client field description

name

Optional, default is OidcClient.1, OidcClient.2, …

You can define a unique name for each client. The client name determines which specific client handles a login request. It also helps to trace what’s happening in debug logs because you can define the name yourself.

http.bearer client

The client name of the first http.bearer client is DirectBearerAuthClient.1 by default.

For a second http.bearer client, DirectBearerAuthClient.2 and so forth.

The field is optional, but you should configure it if you have multiple client use cases. For more, see Configuring multiple SSO clients.

id

Required

The client ID. You get this from your OIDC provider configuration.

secret

Required

The client secret. You get this from your OIDC provider configuration.

clientAuthenticationMethod

Optional, default is client_secret_basic

Defines how the client credentials (client ID and secret) are passed to the token endpoint.

Supported methods (values):

client_secret_basic
client_secret_post
private_key_jwt

scope

Optional, default is openid profile email

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

Required

The IAM instance’s auth endpoint URL.

This must be tweaked according to your project.

preferredJwsAlgorithm

Optional, default is RS256

This defines your preferred algorithm for validating identity tokens.

authorizationGenerators

Required

Defines the authorization generator names to use for the client. This includes custom authorization generators as well as fixed and/or group authorization generators. Refer to the name of your configured authorization generators.

You can define multiple authorization generators separated by commas, e.g.,: groupsAuthorization, editorGroupsAuthorization.

If you want a custom generator, follow the steps here.

callbackUrl

Required

The URL of Magnolia’s callback servlet. You can set callbackUrl to an absolute path or path relative to SSOCallbackServlet, which is /.auth by default.

oidc.callbackUrl: '[https]/.auth'

Adding a scheme to define the protocol type isn’t required in DX Cloud since the X-Forwarded header is always present.

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.

postLogoutRedirectUri

Optional

The URI to where the user is returned after logging out. This must be an absolute URL and is specified for each client in the clients configuration.

If the property is defined, for example as http://localhost:8080/.magnolia/admincentral/logout, the user is redirected to http://localhost:8080/.magnolia/admincentral/logout.

authenticator

Required

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.

userFieldMappings

Required

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 info.magnolia.cms.security.ExternalUser and the value is the attribute name in the OIDC profile.

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 fabien@example.com becomes fabien.

Minimal configuration

A minimal configuration is shown below using all the default values mentioned in the previous section.

callbackUrl: /.auth (1)

authorizationGenerators:
  - name: groupsAuthorization
    groups:
      targetProperty: groups
      mappings:
        - name: superusers
          targetRoles:
            - superuser

clients:
  oidc.id: <CLIENT_ID> (2)
  oidc.secret: <CLIENT_SECRET> (2)
  oidc.discoveryUri: <http://localhost:8180/realms/mgnl/.well-known/openid-configuration> (2)
  oidc.authorizationGenerators: groupsAuthorization (2)

userFieldMappings:
  name: email
  fullName: name
  email: email
  language: locale

1	Required field as a general setting or in oidc.callbackUrl.
2	Required field.

Environment-specific configuration

To create environment-specific configuration files:

Add the magnolia.sso.config property to the magnolia.properties file.
Set different paths for the config.yaml file for your environments:
- Default: WEB-INF/config/default/magnolia.properties
- Author environment: WEB-INF/config/magnoliaAuthor/magnolia.properties
- Public environment: WEB-INF/config/magnoliaPublic/magnolia.properties

The system looks for the file in the resources directory, typically magnolia.resources.dir.

Example of different default and author environment configuration file paths

# Example config in WEB-INF/config/default/magnolia.properties
magnolia.sso.config=/default/config.yaml
# Example config in WEB-INF/config/magnoliaAuthor/magnolia.properties
magnolia.sso.config=/ssoAuthor/config.yaml

The config.yaml file is loaded as a resource file. However, the path is configurable.

You must not place the SSO module config.yaml file under WEB-INF/config/default or WEB-INF/config/magnoliaAuthor because these folders are not watched by the Magnolia resource mechanism and an exception is thrown on startup if the YAML file is present there.

If the magnolia.sso.config property is not added, the module uses the /magnolia-sso/config.yaml path by default.

SSO 4.0 and later supports the use of both SSO and Magnolia JCR-based login mechanisms at the same time. The JCR login acts as a secondary authentication method, for example, to safeguard your access to the Magnolia instance if your IdP is not available.

When you configure JAAS to have both JCR- and SSO-based authentication entries as described below, users can log in using the default Magnolia login when they navigate to /.magnolia/jcrlogin, for example http://localhost:8080/magnoliaAuthor/.magnolia/jcrlogin. When they log out, users also fall back to the default login screen corresponding to their authentication method.

Configuring the URL

You can configure the default URL by updating the patternString property and the postLogoutRedirectUrl property to match. If the two properties don’t match, the login/logout doesn’t fall back to the URL.

Set your login URL using the patternString property under server/filters/securityCallback/clientCallbacks/ssoFallback/originalUrlPattern.

📁 server

📁 filters

📁 securityCallback

⸬ clientCallbacks

⸬ ssoFallback

⸬ originalUrlPattern

⬩ class

info.magnolia.cms.util.SimpleUrlPattern

⬩ patternString

/.magnolia/jcrlogin

⬩ enabled

true

Update the postLogoutRedirectUrl property with the same URL under server/filters/login/loginHandlers/Form@postLogoutRedirectUrl. This means users are also logged out back to the correct login URL.

📁 server

📁 filters

📁 login

⸬ loginHandlers

⸬ Form

⸬ allowedMethods

⬩ class

info.magnolia.cms.security.auth.login.FormLogin

⬩ defaultLoginRedirectUrl

/.magnolia/admincentral

⬩ postLogoutRedirectUrl

/.magnolia/jcrlogin

⬩ class

info.magnolia.cms.security.auth.login.LoginFilter

Disabling default login

Configuring JAAS

Ensure the JAAS security setup configuration is in the WEB-INF/config/jaas.config file. The configuration should appear as follows for SSO installations when using both SSO and the optional fallback JCR-based authentication:

JAAS configuration

magnolia { (1)
  info.magnolia.jaas.sp.jcr.JCRAuthenticationModule requisite;
  info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;
};

sso-authentication { (2)
  info.magnolia.sso.jaas.SsoAuthenticationModule requisite;
  info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;
};

1	Optional fallback default JCR-based login authentication and authorization
2	SSO login authentication and authorization

If you don’t want to use the fallback default JCR-based login, you can disable it.

SSO module compatibility

Module version Third-party APIs tested against Released with

4.0+

Keycloak 21.1.0

See here for more on Keycloak 21.1.0.

Magnolia CMS 6.3.0

3.1.5+

Keycloak 21.1.0

See here for more on Keycloak 21.1.0.

Magnolia CMS 6.2.36

3.1+

Keycloak 21.0.1

See here for more on Keycloak 21.0.1.

Magnolia CMS 6.2.30

3.0+

Keycloak 16.1.1

See here for more on Keycloak 16.1.1.

Magnolia CMS 6.2.23

2.0+

Azure Active Directory

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

2.0+

Google Cloud Identity

1.1+

Keycloak 9.0.3

1.1+

Okta 2021.03.3+

SSO module

Installing with Maven

Prerequisites

SSO user profile information

Configuring via yaml

Field descriptions

Minimal configuration

Environment-specific configuration

Configuring a fallback login

Configuring the URL

Disabling default login

Configuring JAAS

SSO module compatibility

Location

Main doc sections