AEM & SAML: Detailed Installation and Config. (LDAP and Identity Provider)

In this article we’ll see end-to-end setup and configuration for:

1)      Local LDAP Server

2)      Shibboleth2 (as Identity Provider aka IdP)

3)      Configure AEM as Service Provider and do SSO login with SAML using Shibboleth 2

Before even getting into the installation and too many technical details let’s first try to understand what is SMAL and Idp.

Security Assertion Markup Language (SAML) is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider (Idp i.e. Shibboleth in our case) and a service provider (SP, i.e. AEM in our case). The SAML specification defines three roles: the principal (typically a user), the Identity provider (IdP), and the service provider (SP). In the use case addressed by SAML, the principal requests a service from the service provider. The service provider requests and obtains an identity assertion from the identity provider. On the basis of this assertion, the service provider can make an access control decision – in other words it can decide whether to perform some service for the connected principal.

Before delivering the identity assertion to the SP, the IdP may request some information from the principal – such as a user name and password – in order to authenticate the principal. SAML specifies the assertions between the three parties: in particular, the messages that assert identity that are passed from the IdP to the SP. In SAML, one identity provider may provide SAML assertions to many service providers. Similarly, one SP may rely on and trust assertions from many independent IdPs.

Systems Requirements (I am assuming that you’ll be trying below installation on a windows machine):

·         Make sure that you have java installed on your machine and JAVA_HOME is set.

Assumptions:

1)      INST_HOME: create a directory called “installation” anywhere on your computer and in this article we’ll refer this directory as INST_HOME.

2)      IdP_HOME: this is the directory where Shibboleth will be installed.

3)      TOMCAT_HOME: directory where tomcat is installed.

Few Terms that you should be familiar with to understand this tutorial better:

1)      IdP or Identity Provider (e.g. Shibboleth): Identity provider is centralized system which is responsible for connection with user database (RDMS, LDAP etc.), retrieving and supplying user/principal information to Service Providers. Once IdP can server more than one service provider.

2)      Service Provider (SP, e.g. AEM): delegates the task of user authentication and management to IdP. In some cases,  a Service Provider may contact multiple IdPs to do user authentication.

3)      Attributes: When we are talking about SAML, IdP and Service Provider then attributes are mainly related to user or organization attributes (e.g. name, empID, group, mail etc.) that IdP fetches from user database.

4)      Relying Party: In nearly all cases an IdP communicates with a service provider. However, in some more advanced cases an IdP may communicate with other entities (like other IdPs). The IdP configuration uses the generic term relying party to describe any peer with which it communicates. A service provider, then, is simply the most common type of relying party.

Let's begin installation!!!

1.       LDAP Installation: We need to install a LDAP server and we’ll also need a LDAP data browser so that we can see user, groups etc.  Please refer this tutorial “Local LDAP Installation” to see full instruction on how to install LDAP server step by step. If you are not following LDAP installation that I have recommended then please note that you’ll need to update LDAP configuration in “login.config” and “attribute-resolver.xml” files (that we’ll see later in this tutorial) based on your LDAP installation.

Step 1: Download Required Software

Apache Directory: https://directory.apache.org/apacheds/downloads.html

Apache Directory Studio RCP Application (for connecting to LDAP server and looking at records): https://directory.apache.org/studio/downloads.html

Installation of software mentioned above is self-explanatory and you just have to follow the instructions on screen.

Step 2: Import Sample User Data for LDAP

You can download a LDIF file for https://github.com/suryakand/tutorials/blob/master/ldap/sample-ldap.ldif and import it directly. You can use import sample user data using “Apache Directory Studio RCP Application” that you have downloaded in step# 1.

2.       Configure your HOST file (I am assuming that you are on a windows machine)

Add following configuration to host file:

127.0.0.1                                      www.blogsaml.com

3.       Tomcat Installation (Preferred is 8 but, Tomcat 7 will also work)

Download tomcat from https://tomcat.apache.org/download-80.cgi (Direct link: http://www.eu.apache.org/dist/tomcat/tomcat-8/v8.0.27/bin/apache-tomcat-8.0.27.zip) and copy extracted tomcat archive file into INST_HOME directory.

4.       Shibboleth

Step 1: Download Shibboleth & extract it in INST_HOME

Download a copy of 2.4.4 from http://shibboleth.net/downloads/identity-provider/2.4.4/ and extract the zip/archive in INST_HOME. Here is direct link http://shibboleth.net/downloads/identity-provider/2.4.4/shibboleth-identityprovider-2.4.4-bin.zip

Step 2: Install Shibboleth

Installation of Shibboleth is fairly easy process. Go the “INST_HOME/shibboleth-identityprovider-2.4.4” directory (created after extracting the downloaded shibboleth zip in Step# 1). Run the “install.bat” file and it’ll ask you few inputs on screen. Enter following values (make sure that you are using below values only, I’ll tell the reason why later in this article):

Installation Directory: c:/saml_idp (we’ll refer this directory as IdP_HOME in this article)

Host Name: www.blogsaml.com

Password for key store: saml

Once installation is completed you’ll see idp.war file in IdP_HOME/war folder. Copy this war file to your TOMCAT_HOME/webapps folder and start the tomcat. You’ll also need to copy few additional jar file in TOMCAT_HOME/webapps/idp/WEB-INF/lib folder (you can download these jar files from https://github.com/suryakand/tutorials/tree/master/shibboleth/saml_idp/extra-libs) folder. Restart your tomcat server after copying files.

Step 3: Shibboleth Configuration

I have uploaded a preconfigured set of files that you can download from https://github.com/suryakand/tutorials/tree/master/shibboleth/saml_idp. I’ll recommend to keep these files handy so that you can follow this tutorial better. When you install Shibboleth these files will be created by installer in IdP_HOME/conf directory for you based on the parameters that you have supplied while installation (in step #2 above). There are 8 configuration files and all these configuration files are available in IdP_HOME/conf folder. We’ll look at the important section of these files one by one.

Main goal of this tutorial is to make you familiar with IdP (Shibboleth), Service Provider (AEM) and various configurations so that you understand everything end to end. If you are short of time and just want to get up and running with IdP and play with AEM configuration then you can just copy the configuration files (conf, credentials and meta) and replace it in your IdP_HOME folder and go to Step# 4.

First we’ll look at files on IdP_HOME/conf folder

a)      Attribute Resolver Configurations (attribute-resolver.xml): Attribute resolver’s main function is to read attributes (related to a principal/user mainly) from source database (RDMS, LDAP etc.) and provide it to Service Provider (in our case AEM) after filtering within IdP (in our case Shibboleth). There are two main components/elements in this file that we need to focus on:

·         Attributes: There are different type of attributes that we can define. e.g. simple attribute (this contains just name-value combinations), scoped attribute (similar to simple attribute you can define scope), here scope refers to Service Provider (i.e. to which Service Provider a scoped attribute is available). Attributes have dependency on DataConnectors.

·         Data Connector: with the help of DataConnector element to tell IdP how to connect to a database of users (RDMS, LDAP etc.) to fetch information/records.

So, to connect dots we can say that attributes are fetched by Identity Provider (IdP) using data connector and are filtered (how, we’ll see in next section) before giving it to service provider.

You can read more about attribute resolver at https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttribute

b)      Attribute Filter File Configurations (attribute-filter.xml): An attribute filter policy describes which attributes are sent to a particular service provider. The default attribute filter policy file is IdP_HOME/conf/attribute-filter.xml. You can read more about attribute filters at https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttributeFilter

c)       Relying Party configurations (relying-party.xml): This file contains relying party configurations for the IdP, for example, whether SAML assertions to a particular relying party should be signed.  It also includes metadata provider and credential definitions used when answering requests to a relying party. This file mainly contains three components/elements:

RelyingParty: The IdP recognizes three classifications of relying parties:

·         anonymous - a relying party for which the IdP has no metadata

·         default - a relying party for which the IdP does have metadata but for which there is no specific configuration

·         specified - a relying party for which the IdP has metadata and a specific configuration

MetadataProvider: This file contains meta data information for relying parties (IdP and Service Providers). The IdP uses metadata to drive a significant portion of its internal communication logic with a relying party. The metadata contains information such as what keys to use, whether certain information needs to be digitally signed, which protocols are supported, etc. A relying party is identified within metadata by an element with an entityID attribute whose value corresponds to the relying party's entity ID. Entities may be grouped within an element and this group may be given a name by means of the name attribute. Entity groups may be nested.

When creating a specified relying party configuration you may specify either a specific entity or a group of entities. In that event that there is overlap the most specific configuration is used, no settings are "inherited" because of this overlap. As was mentioned above, a relying party for which the IdP can find no metadata is termed an anonymous relying party.

Credential: In this section we provide certificate and key of IdP.

d)      Handler Configuration (handler.xml): In this file we define/map ProfileHandlers (for handling SMAL 1 & 2 authentication, artifice resolution  request) and LoginHandlers (for form based login, session based login etc.). When connecting to a LDAP serer, LoginHalder also needs to know the LDAP configurations which are configured in login.config file (discussed below).

e)      login.config: For login handler to connect to a LDAP server we need to provide LDAP server information,  this information is configured in login.config file.

Now, let’s look at files in IdP_HOME/metadata folder

a)      Identity Provider Metadata (idp-metadata.xml): In this file we provide information about Identity Provider i.e. which certificates will be used by Identity Provider for SSO and Attribute signing while communicating with Service Provider.

b)      Service Provider Metadata (adobecq.xml): In this file we provide information about Service Provider i.e. which certificates will be used for signing SMAL message, where to POST the SAML response after authenticating user and Which URL service provider can use to log out.

Finally, let’s look at files in IdP_HOME/credentials folder

This folder contains the certificates & keys for Service provider.

NOTE: If you have not does this already then, you’ll also need to copy few additional jar file in TOMCAT_HOME/webapps/idp/WEB-INF/lib folder (you can download these jar files from https://github.com/suryakand/tutorials/tree/master/shibboleth/saml_idp/extra-libs) folder. Restart your tomcat server after copying files.

Installation verification:

Make sure that your tomcat is running and after that you can navigate to https://www.blogsaml.com:8443/idp/status and if everything has been configured correctly you should see a similar screen as below:

Fig 1: IdP Status Page

Step 4: Configure AEM

At this point you are done with IdP installation and now we’ll configure AEM to work with IdP so that we can login to AEM using SSO. I am assuming that you are working on AEM 6.x version.

NOTE: If you are running AEM 6.0 then you need to first install SP1 (https://docs.adobe.com/docs/en/aem/6-0/release-notes-sp1.html) else you’ll get 403 HTTP Error while authenticating with IdP.

a)      Start your AEM Server and make sure that you have AEM SP1 installed on your AEM instance if you are running AEM 6.0.

b)      Configure SMAL handler: Go to Felix console and open SMAL Handler Configuration window as shown below and configure values as shown in below screen shot:

 

Fig 2: AEM SAML Handler

 Fig 3: AEM SAML Handler Details

Couple of things to note here:

·         Path: this is the path where SMAL authentication handler will come into picture and will redirect you to IdP login page.

·         IdP URL: This is the URL where user will be redirect for login on IdP web server.

·         Service Provider ID: This is just and identifier for Service Provider and this can be any string value. The point that we have to note here is that this value should match with the value that you have configured in “entityID” attribute of Service Provider metadata file (adobecq.xml) in IdP_HOME/metadata folder. Also, this should match with “provider” attribute of RelyingParty in IdP_HOME/conf/relying-party.xml file

·         User encryption: if you have proper certificate and keys select this configuration and your SMAL messages will be signed before transporting over HTTP.

·         Add to Group & Group Membership: If this check box is selected and a value is configured against “Group Membership” configuration then AEM will look for configured attribute in SMAL response (i.e. in our case it’ll look for “group” attribute) and will add user to that group in AEM.

c)       Configure Referrer Configurations: The referrer filter service is an OSGi service that allows you to configure:

·         which http methods should be filtered

·         whether an empty referrer header is allowed

·         and a white list of servers to be allowed in addition to the server host.

Fig 4: AEM Referrer Config.

 Fig 4: AEM Referrer Config. Detail

At this point you are all set to test your configuration. If you try to access the URL http://www.blogsaml.com:4502/content/geometrixx/en.html you’ll be redirect to IdP’s login page (https://www.blogsaml.com:8443/idp/Authn/UserPassword) as shown below:

Fig 4: IdP Login Screen.

        Also, if you want to see the SMAL XML being transported between IdP and Service Provider then you can use Firefox’s SAML Tracker plugin, here is quick screen shot of SMAL Tracker:

Fig 4: SAML Request

Fig 4:SAML Response

        Now, it’s time to recap and connect dots from beginning. Here is what had happened when you have tried to access secure URL http://www.blogsaml.com:4502/content/geometrixx/en.html:

1)      Since the URL “/content/geometrixx” is configured in AEM SAML authentication handler as secure URL, SMAL handler will intercept this URL and will redirect user to IdP’s server (with SMAL request XML, see screen shot above “SAML Request”).

2)      Once IdP receives request for authentication (from AEM) it check whether the Service Provider is registered with IdP or not (Service Provider is registered with IdP in relying-party.xml file)? Once IdP recognizes that Service Provider is valid and is registered then only it redirects to login screen (https://www.blogsaml.com:8443/idp/Authn/UserPassword).

3)      Once user enter username and password and submits the from IdP looks for LoginHandler in “handler.xml” file and connects with LDAP server using the LDAP configurations provided in “login.config” file.

4)      Once connection is setup with LDAP server, IdP validates the username and password that user has entered against records in LDAP server and prepares SAML response that needs to go back to Service Provider.

5)      To prepare SAML response with appropriate attributes IdP consults the attribute-resolver.xml and attribute-filter.xml file. These file tells IdP which attributes to release (send back) to Service Provider in SAML response (See screen shot “SAML Response” for sample response).

6)      Once response is prepared by IdP it is sent back to Service Provider via a POST request on the configure end point in Service Provider metadata file (i.e. adobecq.xml). AEM by default list for SMAL POST response at /saml_login path.

7)      Once SAML response is received on AEM side, AEM reads the “uid” and “group” parameter from response and adds user in AEM (based on whether AEM has been configured to add user or not?).

I hope this article has helped you to understand the SAML and how it works hand-in-hand with a service provider.