How to Configure Security Assertion Markup Language (SAML) for Adobe Experience Manager

Security Assertion Markup Language (SAML) simplifies federated authentication and authorization processes for users, identity providers, and service providers. It is an open standard and is often used to provide single sign-on to web-based applications. The protocol is used for authentication and providing authorization information. The SAML protocol has three entities: User-agent, which typically is the user's web browser, service provider (SP), the application you are trying to access, and the identity provider (IDP), the application that manages access to your various service providers.

When configuring SAML, we have to establish a trusted relationship between SP and IDP. A user who wants to access an SP must first authenticate into the IDP. If the user manages to authenticate successfully and is authorized, the IDP generates a SAML assertion that is sent to the application, and since the application trusts IDP, the user is allowed access. Since the user is already authenticated into IDP, the user can then use single sign-on to access other applications managed by the IDP.

How is it Done in Adobe Experience Manager?

Adobe Experience Manager (AEM) can use the SAML standard to exchange authentication and authorization data with an IDP service. It enables a web-based cross-domain single sign-on (SSO) and a single logout (SLO). In this case, the SAML standard would define AEM as the Service Provider (SP) and the 3rd party identify solution as the Identity Provider (IDP). 

Beyond the Documentation

Understanding SAML required and optional configuration

Without the following properties the handler will be disabled/non-functional:

• Path
• IDP URL
• IDP Certificate Alias
• Service Provider Entity ID

The rest of the configuration values are optional in IDP-initiated authentication, but for SP-initiated you’ll also need:

• SP Private Key Alias
• Password of Key Store

The ‘Handle logout’ & ‘Logout URL’ fields in the configuration are optional and can be set up if the IDP supports Service Provider initiated log out. The details on how to use this feature can be found here.

SAML On-Prem with Multiple Publish Instances

If your system design contains a Load Balancer that supports sticky sessions, it can be useful to have a 1-1 mapping of publisher to dispatcher and leverage the sticky sessions at the load balancer level. This will enable your session to be managed on a single publish/dispatcher pair.

If your Load Balancer doesn’t support sticky sessions then you’ll likely need to do one of the following:

• Set up your dispatchers to have all the publish instances listed as renders and enable sticky sessions on the dispatcher
• Enable Encapsulated Token support on all publish instances
  • Note: all publishers will need the same HMAC key to ensure they can correctly read the token values
  • User replication across all publish instances as the SAML Authentication Handler adds the new user and the Apache Sling Distribution Agents - Sync Agents Factory replicates it to the other publisher

Personalization with SAML Attributes

When the service provider is connected to an identity provider via SAML, the data sent can be enriched by choosing users’ attributes and profiles. Some examples of this are displaying first-name & last-name on the home page or the profile page. This configuration is done on the identity provider side to set custom attributes, and on the AEM side, we can map the attributes to a relative node in the JCR under the user node. Avoid transmitting PII in the authentication response, and additionally, assertions can be encrypted to prevent disclosure of attributes during transportation.

Using Multiple Identity Providers and Multiple SAML Configurations

The way AEM will choose which SAML configuration to use is based on two things. The repository path configured and the service ranking. If two configurations exist on different paths there will not be a collision. However, if two configurations exist on the same path, the service ranking will decide which to use. 

For particular use-cases, where the authentication in the first IDP is failed, the authentication in the second IDP must be done; the ideal solution would be to create a custom SAML authentication handler.

User Group Considerations

The configuration for the list of groups in CRX that the user should add on authentication in AEM can be identified by configuring the “groupMembershipAttribute'' value. This attribute is set in the identity provider, and if an application supports the configuration of multiple IDPs, we can configure specific permissions per group. If choosing not to synchronize the groups from the identity provider, the SAML configuration on AEM allows us to add the user to a default group or groups. In line with the “createUser” property, this allows auto-created non-existing users in the repository and adds them to the group considering appropriate permissions are set for these groups. The groups need to exist in AEM for a user to be added to them. Unlike the users, the groups are not automatically created. Ideally, these groups can be defined as “Closed User Groups” to restrict access to specific pages and require users to be authenticated to access the site. 

SAML Assertion Encryption

Encrypting the SAML assertion is optional. In most situations, it is not encrypted, and privacy is provided at the transport layer using HTTPS. It is an extra level of security that's enabled if the SAML assertion contains sensitive user information.

Common Errors and Solutions

• “Invalid SAML Token” – This can happen if the login URL defined in the IDP is different from the Service Provided Entity ID defined in the SAML Authentication Handler configs. By capturing the SAML response and decoding it (if encrypted on the IDP), the <saml2:Audience> attribute value should match the Service Provided Entity ID in the configuration
• “Signature Verification failed/Signature Invalid” – This could be an issue with the keys saved in the Keystore and could require a reconfiguration. It could also be with the certificate saved in the truststore. Delete the existing cert and re-upload it

AEM SAML authentication handler is effortlessly configurable and can be integrated with many popular identity providers that support using the SAML protocol.

Please find additional resources specific to SAML below:

SAML 2.0 Authentication Handler