Talks about how to integrate AEM and SAML

Article summary

Summary

Discusses how to peform single sign on by integrating SAML with Adobe Experience Manager. 

A special thank you to Nishant Gupta, an AEM community members, for submitting content used in this article.  

A special thank you to Ratna Kumar Kotla and  Navin Kaushal, for testing this article to ensure it works.

Its great community members like those mentioned here that help the overall AEM community and drives the success of AEM Developers using Adobe Experience Manager.

Digital Marketing Solution(s) Adobe Experience Manager 6.2/6.3
Audience Developer
Required Skills Java, HTML, JavaScript
Version 6.2/6.3

Introduction

SAML (Security Assertion Markup Language) is a standard technology to provide authorization information between an IdP (identity provider) and SP (service Provider). SAML is a key technology to achieve SSO (Single Sign On) as multiple SPs can validate the authentication token provided by a single IdP.

In Adobe Experience Manager (AEM) 6.x, a SAML authentication handler is provided by default. So, you do not have to write a handler for authentication. This handler provides support for the SAML 2.0 Authentication Request Protocol (Web-SSO profile) using the HTTP POST binding.

 

overview
SAML workflow

To configure the SAML Authentication Handler, you need to set these values:

  • IdP Post URL (On which the user is redirected to for one-time authentication)
  • SP ID (Your AEM instance is SP in this case).

A single IdP can have multiple SP entities and every SP entity can have a different redirect URL after successful authentication, hence it is recommended to have a SP ID. (This would be provided by the IdP entity).

Setup the identity provider

Ideally, you would not be required to setup an IdP entity as this would typically be provided to you before setup. However, to make this process clear, it is included in this article. That is, you need to setup an IdP so that we can integrate with the AEM SAML Authentication Handler.

There are multiple IdP provider that you can use. In this article, you can use https://www.ssocircle.com. To setup the IdP entity, peform these tasks: 

  1. Go to https://idp.ssocircle.com/sso/UI/Login.
  2. Click on New User.
  3. Provide the information as required and click on register.
  4. You should receive an email about account activation.
  5. Activate the account.
  6. Go to https://idp.ssocircle.com/sso/UI/Login again.
  7. Add the username and password and click on Log in.

You should see a screen that resembles the following illustration.
 

Screen!
A IdP entity

Notice a user with the name AemHELPX is used. Perform these tasks

  1. Click on Manage Metadata.
  2. Now click on Add a new Service Provider
     

See the following illustration.

Screen2
Setting up an entity provider

3. In a new tab open https://www.ssocircle.com/en/idp-tips-tricks/build-your-own-metadata/

4. Give a Unique value in entityId ( we have used AEMSAMLService in this case). This is SP Entity ID which would be used by IdP entity. Try not to use special characters as this may cause problem.

5. In the ACS URL, give http://localhost:4503/content/saml_login (This is the URL on which IdP would redirect back).

6. Click on Insert and copy the data in text area.

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="AEMSAMLService ">
   <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>
      <AssertionConsumerService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://localhost:4503/content/saml_login" />
   </SPSSODescriptor>
</EntityDescriptor>

as shown here. 

Screen3
Add XML

7. Now go back to https://idp.ssocircle.com/sso/hos/SPMetaInter.jsp page.
8. Paste the above metadata
9. Assertion attributes are sent back in SAML assertion. You may select any attribute of the below.
10. It should look like this and click on submit
 

Screen4
Setting up the identity provider

Now you have setup an IdP with an SP association (note the SP entity id value as this is required later). The handler provided by AEM is called Adobe Granite SAML 2.0 Authentication Handler. Before configuring the SAML 2.0 Authentication handler, we need to create a trust store and a Key store in AEM.

 

Creating a trust store

To create a Trust Store, perform these tasks:

1. Go to: http://localhost:4503/crx/de/index.jsp and login with admin credentials.

2. Go to: http://localhost:4503/libs/granite/security/content/useradmin.html.

3. Click on any of the users in the list. (for demo purposes, select the administrator user).

4. Go under Account Settings and press the Create TrustStore link.

5. Enter the password for the TrustStore and click Save. For the demo purpose, you can use admin as the password.

After creating the trust store, you need the IdP certificate so that the SAML Request and Response can be validated against that certificate. This would be provided by the IdP provider. However, you can use the certificate added into the zip for demo purpose.

Download

To add an IDP certificate

To add an IDP certificate, perform these tasks: 

  1. Open the user for which we created the trust store.
  2. Click on Manage TrustStore.
  3. Upload the IdP certificate. 
  4. Take note of the certificate Alias. The alias is certalias___1520408940449 in the example below then close the popup and click on save.
     
Screen5
An IDP certificate

Creating the Key Store

To create the Key Store, perform these tasks:

  1.  Go to: http://localhost:4503/libs/granite/security/content/useradmin.html.
  2. Edit the authentication-service user.
  3. Create a KeyStore by clicking Create KeyStore under Account Settings.
  4. Give the password as admin and save (the admin password is for the demo use only).

Note:

The following steps are required only if the handler is able to sign or decrypt messages.

5. Upload the Private key file by clicking Select Private Key File. The key needs to be in PKCS#8 format with DER encoding.

6. Upload the certificate file by clicking Select Certificate Chain Files.

7. Assign an Alias.

