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