SSO module
Edition |
DX Core |
License |
|
Issues |
|
Maven site |
|
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 version is managed by the parent POM, 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 |
---|---|
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 |
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. |
a Group Membership mapper |
required By convention, this is required in order to include the user’s groups in the
|
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:
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 | |||||
---|---|---|---|---|---|---|
1 |
|
required Describes on which path the SSO module should kick in. |
||||
2 |
|
required The URL of Magnolia’s callback servlet. This URL is made up of the instance’s absolute URL (in this case,
|
||||
3 |
|
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.
Property defined
Jane is working on Property not defined
Jane is working on |
||||
4 |
|
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. |
||||
|
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:
|
|||||
5 |
|
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. |
||||
6 |
|
required Name of the OIDC client that is configured to allow the Magnolia instance to access the IAM instance.
|
||||
7 |
|
required Secret created by the IAM instance when the client is created. |
||||
8 |
|
required Defines the user data that the Magnolia instance should be allowed to request from OIDC.
|
||||
9 |
|
required The IAM instance’s auth endpoint URL. This must be tweaked according to your project. |
||||
10 |
|
required The JWS algorithm that is going to be used by pac4j. We recommend |
Configure JAAS
The instance’s JAAS configuration (see JAAS security set up) must be edited and only contain the following:
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
|
||
2.0+ |
Google Cloud Identity |
||
1.1+ |
Keycloak 9.0.3 |
||
1.1+ |
Okta 2021.03.3+ |