AEM Single Sign-On (SSO) using JumpCloud

User experience begins with sign-in process. In today’s digital world we use many applications (at our workplace and outside). Remembering passwords and/or reauthenticating every time we access these applications within same provider ecosystems is not a desirable user experience. 

 

Many of us use google applications (Gmail, Google drive, YouTube etc.) and if you must sign-in again-and-again to access these applications then I am sure you’ll not be very happy. And yes, there is a chance that you may forget password as well.

 

At your workplace you may have timesheet application, payroll application and many other. If you sign-in only once and can access all other application without having to sign-in again then you are lucky, SSO implemented at your workplace.

 

What is Single Sign-On?

Single Sign-On allows users to authenticated themselves once and auto-login to multiple applications (that talks to same identity provider) without reauthenticating. If you are not sure what is Identity Provider (IdP), stay with me, I’ll cover that later shortly.

 

Here are key terms that you should be aware of while learning about Single Sign-On (SSO):

 

• Identity/principal – this is the actual user (credentials) in a database (e.g., an Active Directory)
• Identity Provider (IdP) - An identity provider is a system entity that creates, maintains, and manages identity/authentication information for principals and also provides authentication services to reliant applications within a federation or distributed network. Identity providers offer user authentication as a service. In this article, we’ll use JumpCloud as our Identity Provider (IdP)
• Service Provider - A Service Provider (SP) is the entity providing the service, typically in the form of an application. In this article, AEM is our Service Provider.
• Trust Store/Signing Certificate - SSO works based upon a trust relationship set up between Service Provider (SP) like AEM, and an identity provider (IdP), like JumpCloud. This trust relationship is often based upon a certificate that is exchanged between the identity provider and the service provider. This certificate can be used to sign identity information that is being sent from the identity provider to the service provider so that the service provider knows it is coming from a trusted source.
• Security Assertion Markup Language (SAML) – it is an XML based open standard to exchange authentication information between Identity Provider (IdP) and Service Provider (SP). SAML request and response entities must follow defined standards while exchanging information.

 

SSO Authentication can be initiated by Identity Provider (IdP-initiated) or Service Provider (SP-initiated).

 

• A Service Provider Initiated (SP-initiated) sign-in is initiated by the Service Provider. This is typically triggered when the end user tries to access a resource or sign in directly on the Service Provider side, such as when the browser tries to access a protected resource on the Service Provider side.
• An Identity Provider Initiated (IdP-initiated) sign-in is initiated by the Identity Provider. Instead of the SAML flow being triggered by a redirection from the Service Provider, in this flow the Identity Provider initiates a SAML Response that is redirected to the Service Provider to assert the user's identity.

 

In this article we’ll look at detailed steps to configure AEM SSO authentication handler (which is a SAML based authentication handler).

 

How Single Sign-On (SSO) works?

 

The login flow usually looks like this:

 

1. A user tries to access a secured resource (web page, video etc.) on Service Provider (SP) site
2. The Service Provider sends a token that contains some information about the user, like their email address, to the Identity Provider, as part of a request to authenticate the user.
3. The Identity Provider first checks to see whether the user has already been authenticated, in which case it will grant the user access to the Service Provider application and skip to step E.
4. If the user hasn’t logged in, the user will be prompted to do so by providing the credentials required by the Identity Provider. This could simply be a username and password, or it might include some other form of authentication like a One-Time Password (OTP).
5. Once the Identity Provider validates the credentials provided, it will send a token back to the Service Provider confirming a successful authentication.
6. This token is passed through the user’s browser to the Service Provider.
7. The token that is received by the Service Provider is validated using the trust relationship that was set up between the Service Provider and the Identity Provider during the initial configuration.
8. The user is granted access to the Service Provider

 

Authentication options in AEM 

Let’s first look at various options available in AEM for configurating authentication.

 

AEM has a robust security implementation (based on Sling Authentication). The Sling Authentication is a complete framework, and it provides foundation for implementing different type of authentication schemes. AEM leverages Sling Authentication framework and support multiple authentication methods out-of-the-box (OOTB). Based on whether users are getting authenticated against the AEM user repository or an external identity provider we can divide the authentication implementation in 2 groups (as follows):

 

Authentication	AEM 6.3	AEM 6.4	AEM 6.5
AEM as Identity Provider
Basic authentication	✔	✔	✔
Forms-based	✔	✔	✔
Token-based (w/ encapsulated token)	✔	✔	✔
Non-AEM system Identity Provider
LDAP	✔	✔	✔
Single Sign-On SSO	✔	✔	✔
SAML 2.0	✔	✔	✔
OAuth 1.0a & 2.0	✔	✔	✔
OpenID	⁕	⁕	*

 

As we discussed above, we’ll be using a cloud-based directory service called as JumpCloud. You may want to create a free JumpCloud cloud account to follow along this tutorial.

 

Link to JumpCloud: https://jumpcloud.com/pricing

 

Prerequisites to follow this step-by-step tutorial:

