Thursday 21 June 2012

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 the Security 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.


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".

My hosts file has 4 different host names set all pointing to, 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 ProviderDashboard application and OpenAM instance protecting it 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

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
  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
  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
  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
  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:
    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
  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,
    2. Authentication for Service Provider.
    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


rdx said...

this was a very helpful tutorial, i tried but the test gives unable to link accounts

i have 2 webaps both hosted on diff jboss installs one on 4 other on 5

4 is Ip
and 5 is SP

i configured both hosted and remote but fails on Linking acounts

one thing i did not map any attribiutes

Unknown said...

This is very helpful tutorial. Is it possible to post the provider dashboard and issue reporter apps?

Filip Czaja said...

Hi John

I may post my apps soon. For now, I recommend you to take a look at the samples included with OpenAM distribution. They are much richer than my apps.

Unknown said...

Thanks Filip. I am new to OpenAM, I am trying to setup SSO between 2 Java web apps. I am able to link SP and IdP by following your tutorial. I am kind of lost on how to setup my apps with OpenAM. If you could point to a sample that you are aware of, that will be great.

Filip Czaja said...
This comment has been removed by the author.
Filip Czaja said...

Hi John

For securing your apps with openam I recommend you to start with OpenAM wiki.

For using SAML functionality offered by OpenAM in your webapp you can read the next part of this tutorial.

Unknown said...

Thanks Filip. I am able to get the SSO working between 2 web apps. Thanks for your help.

My requirement is to have SSO as well as federated identity management. I have to provide SSO between multiple applications and should be able to talk to multiple identity providers (one for each customer). My application will have an identity provider configured for each customer, whenever a user submits the credentials I have to send it to appropriate IdP. Is this something I can achieve using OpenAM?

Pratapk said...

Can you give source code for ProviderDashboard and IssueReporter applications

Unknown said...

I am getting the below exception while doing the SSO test from It failes to link the IDP to SP.

Can any body tell me whats wrong with the configuration?

org.apache.jasper.JasperException: javax.servlet.ServletException: com.sun.iden
ity.saml2.common.SAML2Exception: Couldn't find IDP based on the SourceID in the

Unknown said...

I am able to single sign on using the steps mentioned. Now I have a requirement where the sp authentication should isn't required while linking the account. Please provide some idea how to configure this scenario.

Unknown said...

Good example, however, I was also getting the "unable to link accounts" and finally found out the reason.

Unlike the example, I did not have and I had, Shared domain.

I was also using the same installer package for OpenAM in both locations.

The solution here is that for this example, if the IdP and the SP are in the same domain, the Cookie name must be different for both instances of OpenAM.

Configuration->ServersAndSites->Default Server Settings->Security->Cookie : rename the cookie from iPlanetDirectoryPro (or whatever you have) to something unique. OpenAM must then be restarted to accept the cookie change.

After doing this, my test was able to proceed, as both IdP and SP can accept concurrent login sessions from the same browser without clobbering one another.

Unknown said...

I am unable to link the accounts even after following all the above mentioned steps.even i checked the cookie and domains also even then it is not linking the accounts.The one thing i missed is the attribute mapping when creating the entities.Is that the reason for not linking accounts?if not please provide me a solution for this..
Thank u

Unknown said...

I'm seeing invalid meta data message when configuring Remote Identity Provider in

Please let me know if anyone has seeing this error before.