SSO module

Edition

DX Core

License

MLA

Issues

MGNLSSO

Maven site

SSO

Latest

2.0.6

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.

If you use Java 8 at runtime, please note that pac4j 4.x is no longer maintained. Because of this, you may not receive security fixes.

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.

Installing with Maven

Bundled modules are automatically installed for you.

If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section. If the module is unbundled but the parent POM manages the version, add the following to your webapp’s <dependencies> section.

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

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

Configuration

Prerequisites

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

Prerequisite	Description
a user	required Its username and password are used to access Admincentral. It should have names as well as an email.
a group	required 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	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 in order for Keycloak 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 permission, and hence won’t be able to go past the login screen. Here’s how to configure the mapper in various applications:

a user

required

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

a group

required

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

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 in order for Keycloak 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 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

This section explains how to configure the SSO module. This is most easily done with a YAML decorator.

From a light module, use the following path structure:

<MODULE_NAME>/decorations/magnolia-sso/config.yaml

authenticationService:
  path: /.magnolia/admincentral (1)
  callbackUrl: http://localhost:8080/.auth (2)
  postLogoutRedirectUri: http://localhost:8080/.magnolia/admincentral (3)
  authorizationGenerators: (4)
    groupsAuthorizationGenerator:
      class: info.magnolia.sso.oidc.GroupsAuthorizationGenerator
      mappings:
        /magnolia-sre:
          roles:
            - superuser
          groups:
            - publishers
        /magnolia-publishers:
          roles:
            - travel-demo-publisher
          groups:
            - publishers
  pac4j: (5)
    oidc.id: magnolia-sso (6)
    oidc.secret: 2ff75b44-c7ef-4932-91c8-59e6ea5f35b6 (7)
    oidc.scope: openid profile email (8)
    oidc.discoveryUri: https://<YOUR_OIDC_IDP_DOMAIN>/…/.well-known/openid-configuration (9)
    oidc.preferredJwsAlgorithm: RS256 (10)

Property Description

path

required

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

callbackUrl

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.

postLogoutRedirectUri

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.

authorizationGenerators

required

List of configured authorization generators. An authorization generator serves as a pac4j API entry point to allow generation of authorization based on a user profile.

Multiple generators can be configured. Two generator classes are available out-of-the-box. You can also provide your own implementation.

<generator>

required

Node specifying the properties of a generator. The node name is arbitrary.

The properties that can be configured are class-dependent. The following generators are available out-of-the-box:

Fixed Role Generator

The class name is info.magnolia.sso.oidc.FixedRoleAuthorizationGenerator.

It 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.
```
fixedRoleAuthorizationGenerator:
  class: info.magnolia.sso.oidc.FixedRoleAuthorizationGenerator
  roles:
    - superuser
  groups:
    - …
```

Groups Generator

The class name is info.magnolia.sso.oidc.GroupsAuthorizationGenerator.

Use this generator 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.

groupsAuthorizationGenerator:
  class: info.magnolia.sso.oidc.GroupsAuthorizationGenerator
  mappings:
    /magnolia-sre:
      roles:
        - 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.

groupsAuthorizationGenerator:
  class: info.magnolia.sso.oidc.GroupsAuthorizationGenerator
  mappings:
    ea0b1d9f-c8fc-4b99-9f76-8a92abbbb496: # sysadmins
      roles:
        - superuser

pac4j

required

Properties to be forwarded to the pac4j library in order to build a configuration that can then be used by the library. See pac4j’s page on the configuration module for more details.

oidc.id

required

Name of the OIDC 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.

oidc.secret

required

Secret created by the IAM instance when the client is created.

oidc.scope

required

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.

Azure users: For users that implement refresh tokens with Azure, you can add the offline_access scope as well.

This means the session will not expire even when the session TTL has been reached.

...
  pac4j:
  ...
    oidc.scope: openid profile email offline_access
  ...
...

oidc.discoveryUri

required

The IAM instance’s auth endpoint URL. This must be tweaked according to your project.

oidc.preferredJwsAlgorithm

required

The JWS algorithm that is going to be used by pac4j. We recommend RS256 because it has broad support, but this can be changed here. You can find more details in the following algorithm selection guide.

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

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

Configuration

Prerequisites

YAML configuration

Configure JAAS

Module compatibility

Location

Main doc sections