External User Management and SSO with Magnolia

On average, enterprises are using well over 100 apps, and the handling of user accounts for those various applications can become challenging for users and admins alike. Managing accounts and permissions in different systems also isn’t ideal from a security perspective. Therefore, many enterprises require single sign-on (SSO) across their IT landscape.

SSO is an authentication service that allows users to access multiple applications using the same login credentials. Setting SSO up for Magnolia means integrating a centralized user pool that is governed by the authentication solution. This is especially important for Magnolia author instances because content and experiences are created and managed here.

You can also take advantage of SSO to enable existing user pools to access resources such as your website, for example by using social logins from social network providers like Facebook, Twitter, and Google.

Consider the following benefits of using single sign-on with Magnolia:

Magnolia’s LDAP and CAS modules could be considered a precursor of SSO. While they are still valid options in traditional corporate environments and on-premises installations, the demand for a different kind of solution emerges as today’s technology is shifting to flexible and transparent cloud services.

This article will explain SSO and extended authentication features in Magnolia and examine the options to integrate external user pools.

Magnolia’s security is based on JAAS, which stands for Java Authentication and Authorization Service. The below is an excerpt from Magnolia’s documentation:

JAAS provides a standardized way for:

You can adjust the usage of JAAS in the configuration of a Magnolia web application bundle by editing the file .../WEB-INF/jaas.config. It allows you to define simultaneous login types for a Magnolia instance, for example, LDAP, Azure AD, and local user accounts.

Magnolia checks whether a user has the required permissions before granting access to resources such as web pages, documents, templates, or other data types.

For more information, please check Magnolia’s security documentation and the configuration of JAAS-based logins.

Security objects and components in Magnolia include users, groups, roles and login modules. All of the above are derived from a common code base, but you can replace them with other login modules or change their configuration.

New login modules can leverage Magnolia’s core security architecture while offering additional capabilities to integrate external authentication providers.

This elegant approach makes it possible to enable external user management without changing Magnolia’s core code and doesn’t risk breaking compatibility with future Magnolia releases, nor does it require maintaining a custom codebase.

Magnolia offers various modules to handle user authentication through a third-party system.

The LDAP Connector module enables authentication against an LDAP server. It is used in corporate environments where LDAP authentication is the standard. This includes environments that rely on Microsoft’s popular directory service Active Directory (AD).

CAS is an open-source Java server component by the Apereo Foundation. It provides a single sign-on (SSO) solution for the web. Besides implementing the CAS protocol, it also supports the SAML, OAuth, and OpenID protocols. In addition, it transparently integrates other authentication services.

Magnolia’s CAS module requires the LDAP Connector module as a prerequisite. When implementing a CAS solution, in-depth knowledge of Java servers and their operation should be available.

Magnolia provides a flexible SSO module based on the OAuth and OpenID Connect (OICD) protocols and their respective authentication flows. The setup includes registering Magnolia as a client and providing configuration details such as the client ID and secret, as well as the callback URL.

In contrast to the LDAP Connector and CAS modules above, the Magnolia SSO module uses the OAuth and OpenID Connect (OIDC) protocols.

When integrating Magnolia with an external authentication solution only the protocols are relevant. Both systems have to be able to communicate in a common language, i.e. the protocol. In the past, there has been the wrong assumption that specific Keycloak libraries have to be used with Magnolia SSO. This is not the case: Magnolia SSO is not tied to one particular product or library. It can leverage any user authentication that adheres to the OAuth/OIDC protocols' standard. Though for some use cases - like parsing of group/role information or the re-use of tokens - it might be necessary to adjust the SSO module’s code.

For a better understanding, we’ll explain the supported protocols here.

OAuth 2.0

According to the Internet Engineering Task Force (IETF) “the OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.”

OAuth 2.0 has established itself as the standard for authorization of API access on the web because it’s simple, secure, and supports many types of applications - ranging from portals to applications running on various devices.

The purpose of OAuth 2.0 is authorization: granting access from one application to another to use data or features without having to deal with the original authentication. OAuth 2.0 is not an authentication protocol; it does not deliver a user id or extended information about a user. Most of the social network providers that offer login services to sign in to 3rd-party applications - like Gmail, Facebook, and Twitter - use the OAuth protocols.

OpenID Connect (OIDC)

Unfortunately, the purpose of OpenID Connect (OIDC) is often misunderstood because it is confused with the former OpenID standard that provides a decentralized authentication protocol. OpenID not related to OAuth and is not supported by Magnolia.

OpenID Connect, however, is a layer on top of OAuth 2.x that allows clients to verify a user's identity. It adds profile and login information about the logged-in user account.

In short, OIDC enables logins to be used across several applications, which is the purpose of SSO. Magnolia recommends using OIDC over OAuth 2.0 whenever possible, especially when enabling access to Magnolia AdminCentral. Most enterprise authentication solutions support OIDC in addition to other protocols.

Solutions supporting OIDC are often called an identity provider because they provide information about the user’s identity. Examples of identity providers are Azure Active Directory (Azure AD), Auth0, AWS Cognito, Keycloak, and Okta.

SAML is a secure and robust protocol that is supported by some authentication servers. The downside is that SAML is dated and doesn’t meet the needs of modern applications. In addition, the underlying standards for XML signatures are complex, and managing X.509 certificates in production environments is cumbersome.

Magnolia has therefore decided to focus development on the modern OAuth 2.0 and OpenID Connect protocols. Consequently, this means that we don’t support SAML directly.

To set up SSO for Magnolia, it has to be configured as a client with the authorization service.

To identify Magnolia as a valid client, Magnolia receives a client ID and a client secret, sometimes called app ID and app secret.

You also have to define one or more callback URLs, also known as redirect URIs. These URLs are used by the authentication system to “call back” Magnolia after a successful login.

The OAuth 2.0 standard supports several types of “flows”; the most common is the “authorization code flow” used by Magnolia SSO modules. The flow for OIDC and OAuth 2.0 are almost identical. The OIDC flow includes the OpenID scope in the initial request and issues an ID token in addition to the OAuth 2.0 access token.

Magnolia then grants permissions to external users based on the user’s roles. Magnolia does not save an external user. It only exists in memory until a user logs out or the session expires.

1. A user wants to allow Magnolia to retrieve information like the username, language, group, and role memberships from an authorization server to enable Magnolia to compile the user’s permissions to access resources such as AdminCentral or a protected website.

2. Magnolia redirects the user’s browser to the authorization server. The redirect contains the following parameters: client ID, callback URL, response type, and the scopes, including OpenID.

3. Unless the user has previously logged in, the authorization server won’t find an active session for the user. It prompts a login and verifies the user's identity. If configured, this process leverages multi-factor authentication.

4. Depending on the scopes requested by Magnolia, the server asks for the user’s consent.

5. The authorization server then redirects to Magnolia using the callback URL and the authorization code.

6. When Magnolia receives the authorization code via the callback URL, its backend contacts the authorization server via a secure connection. It transmits the authorization code, the client ID, and the client secret.

7. The authorization server verifies the information and, if correct, responds with an access token and ID token via the secure connection.

8. Once Magnolia receives the tokens, it can use the access token as a key to query user information from the resource server. Depending on the authorization server’s configuration, the information might already be included in the ID token (see below for token types).

9. Magnolia creates a user object based on the username and ID it received. Additional attributes like the user’s email and language are assigned if available.

If the authorization server provides roles and groups, Magnolia matches their names with local roles and groups in its backend. If a role or group does not exist in Magnolia, it is ignored. If the authorization server doesn’t provide roles and groups, Magnolia applies default roles and groups from the SSO configuration to the user object.

Magnolia uses an access token as the key to query a user’s data on the resource server. The resource server checks the token to verify if Magnolia is allowed to access the requested resource. While the token is a critical part of the flow, its contents are irrelevant to Magnolia. OAuth 2.0 and OpenID Connect use access tokens in their flow.

The OIDC flow also uses an ID token. Its payload has the format of a JSON Web Token (JWT) and the payload’s contents are known as claims. Magnolia parses the claims using a decoder.

