Friday, 22 June 2012

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

This is the third 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.

Using OpenAM SAML services

Having IdP and SP environments configured it’s time to make use of the SAML functionality exposed by OpenAM. OpenAM deployment includes several services that allow developers to easily configure the entire Identity Federation and SSO. Those services are available directly at openam base url and can be access by regular hypelinks from within your web applications.

In this chapter I will describe each service and show how to make use of them.

IDPSSOInit - Identity Federation and SSO service

This service is used to initiate both Identity Federation and SSO. If the link is clicked for the first time by current IdP user the Identity Federation process will be invoked and then SSO. Otherwise only SSO process will be invoked.

The service takes following parameters:

Param name Description Sample value
metaAlias IdP MetaAlias value, by default “/idp”. To ensure about the correct value navigate to hosted IdP configuration screen. MetaAlias will be defined in Services tab. /idp
spEntityID Value of the name given to your Service Provider. Usually SP OpenAM url. http://www.sp.com:8090/openam
binding Binding type used for sending SAML assertions. Available Bindings: HTTP-Artifact & HTTP-POST urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
RelayState The target URL on SP side. User will be redirected to that url after SSO is completed. http://www.reporter.sp.com:8020/issuereporter

Sample HREF attribute value for the SSO initiation link could look as follows:

http://www.idp.com:8080/openam/idpssoinit
?metaAlias=/idp
&spEntityID= http://www.sp.com/openam
&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact
&RelayState=http://www.reporter.sp.com:8020/issuereporter

IDPSloInit - Single Log Out

This service is used to initiate Single Logout (SLO). It allows logging out the user from both IdP and SP with a single click.

The service requires following parameters:

Param name Description Sample value
binding Binding type used for logout request. Available Bindings: HTTP-Redirect & SOAP urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
RelayState The target URL to be used after logout http://www.dashboard.idp.com:8010/providerdashboard/logout

Sample HREF attribute value for the logout link could look as follows:

http://www.idp.com:8080/openam/idpsloinit
?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
&RelayState=http://www.dashboard.idp.com:8010/providerdashboard/logout

IDPMniInit - Federation management service

This service can be used to terminate the relation between accounts that was established during initial Identity Federation. After it is invoked Identities will need to be federated again during the next SSO.

The service requires following parameters:

Param name Description Sample value
metaAlias IdP MetaAlias value, by default “/idp”. To ensure about the correct value navigate to hosted IdP configuration screen. MetaAlias will be defined in Services tab. /idp
spEntityID Value of the name given to your Service Provider. Usually SP OpenAM url. http://www.sp.com:8090/openam
binding Binding type used for termination request. Available Bindings: HTTP-Redirect & SOAP urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
RelayState The target URL to be used after termination is completed http://www.dashboard.idp.com:8010/providerdashboard
requestType In order to terminate the relation use “Terminate”. The service also supports “NewID” but it is not explicitly used in our use case. Terminate

Sample HREF attribute value for the federation termination link could look as follows:

http://www.idp.com:8080/openam/idpmniinit
?metaAlias=/idp
&spEntityID= http://www.sp.com/openam
&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
&RelayState=http://www.dashboard.idp.com:8010/providerdashboard
&requestType=Terminate

How to use OpenAM SAML services?

As mentioned before, all you have to do to use OpenAM SAML services is to create hyperlinks within your web applicaiton pointing to them. In our use case the body of a sample web page for ProviderDashboard could look as follows:

Provider Dashboard

Report an issue Terminate federation Logout
The page above contains 3 hyperlinks:
  1. Report an issue - initiates Identity Federation and SSO with IssueReporter
  2. Terminate federation - terminates Identi Federation established with IssueReporter app. Will only work if the federation has been previously established, otherwise it will cause an error
  3. Logout - initiates logout from both ProviderDashboard and IssueReporter
Copy the hyperlinks and place them anywhere within you sample ProviderDashboard web application. Now it's time to verify if our solution works.

Solution verification

Identity Federation
  1. Navigate to http://www.dashboard.idp.com:8010/providerdashboard
  2. Log in as user '12345'
  3. Click on the 'Report an issue' link
  4. Because you are doing this for the first time you will be redirected to IssueReporter login screen.
  5. Login to IssueReporter using 'filip' account. OpenAM will establish federation between IdP and SP accounts (i.e. between users '12345' and 'filip).
  6. You should be redirected to your IssueReporter app
Single Logout
  1. Go back to http://www.dashboard.idp.com:8010/providerdashboard
  2. Click the 'Logout' link
  3. You should be redirected to IdP OpenAM login screen
  4. Try to access http://www.reporter.sp.com:8020/issuereporter
  5. You should be redirected to SP OpenAM login screen
Federation termination
  1. Navigate to http://www.dashboard.idp.com:8010/providerdashboard
  2. Log in as user '12345'
  3. Click on the 'Terminate Federation' link
  4. Click on the 'Report an issue' link
  5. Because you terminated the original federation you will be redirected to IssueReporter login screen so you can establish new federation.
  6. Login to IssueReporter using 'filip' account to recreate the original federation. OpenAM will establish federation between IdP and SP accounts again (i.e. between users '12345' and 'filip).
  7. You should be redirected to your IssueReporter app
Congratulations! You have now configured working example of IdP initiated SSO and Identity Federation with OpenAM and SAML. But are you really sure what is goin on behind the scenes? In the next chapter I will explain the SAML communication and messages exchanged between IdP and SP in details.

Previous chapter: Sample environment configuration with OpenAM
Next chapter: Detailed look at SAML interactions

4 comments:

Phil Lembo said...

Thanks much for this series! I've been struggling with getting various things to work in OpenAM and what you've written about it (including some important critical comments you made back in September) have been spot on.

Arjun said...


Hi

I have developed an application as SP using OpenAM fedlet. Single Sign on is working fine and Single Sign out also happening from Idp (Idp is

SimpleSAMLPHP).

But Im facing one issue, when I have connected two SP's and do single sign out its successfully signed out from Idp but the local session for second SP

still exists and able to access the site even after logged out of Idp.

I assume that for each request in SP should validate whether valid session exists in Idp, but I'm unable to find how to do with OpenAM fedlet.

Can you please give me some valuable input to signout local session of SP when signout is happened from any other SP.

Regards
Arjun S

chrome said...

Filip, great tutorial and a very clear use case explaining SAML use in OpenAM. I've looked and your's is the best and most clear explanation I've read. thanks

Shadab Alam said...

Hello Filip

I have a requirement, I have an IdP application and a SP application.
I need IdP initiated SSO. So, when User Logged into IdP land into IdP portal from where we can click the link and go to SP (apps), but this need again login. The second login needs to be removed. which can be done using openAM.
1. My first question is, do we need to treat both IdP and SP as remote and do the required
configuration in OpenAM to achieve SSO and federated Id.
2. My second question is, can we achieve this using one instance of openAM or we need to
have 2 openAM instance.

Thanks for the wonderful tutorial. I implemented and faced no problem at all.

Shadab