• An AEM instance (let’s say author is running on http://localhost:4502/)
• JumpCloud account (either free/trail or paid)

 

There are 4 main steps to configure AEM SSO handler:

1. Configure Identity Provider (in this case JumpCloud SSO/SAML) to work with AEM. To do this, we need to create an SSO application on Identity Provider (IdP) and get the certificate and other details required to SSO handler in AEM
2. Create a Global Trust Store in AEM and import IdP certificate
3. Create Keystore for “authentication-service” user in AEM
4. Configure “Adobe Granite SAML 2.0 Authentication Handler”. We we’ll also create a user group in AEM (e.g., jumpcloud-sso) so that after successful SSO authentication users (from JumpCloud) will get added to this group.

 

Time for action! Let’s perform each of these steps one by one.

 

Step 1: Configure JumpCloud SSO/SAML to work with AEM

• Login to JumpCloud (please create an account first if you don’t have one): https://console.jumpcloud.com/login/admin
• Create a user group “AEM Administrator”

 

 

• Create a user and add it to “AEM administrator” group create in previous step

 

 

• Navigate to SSO console for creating SSO application: https://console.jumpcloud.com/#/sso

 

• Click on “+” sign to create new SSO application

 

 

• Click on “Custom SAML app”

 

• Provide a name for your application (e.g., AEM Local)

 

 

• Click on “SSO” Tab. Fill in the details as follows and click on “activate” button on right-bottom corner

 

 

 

• Once SSO application is activated, we need to download the certificate from JumpCloud and import it in AEM (we’ll import it later). Go to the newly created SSO app and download certificate

 

At this point we are done with creating an SSO application in JumpCloud. We also have required certificate that we’ll use in next step.

 

Step 2: Create a Global Trust Store in AEM and import IdP certificate

• In AEM, go to Tools > Security > Trust Store
• Click “Create Trust store” if one doesn’t exist already. Provide a password (in this case, I am going to use “admin”)
• Click “Select Certificate File”, upload certificate (downloaded from JumpCloud) and map it against a user. You can map it against any user because the Trust Store in AEM is Global
• Copy or make note of certificate alias, we would need it for SAML configuration in step 4 (later in this article)

 

Once everything is configured, you should have a screen as follows:

 

 

Step 3: Create Keystore for “authentication-service” user in AEM

• In AEM, Go to Tools > Security > Users
• Search for “authentication-service”
• Create keystore. Provide a password (e.g., admin). Make note of this password as we’ll need this password when we are configuring SAML authentication handler in Web/OSGi Console.

 

 

 

• We would need to configure the same password in the next step for SAML config

 

Step 4: Configure “Adobe Granite SAML 2.0 Authentication Handler”

• In AEM, go to Tools > Operations > Web Console
• Click to add a new config for “Adobe Granite SAML 2.0 Authentication Handler”
• Add the configurations gathered from JumpCloud (see screen shot below). The description about each field can be found on link. You can learn more about the configuration parameters here: https://experienceleague.adobe.com/docs/experience-manager-65/administering/security/saml-2-0-authenticationhandler.html

 

If you have followed the exact steps as outlined in this article then, you can use the values shown in above screen shot else adjust is based on actual values that you have used.

 

Important notes about SAML 2.0 Authentication Handler configuration:

• The “Path” configuration tells AEM at which path this SSO handler should be invoked. In this case when user will try to access http://localhost:4502/content/wknd-spa-angular.html the user will be redirect to IdP (JumpCloud) for authentication. This path can be any path under “/content” path of AEM.
• The “IDP Certificate Alias” is the value that we got in Step 2 (while configuring “Global Trust Store”)
• The “Service Provider ID” should match with the “SP Entity ID” that we have configured in JumpCloud while creating SSO application (see Step 1 above)
• The “Password of key store” is the password that we have provided while creating “Keystore” in previous step (I have used “admin” as password).
• The “UserID attribute” configuration instructs authentication handler to look for this attribute in IdP response to identify the authenticated user
• The “Synchronize Attributes” configuration mapping tells SSO authentication handler to map the attributes of JumpCloud user to AEM profile.

 

If you run into “Forbidden 403” error, please update “Apache Sling Referrer Filter” as follows:

 

 

At this point everything is configured, and it is time to do the test drive!

 

Let’s do a test:

• Navigate to http://localhost:4502/content/wknd-spa-angular.html (or to the path you have configured SSO authentication handler configuration)
• If user not authenticated already, JumpCloud will ask the user to enter credentials

 

 

• After successful authentication, the user will be redirect back to AEM

 

Additional Configuration needed on AEM Publish

 

On AEM publish instance content is by default accessible without any login requirements (using anonymous user).  To force login for specific paths, we need to configure it in the Sling Authentication Service by adding new authentication requirements.

 

 

I hope you have gained good understanding of SSO and how it works in AEM.

Feel free to comment if you have any question or suggestions.

If you run into issues while configuring SSO/SAML with AEM refer this page (for common issues):

https://www.albinsblog.com/2018/05/exceptionsissues-while-configuring-aem-saml-authentication-handler.html