In addition to the basic user information, an ID token often also contains information such as an expiration date and the token issuer. Beyond this, the authentication server can add information such as the user’s roles to the payload making the exchange of data more efficient.

Magnolia can request additional information from the resource server by using the access token.

When testing or debugging, you can examine an ID token's content with services like https://jwt.io/ or https://jwt.ms/.

The OpenID Connect standard offers a plethora of features to use with Magnolia. The SSO modules can leverage these features if the authentication solution supports them.

Multi-factor Authentication

SSO outsources user authentication to an authentication server. It is therefore transparent to Magnolia. If the authentication server supports multi-factor authentication, Magnolia can benefit from it.

When logging into Magnolia, a user is redirected to the authentication server and only returns to Magnolia after a successful login. The authentication process and the steps involved are irrelevant to Magnolia, even if sending smoke signs were required as part of the authentication.

This is also true for logins using your social network accounts. If you enabled two-factor authentication (2FA) in your Google account settings, all services using Google Sign-In would require you to complete 2FA - unless you already have an existing session with the provider.

Seamless Device Integration

Many users have more devices than just a desktop or laptop. They like to switch between devices without the hassle of entering login data over and over again. Authentication solutions can identify devices by their hardware id and assign them to known users in an organization. If a user has already logged in to a desktop computer, the authentication server can identify a request from a registered device as coming from the same user and grant access without logging in again.

Integration Hub

Magnolia modules support LDAP, CAS, OAuth, and OpenID Connect. You can use any authorization solution that speaks one of the protocols to act as a transparent “integration hub” to manage different types of user pools. Integration hubs eliminate the need to implement different authentication protocols.

For example, Keycloak can integrate many types of user databases including LDAP, SAML and social logins, enabling Magnolia to retrieve users from their user pool.

A typical Magnolia installation consists of one author instance and at least two public instances. In technical terms, we can distinguish between backend (author) and frontend (public) access. For both types of Magnolia instances, it makes sense to enable external users, though the use cases are different.

Imagine an area of a website that is protected from anonymous access and requires a login, for example, a member or customer portal. This is a common requirement that is covered by the Public User Registration (PUR) module. The module also provides account registration and management. PUR logins are stored in Magnolia’s database and cannot be re-used by services outside of Magnolia.

Many websites and portals provide authentication via social network providers as an option to lower the barrier to access. By using the Magnolia SSO module, you can easily integrate with most popular social networks through configuration. When working with social logins, it’s important to keep in mind that they usually don’t provide extended user information like group or role memberships.

When restricting access to an area of your website this is typically not a problem because it is used for a predefined use case. You can define default roles and groups for users who successfully authenticate through a social login.

The downside of this approach is that Magnolia cannot distinguish between different types of users. Having different roles and groups requires a more sophisticated authentication solution like Azure AD or Keycloak.

When enabling SSO for users of a Magnolia author instance, it is essential to assign roles to different categories of users such as editors, publishers, and superusers. You can use Magnolia’s LDAP Connector and CAS modules to integrate with authentication solutions for centralized user management.

The Magnolia SSO module can integrate with any authentication solution that adheres to the OpenID Connect protocol standard and their authorization code flow. You can use these services to retrieve group and role information by parsing the data provided by the authentication server.

It does not make sense to use social logins to manage access to Magnolia author instances because they do not provide roles and groups.

A few years ago, Magnolia Professional Services developed code to allow OAuth logins for a customer’s website. We subsequently developed a module to enable OAuth-based logins - the SSO module described above.

We made it available to customers through our incubator and later extended the module to support the OpenID Connect protocol. The module has proven to be quite successful and is used in many enterprise projects implementing various authentication services.

Because of the high demand, Magnolia started to develop a new SSO module that uses a more powerful library, PAC4J. The new module will support the OpenID Connect protocol and be a good fit for modern cloud environments.

The basic implementation is ready and we are in the process of testing advanced use cases. In the meantime, you can use our SSO, LDAP Connector, and CAS modules. If you are interested in additional features, watch out for more articles about the new SSO module as its development progresses.