Monday 18 June 2012

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

In this tutorial I will describe 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

Basic concepts

In this section I will describe basic concepts and terms used in this tutorials. It is important that you understand them before you start configuring the end solution.


OpenAM is Access Manager that evolved from OpenSSO after SUN abandoned it. It provides open source Authentication, Authorization, Entitlement and Federation software. This tutorial assumes you have basic knowledge about OpenAM and the functionalities it offers. You should be able to deploy and initially configure OpenAM instance on you local machine (not covered in this tutorial).

More on OpenAM on their website:


Security Assertion Markup Language (SAML) standard defines an XML-based framework for describing and exchanging security information between on-line business partners. Currently OpenAM supports SAML in version 2. The best way to start learning about SAML v2 is the Security Assertion Markup Language (SAML) V2.0 Technical Overview. This document covers all the following basic concepts described in my tutorial.

Web Single Sign On

Web SSO is the approach allowing single sign on for multiple web applications that have established a common agreement on how to exchange user information. The end users provide their credentials only once and they are recognized by all of the webapps, even if they are deployed in different domains and use different identity stores. SSO also allows usage of single identity store by all of the webapps.

Identity Federation

Identity federation is a process of linking users defined in different identity stores. Such link allows implementation of Single Sign On. What is important from privacy perspective is that in order to establish federation both parties do not have to know anything about user attributes from different identity stores.

Use case overview

This section describes the use case we will try to implement in this tutorial. I believe in learning by example so let's describe our use case using one:

I've recently registered a new internet domain by one of online providers. The provider offers a web based customer dashboard - let's call it the ProviderDashboard. I can use my customer number (12345) and password to log into that dashboard to see the list of my domains, invoices etc.

My provider has also an agreement with an external web application that offers reporting technical issues (e.g. when the domain is not available) - let's call it the IssueReporter. I already have an existing account at that website, because I used it in the past for other reasons. My login for that website is "filip".

So, whenever I log into the ProviderDashboard I have a link called "Report an issue" that takes me directly to the IssueReporter app. After I click the link I'm automatically loged into the IssueReporter app using the correct username i.e. filip. However, this relation is not symetricall - if I log in directly into IssueReporter I will not be automatically loged into ProviderDashboard.

So, let's have a look at the use case flow in detailed steps (happy path):

  1. I log into ProviderDashboard using account number 12345 and password
  2. I click on the link within the dashboard called "Report an issue"
  3. I'm redirected redirected to IssueReporter login screen
  4. I provide valid IssueReporter credentials i.e. filip as username
  5. My ProviderDashboard account (with identifier 12345) is linked to IssueReporter account for filip
  6. I am redirected to IssueReporter application and automatically logged in using filip account
Important: steps described using green font only happen during the first time I click on the link and belong to Identity Federation process. All subsequent redirections from ProviderDashboard to IssueReporter will not require those to be completed. All remaining steps are part of usual SSO process.

SAML terminology

In the scenario described above ProviderDashboard application acts as an Identity Provider (IdP) whereas the IssueReporter acts as Service Provider (SP). IdP and SP are terms defined in SAML and OpenAM also use them.

Our use case reflects “IdP initated SSO” scenario described in details in SAML Technical Overview document linked earlier. In general: IdP produces assertions about the user identity and passes them to SP. IdP also initiates Identity Federation when required i.e. when the link is clicked for the first time.

The following diagram presents IdP initiated SSO. It doesn’t cover Identity Federation actions (assume identities are already federated):

Note: On the diagram SAML assertions about identity are passed from IdP to SP using http POST request (steps 4&5). It is also possible to use SAML artifacts instead. When using SAML artifacts IdP passes to SP only artifact id instead of the entire identity assertion. SP obtains then the assertion by making a SOAP call to IdP and passing the artefact id.

In the next part of this tutorial I will describe how to configure sample environments using OpenAM for both IdP and SP.

Next: Sample environment configuration with OpenAM


Munavar Ahmed said...

Awesome explanantion!! thanks filip for posting this concept. now iam clear. your learn by example concept worked well for me.. keep posting

gw said...

If this is a single sign on process why would the user login on at two different logon pages?
Would the additional logon page be eliminated if the metadata was shared via an external activity ahead of time? So creating the circle of trust prior to the user accessing the provider site.

Filip Czaja said...

Hi gw

Users need to logon on 2 pages only during their first attempt ever. This process is called identity federation and is required, so the SP knows which of its user accounts should be linked to the identity extracted from the SAML assertion received from the IdP. All subsequent attempts will not require the second login.
For the 2nd question - yes, SAML allows establishing identity federation "ahead of time", although not sure how this works in case of OpenAM implementation - need to check.
Circle of trust needs to be established anyway, so both parties know who can they trust.


Unknown said...

Hello Filip,

My name is Shamji. I am a Sharepoint Administrator and trying to install the ForgrRock OpenAM Agent on my sharepoint servers for authentication and sso. My Sharepoint is 2010 standard with claims based authentication. I have followed all the steps mentioned in the forgerock wiki but for some reason I get a 403 error. Unfortunately neither the open logs nor the iis 7.5 logs have got nothing much to say. I am stranded on beach looking for a help SOS.

Below is the link that I have followed to install the agent on the SP servers. Any help will highly be appreciated.!/docs/openam-policy-agents/3.1.0/agent-install-guide/chap-msiis-7


Unknown said...

Hi Filip I have one query around saml
There is one use case where I want to bypass saml authentication and need to create a super user sort of login who can emulate other users without touching to saml. So is this possible to do and if yes then how please help me out here


Gluu said...

Just an FYI... OpenAM is open source. If you fork the project, it has CDDL license. So if you're building from source, your probably fine. But if you use Forgerock's binary packages, you must accept their commercial license agreement, which says you cannot use the code in production without paying.

Unknown said...

Thanks, you have explained with examples and flow charts which helped much to understand clearly.