Openam Saml

IdP initiated SSO and Identity Federation with OpenAM and SAML - part II

This is the second part of the tutorial describing how to configure IdP initiated SSO and Identity Federation with OpenAM and SAML. The tutorial consists of 4 parts:

1. Basic concepts & use case overview
2. Sample environment configuration with OpenAM
3. Using OpenAM SAML services
4. Detailed look at SAML interactions

If you don't understand any terms or abbreviations that I use here please read the first part of the tutorial together with theSecurity Assertion Markup Language (SAML) V2.0 Technical Overview.

Sample environment configuration with OpenAM

Now that you know what we will try to achieve in this tutorial let's try to configure our test environment.

Prerequisites

Web containers
Our test environment will consists of 2 instances of OpenAM, each protecting one web application. The first instance will act as an Identity Provider (IdP) and the second as a Service Provider (SP). This gives us 4 web containers (I used Tomcats 6.x) that I've installed on a single machine using different ports :

• 8010 - tomcat hosting sample ProviderDashboard application
• 8020 - tomcat hosting sample IssueReporter application
• 8080 - tomcat hosting OpenAM protecting ProviderDashboard and acting as IdP
• 8090 - tomcat hosting OpenAM protecting IssueReporter and acting as SP

OpenAM default configuration
In this tutorial I assume you already have all those tomcats prepared. This means you have some sample applications deployed that represent ProviderDashboard and IssueReporter web applications. Those webapps should also be protected by OpenAM agents communicating with appropriate OpenAM instance. However, at this stage there is no SSO or identity federation configured for those instances (that is what we need to do).If you don't know how to deploy OpenAM please reffer to the following guide: How to deploy OpenAM.
For now, as ProviderDashboard and IssueReporter you can use any Hello World wabapp. When configuring OpenAM agents please create a realm called "test", as this is what we'll be using in this tutorial.
In your OpenAM instances you should also have registered users, that we use in our use case. This means in IdP OpenAm you should have a user "12345" and in SP there should be a user "filip".

Hosts
My hosts file has 4 different host names set all pointing to 127.0.0.1, so I can access all of the tomcats using different hosts names. The following table summarizes urls I use in this tutorial:

App Url	Openam Url	Description
http://www.dashboard.idp.com:8010/providerdashboard	http://www.idp.com:8080/openam	ProviderDashboard application and OpenAM instance protecting it
http://www.reporter.sp.com:8020/issuereporter	http://www.sp.com:8090/openam	IssueReporter application and OpenAM instance protecting it

If you are using Windows you can configure those hosts by adding the following line to the file
C:\Windows\System32\drivers\etc\hosts

?

1	127.0.0.1 www.dashboard.idp.com www.reporter.sp.com www.idp.com www.sp.com

Once you have all the prerequisites fulfilled you can start configuring your SAML communication. This requires configuration changes in both OpenAM instances.

Hosted Identity Provider

First, we will start by configuring hosted Idp in ProviderDashboard OpenAM

1. Navigate to http://www.idp.com:8080/openam
2. Login as amadmin to OpenAM web console
3. On the main screen (“Common tasks” tab) choose “Create Hosted Identity Provider” link from “Create SAMLv2 Providers” section
4. The following form appears: The fields to be populate are marked with red numbers
5. Populate the form:
   1. Realm
      Select the 'test' realm. Each IdP is directly related to a Realm.
   2. Name – unique name of your IdP
      You can use OpenAM instance url as the name assuming you will only have 1 IdP per instance. If you want to have more IdPs per OpenAM instance use realm names
   3. Signing key
      If you want to digitally sign all your SAML messages select a signing key. OpenAM offers a test key to be used for testing purposes. For production needs you’ll have to generate a new one.
   4. Circle of trust
      Provide name for your circle of trust. All SAML providers that want to communicate with each other need to belong to the same circle of trust.
   5. Attribute mapping
      If IdP and SP identity stores have different schema but store the same kind of information you can define an explicit mapping between them. E.g. Email address can be stored in IdP as ‘email’ and in SP as ‘mailAddress’. OpenAM suggest you attributes available for your IdP.
6. Click ‘Configure’ button
7. On the confirmation screen click ‘Finish’

Remote Identity Provider

Next, we will register IdP created in previous step as a remote IdP in IssueReporter OpenAM:

1. Navigate to http://www.sp.com:8090/openam
2. Login as amadmin to SP OpenAM web console
3. On the main screen (“Common tasks” tab) choose “Register Remote Identity Provider” link from “Create SAMLv2 Providers” section
4. Populate the form:
   • Url of metadata
     Use the following format: http://<idp-openam-url>/saml2/jsp/exportmetadata.jsp
   • Circle of Trust
     Provide the same name as used on IdP side
5. Click ‘Configure’ button

Hosted Service Provider

Now, it is time to configure an SP hosted in IssueReportr OpenAM:

1. Navigate to http://www.sp.com:8090/openam
2. Login as amadmin to SP OpenAM web console
3. On the main screen (“Common tasks” tab) choose “Create Hosted Service Provider” link from “Create SAMLv2 Providers” section
4. Populate the form:
   • Name – use url of this SP OpenAM instance
   • Circle of Trust – select the same one as for IdP
   • Use default attribute mapping from Identity Provider - checked
5. Click ‘Configure’ button

Remote Service Provider

Next, we will register remote SP in ProviderDashboard OpenAM

1. Navigate to http://www.idp.com:8080/openam
2. Login as amadmin to OpenAM web console
3. On the main screen (“Common tasks” tab) choose “Register Remote Service Provider” link from “Create SAMLv2 Providers” section
4. The following form appears:

5. Populate the form:
   1. Realm
      Select the same realm as for IdP.
   2. Url of metadata 
      If another instance of OpenAM is used as SP then the url pointing to the service metadata has following format: http://<sp-openam-url>/saml2/jsp/exportmetadata.jsp
      In our case it is: http://www.sp.com:8090/openam/saml2/jsp/exportmetadata.jsp
   3. Circle of trust
      Select the same as used for IdP
   4. Attribute mapping
      If required use the same mappings as in IdP
6. Click ‘Configure’ button

General configuration

You can always edit providers defined in previous steps. To do that:

1. Navigate to either SP or IdP OpenAM and login as admin to OpenAM web console
2. Click on ‘Federation’ tab
3. You should see the screen listing all defined circles of trust and all entities (IdPs and SPs). Sample sreen for IdP OpenAM instance:
4. Click on the entity you’d like to update e.g. hosted IdP
5. You will be redirected to the screen where you can update default and advanced entity configuration

Environment setup validation

At this stage our test environment should be ready to perform SAML Identity Federation and Single Sign On between our sample ProviderDashboard and IssueReporter applications. In order to validate the setup perform following steps:

1. Navigate to http://www.idp.com:8080/openam
2. Login as amadmin to OpenAM web console
3. On the main screen (“Common tasks” tab) choose “Test Federation Connectivity”
4. Select circle of Trust (COT) that you'd like to test
5. The following screen should appear: You can select IdP and SP that you'd like to perform the test for and click 'Start Test' button
6. A warning will be displayed that the user will be logged out - click 'OK'
7. Now the actual test begins. It consists of following steps:
   1. Authentication for Identity Provider, http://www.idp.com:8080/openam
   2. Authentication for Service Provider. http://www.sp.com:8090/openam
   3. Testing for the ability to link account
   4. Testing for single logout
   5. Testing Single Sign On.
   6. Testing for account termination
   You will be guided through the entire test. While testing account linking you will be asked to provide credentials for the Idp (12345/password) and then for the SP (filip/password). Next it will perform SSO test which requires authentication with Idp credentials once again. At the end of the test you should see a success message.

If everything worked fine you should be able to start using SAML functionality exposed by OpenAM in your applications. Please note that although your test environment is correctly configured the sample web applications are not making use of SAML features yet.In the next chapter I will show how to make use of SAML features exposed by OpenAM in your web applications.
Previous chapter: Basic concepts & use case overview
Next chapter: Using OpenAM SAML services