Setting up SAML Authentication on AEM

AEM provides SAML Authentication Module built-in which can be configured as Service Provider (SP) to authenticate, for instance, with your corporate Identity Provider (IdP). Please go over the terminologies of SAML for a good understanding of how the SP and IdP interacts and exchanges information using SAML protocol.

Following are the pre-requisites that you need to do or have it handy before you start configuring on the AEM Side

1. Register your Service Provider (SP) with the IdP – Service Providers needs to be registered with the IdP for the IdP to recognise the SAML request that is being sent by the Service Provider. There are two pieces of information that are typically required by the IdP for registration. Please check with your IdP Provider if they require more information :
Service Provider Entity Id – Eg. http://subdomain.yoursite.com – Used by IdP to uniquely identify the Service Provider (This information is sent by SP in the SAML Request that is sent to the IdP)
Service Provider Redirect URL – Eg. http://subdomain.yoursite.com/saml_login – IdP, upon authentication sends POSTs the SAML response to this URL. For AEM, the SAML response needs to be sent to /saml_login as the SAML Authentication Handlers seems to be written to process SAML for this specific URL pattern.

Make sure to provide this information to the folks managing the IdP before you start sending SAML Request.

2. IdP’s information – You will need to have keep few information of IdP handy to configure AEM
IdP URL – URL of the IDP where the SAML Authentication Request should be sent to (quoting AEM’s documentation) – This is where the SAML Request will be sent by AEM
IdP’s Public Certificate – This is required to sign the SAML request that is sent to IdP from the AEM. Download copy of the certificate in PEM certificate format (example idp.pem) in your local before getting started.

3. SAML Tracer Plug-in for Firefox (Optional) – This is a very handy Firefox Add-on to see the SAML Request and Response

4. Enable debug logs for the SAML Authenticate Handlers – Create new configuration under Apache Sling Logging Logger Configuration (configuration screenshot below)


Configuring SAML Authentication Handler on AEM – Its a three step process

Following configurations are done on AEM Instance, say Publisher, to enable to use SAML

1. Import IdP Public Certificate to binary property “idp_cert” on /etc/keys/saml –
Create the node structure – /etc/key/saml in the repository
Run the following command from where you have the “idp.pem” (2.2 of the pre-requisite) certificated downloaded

curl -u admin:admin -F idp_cert=\<idp.pem -F idp_cert@TypeHint=Binary http://<hostname>:4503/etc/key/saml



2. Configure Adobe Granite 2.0 Authentication Handler
Navigate to “Adobe Granite SAML 2.0 Authentication Handler” Configuration through /system/console/configMgr and provide the following configurations
Path – Provide “/” or specific URL pattern “/content/private/” – based on where you want this Authentication Handler to be applied
IDP URL – Information that you have from pre-requisite 2.1
Service Provider Entity Id – This is the same Id provided to the IdP (pre-requisite 1.1) to uniquely identify this AEM SP (Example – http://subdomain.yoursite.com)
UserID Attribute (optional) – This is useful if you would enable autoCreateUser. The exact value of this can be obtained from your IdP or can be looked at the SAML Response



3. Configure Apache Sling Referrer Filter

IdP upon successful authentication sends SAML Response to the Service Provider to the URL already provided to the IdP (ref pre-requisite 1.2). Now, the URL of the IdP which does the POST will need to be added to the Sling Referrer filter for the AEM to accept this request.

1. Edit “Apache Sling Referrer Filter” configuration from /system/console/configMgr

2. Allowed Host – Add your IdP’s hostname

That should be it on the configuration and you should be ready to go at this point..

Following are the rough sequence that can be observed in the handshake between the IdP and SP during the Authentication process

1. Hit any authenticated URL on your AEM publisher (open the SAML Tracker Firefox plug-in to observe the SAML Request being sent to the IdPURL)

2. The users browser should get redirected to the IdP Login Page

3. User keys in credentials and submits – User gets authenticated at the IdP

4. Idp redirects to the /saml_login of the AEM with the SAML response

5. AEM SAML Authenticator module intercepts the /saml_login url and extracts the userid and creates users in the repository if autoCreateUser is enabled

Debugging tips
saml.log is the key if the redirection to IdP and back is working fine and there is a failure during redirection to /saml_login. There are several checks on the SAML Authentication Handler to make sure that the SAML response is valid and the signatures match, failures or warning messages are logged on debug mode.
SAML Trace FF plug-in is key to see if your Service Provider Id etc sent from AEM is configured correctly
If IdP does not recognize the request going in from your SP one of the checks that can be done is on the IdP Certificate, make sure the key value is correct. Also, something can be incorrect on the IdP side during the registration of SP (id, redirect url).