8. Close the pop up and click on save.

Configure the SAML 2.0 Authentication Handler

The next step is to configure SAML 2.0 Authentication Handler in Experience Manager by performing these steps: 

1. Go to http://localhost:4503/system/console/configMgr.

2. Open Adobe Granite SAML 2.0 Authentication Handler. It should look like the following illustration.

Screen6
Adobe Granite SAML 2.0 Authentication Handler

Now we need to add the values as per below

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    path="[/content]"
    idpUrl="https://idp.ssocircle.com/sso/idpssoinit?metaAlias=%2Fpublicidp&spEntityID=AEMSAMLService"
    idpCertAlias="certalias___1520408940449"
    idpHttpRedirect="{Boolean}true"
    serviceProviderEntityId="AEMSAMLService"
    keyStorePassword="admin"
    spPrivateKeyAlias=""
    defaultRedirectUrl="/"
    userIDAttribute="uid"
    useEncryption="{Boolean}false"
    createUser="{Boolean}true"
    addGroupMemberships="{Boolean}true"
    groupMembershipAttribute=""
    defaultGroups="mp-editors"
    nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
    synchronizeAttributes=""
    handleLogout="{Boolean}true"
    logoutUrl="https://idp.ssocircle.com/sso/UI/Logout"
    clockTolerance="{Decimal}60"
    />

The following list explains these values: 

  • path - the path on which this handler is invoked. For example, any page under the /content node is used as the path.
  • idpUrl - the URL of the IDP where the SAML Authentication Request is sent to. If this property is empty, the authentication handler is disabled. If you notice in the url, spEntityID -AEMSAMLService. Here spEntityId is the one you have created on SSO Circle IdP.
  • idpCertAlias  - this is the certificate alias you copied while uploading the IdP certificate in the trust store.
  • serviceProviderEntityId - the  sPEntityId you created on SSO Circle IdP.
  • keyStorePassword - the password you entered while createing the keystore. For example, you used admin as the password.
  • defaultRedirectUrl - the default URL where the user is taken after a successful login.
  • useEncryption - this is set to true if the handler is able to sign or decrypt messages. If this is marked as true, you need to add the certificate in the keystore.
  • createUser - this is set to True if you wish the handler to create a user on successful login. If not, then the user must exist in AEM beforehand.
  • defaultGroups - this is the default group in which the user would be added if it is being created by SAML handler. Note that default group cannot be administrator.
  • synchronizeAttributes  - if you wish to synchronize the attributes in SAML response to the user being created. 
  • handleLogout - it should be checked if the handler should logout function as well.
  • logoutUrl - the logout URL from the IDP.

We don’t need to worry about rest of the rest of the fields in the configuration. After SAML Authentication Handler is configured,you still need to perform two more configurations. 
 

Configure a Logger for SAML

You can set up an AEM Logger in order to debug any issues that might arise from misconfiguring SAML. You can do this task by performing these steps:

1. Go to the Web Console, at http://localhost:4503/system/console/configMgr.

2. Search for and click on the entry called Apache Sling Logging Logger Configuration.

3. Create a logger with the following configuration:

  • Log Level: Debug
  • Log File: logs/saml.log
  • Logger: com.adobe.granite.auth.saml

Configure Apache Sling Referrer Filter for IdP

Perform these steps: 

1. Go to the Web Console, at http://localhost:4503/system/console/configMgr.
2. Search for and click on the entry called Apache Sling Referrer Filter Configuration.
3. Select the Allow Empty check box
4. Add URL of IdP in allowed Hosts. In this example, it would be idp.ssocircle.com.
5. It should look like the following illustration. 
 

Screen7
Apache Sling Referrer Filter Configuration

Note:

Now we are done with the AEM SAML Setup.

Defining Closed User Group for a page

Define the AEM page on which this handler is invoked. For this article, the the geometrixx-outdoors  page is used. Perform these tasks: 

1. Go to http://localhost:4503/editor.html/content/geometrixx-outdoors/en.html.

2. Open Page Properties.

3. Go to the Advanced Tab.

4. Check the Closed User Group checkbox. 

5. Under the Admitted Group give the same group you have given in your SAML 2.0 Authentication Handler. For example, use mp-editors.

Note:

If geometrixx-outdoors is not installed, you can download it from Package Share. 

Screen8
Set Closed Group information

Note:

If you are using AEM 6.3, the Closed User Group configuration is under the Permission tab. 

6. Click on Submit.

Now you have setup the AEM SAML integration and it's ready for testing.

Testing SAML AEM Integration

Test the SAML integration by performing these tasks: 

1. Open a new browser in which you have not logged in.

2. Open the URL http://localhost:4503/content/geometrixx-outdoors/en.html.

3. It redirects you to the IDP Website. 

4. Use the credentials you used while registering on the SSO Circle to log in to the IDP.
 

Screen9
The IDP Website

5. Once Logged In, it asks for Captcha (This is for SSO Circle only as this might vary from IdP to IdP).

6. After entering the Captcha, click on Continue to Single Sign On. It would look like this.

Screen10
A Captcha

7. It will redirect the user to http://localhost:4503/content/geometrixx-outdoors/en.html.

Congratulations. Your AEM integration with SAML Setup has been done.

See also

Join the AEM community at: Adobe Experience Manager Community

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy