SSO module
Edition |
DX Core |
License |
|
Issues |
|
Maven site |
|
Latest |
3.1.8 |
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
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>3.1.8</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 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 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 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
|
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 .
|
Configure via yaml
This section explains how to configure the SSO module for Magnolia 6.2.
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
path: /.magnolia/admincentral (1) callbackUrl: http://localhost:8080/.auth (1) postLogoutRedirectUri: http://localhost:8080/.magnolia/admincentral authorizationGenerators: (1) - name: fixedRoleAuthorization fixed: targetRoles: - superuser targetGroups: - publishers - name: groupsAuthorization groups: targetProperty: groups mappings: - name: superusers targetGroups: - publishers targetRoles: - superuser clients: (1) 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 userFieldMappings: (1) name: preferred_username removeEmailDomainFromUserName: true removeSpecialCharactersFromUserName: false fullName: name email: email language: locale
1 Required fields. -
Specify the
path:
where where you want to use the SSO module. Typically, this is/.magnolia/admincentral
.path: /.magnolia/admincentral ...
-
Specify the
callbackUrl
. This consists of the instance’s absolute URL (thedefaultBaseUrl
,http://localhost:8080
below) and the relative path to theSSOCallbackServlet
(/.auth
).path: /.magnolia/admincentral callbackUrl: http://localhost:8080/.auth (1) ...
1 defaultBaseURL
is the default base URL of the server root. It can be found atconfig/server/defaultBaseUrl
in Magnolia. See Configuration management. 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.path: /.magnolia/admincentral callbackUrl: http://localhost:8080/.auth postLogoutRedirectUri: http://localhost:8080/.magnolia/admincentral (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.
path: /.magnolia/admincentral callbackUrl: http://localhost:8080/.auth postLogoutRedirectUri: http://localhost:8080/.magnolia/admincentral 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 thisconfig.yaml
to use it. For more details, see Field descriptions.2 targetProperty
maps to the groups in your IDP. By default, the value isgroups
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 groupname
as shown in the example. -
Set the following under
clients:
... 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.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.id.3: 0o...x7 oidc.secret: aK...th6 oidc.authorizationGenerators.3: CustomAuthorizationGenerator (8)
1 You’ll find the id
andsecret
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
andprivate_key_jwt
.3 Defines the user data that the Magnolia instance should be allowed to request from OIDC. For more on scope
, see here. Theopenid
,profile
, andemail
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 typicallyRS256.
6 Defines the authorization generator names to use for the client as set in the authorizationGenerators
section in thisconfig.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: true (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 ispreferred_username
oremail
.2 Optional removeEmailDomainFromUserName
istrue
by default. This is a built-in formatter to remove the email domain from the name attribute (e.g.,test-user@domain.com
will betest-user
if this config is set totrue
).3 Optional removeSpecialCharactersFromUserName
isfalse
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 | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Required Describes on which path the SSO module should kick in. |
||||||||||||||||||||||||||
|
Required The URL of Magnolia’s callback servlet. This URL is made up of the instance’s absolute URL (in this case, Since SSO Module |
||||||||||||||||||||||||||
|
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.
|
||||||||||||||||||||||||||
|
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 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
The fixed role generator gives all users the same permissions.
|
||||||||||||||||||||||||||
Required A set of properties for different clients (Oidc and DirectBearerAuthClient with
http.bearer clientAn
|
|||||||||||||||||||||||||||
|
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
|
Environment-specific configuration
Available in SSO module 3.1.4 and later. |
To create environment-specific configuration files:
-
Add the
magnolia.sso.config
property to themagnolia.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.
Configure JAAS
The instance’s JAAS security setup must be edited and only contain the following:
sso-authentication {
info.magnolia.sso.jaas.SsoAuthenticationModule requisite;
info.magnolia.jaas.sp.jcr.JCRAuthorizationModule required;
};
SSO module compatibility
Module version | Third-party APIs tested against | ||
---|---|---|---|
|
Keycloak
|
||
|
Keycloak
|
||
|
Keycloak
|
||
|
Azure Active Directory
|
||
|
Google Cloud Identity |
||
|
Keycloak 9.0.3 |
||
|
Okta 2021.03.3+ |