12.2.1. Deploying the Identity Provider Discovery Service

When your circle of trust includes multiple identity providers, then service providers must discover which identity provider corresponds to a request. You can deploy the identity provider discovery service for this purpose as a separate web application.

Browsers only send cookies for the originating domain. Therefore when a browser accesses the service provider in the www.sp.example domain, the service provider has no way of knowing whether the user has perhaps already authenticated at www.this-idp.example or at www.that-idp.example. The providers therefore host an identity provider discovery service in a common domain, such as www.disco.example, and use that service to discover where the user logged in. The identity provider discover service essentially writes and reads cookies from the common domain. The providers configure their circle of trust to use the identity provider discovery service as part of SAML 2.0 federation.

Deploying the identity provider discovery service involves the following stages.

  1. Deploy the .war file into your web application container.

  2. Configure the discovery service.

  3. Add the identity provider discovery service endpoints for writing cookies to and reading cookies from the common domain to the circle of trust configurations for the providers.

  4. Share metadata between identity providers and the service provider.

Procedure 12.6. To Deploy the Discovery Service on Tomcat

How you deploy the discovery service .war file depends on your web application container. The procedure in this section shows how to deploy on Apache Tomcat.

  1. Copy the file to the webapps/ directory. 

    $ cp ~/Downloads/openam/ /path/to/tomcat/webapps/disco.war

  2. Access the configuration screen through your browser.

    In this example, Apache Tomcat listens for HTTP requests on www.disco.example:8080, and Tomcat has unpacked the application under /disco, so the URL is http://www.disco.example:8080/disco, which redirects to Configurator.jsp.

Procedure 12.7. To Configure the Discovery Service

  1. Configure the identity provider discovery service.

    Completed discovery service configuration screen

    [D]

    Hints for discovery service configuration parameters follow.

    Debug Directory

    The discovery service logs to flat files in this directory.

    Debug Level

    Default is error. Other options include error, warning, message, and off.

    Set this to message in order to see the service working when you run your initial tests.

    Cookie Type

    Set to PERSISTENT if you have configured OpenAM to use persistent cookies, meaning single sign on cookies that can continue to be valid after the browser is closed.

    Cookie Domain

    The cookie domain is the common cookie domain used in your circle of trust for identity provider discovery, in this case .disco.example.

    Secure Cookie

    Set this to true if clients should only return cookies when a secure connection is used.

    Encode Cookie

    Leave this true unless your OpenAM installation requires that you do not encode cookies. Normally cookies are encoded such that cookies remain valid in HTTP.

    HTTP-Only Cookie

    Set to true to use HTTPOnly cookies if needed to help prevent third-party programs and scripts from accessing the cookies.

  2. Restrict permissions to the discovery service configuration file in $HOME/libIDPDiscoveryConfig.properties, where $HOME corresponds to the user who runs the web container where you deployed the service.

Procedure 12.8. To Add the Discovery Service to Your Circles of Trust

Each provider has a circle of trust including itself. You configure each of these circles of trust to use the identity provider discovery service as described in the following steps.

  1. On the service provider console, login as OpenAM Administrator.

  2. On the service provider console, under Federation > Circle of Trust > Circle of Trust Name add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and Save your work.

    In this example, the writer URL is http://www.disco.example:8080/disco/saml2writer, and the reader URL is http://www.disco.example:8080/disco/saml2reader.

  3. On each identity provider console, login as OpenAM Administrator.

  4. On the identity provider console, under Federation > Circle of Trust Configuration > Circle of Trust Name also add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and Save your work.

Procedure 12.9. To Share Identity & Service Provider Metadata

Before performing these steps, install the administration tools for each provider as described in To Set Up Administration Tools. The administration tools include the ssoadm tool that you need to export metadata.

  1. On each identity provider console, register the service provider as a remote service provider adding to the circle of trust you configured to use the identity provider discovery service.

    The URL to the service provider metadata is something like http://www.sp.example:8080/openam/saml2/jsp/exportmetadata.jsp.

  2. Obtain metadata for each identity provider.

    $ ssh www.this-idp.example
$ cd /path/to/openam-tools/admin/openam/bin
$ ./ssoadm create-metadata-templ -y "http://www.this-idp.example:8080/openam"
 -u amadmin -f /tmp/pwd.txt -i /idp -m this-standard.xml -x this-extended.xml
Hosted entity configuration was written to this-extended.xml.
Hosted entity descriptor was written to this-standard.xml.

$ ssh www.that-idp.example
$ cd /path/to/openam-tools/admin/openam/bin
$ ./ssoadm create-metadata-templ -y "http://www.that-idp.example:8080/openam"
 -u amadmin -f /tmp/pwd.txt -i /idp -m that-standard.xml -x that-extended.xml

Hosted entity configuration was written to that-extended.xml.
Hosted entity descriptor was written to that-standard.xml.

  3. For each identity provider extended metadata file, change the value of the hosted attribute to 0, meaning the identity provider is remote.

  4. On the service provider, add the identity providers to the circle of trust using the identity provider metadata. 

    $ ssh www.sp.example
$ cd /path/to/openam-tools/admin/openam/bin
$ ./ssoadm import-entity -t discocot -m ~/Downloads/this-standard.xml
 -x ~/Downloads/this-extended.xml -u amadmin -f /tmp/pwd.txt

Import file, /Users/mark/Downloads/this-standard.xml.
Import file, /Users/mark/Downloads/this-extended.xml.
$ ./ssoadm import-entity -t discocot -m ~/Downloads/that-standard.xml
 -x ~/Downloads/that-extended.xml -u amadmin -f /tmp/pwd.txt

Import file, /Users/mark/Downloads/that-standard.xml.
Import file, /Users/mark/Downloads/that-extended.xml.

  5. Test your work by using the Federation Connectivity Test that you start from the service provider console under Common Tasks > Test Federation Connectivity.

    When the test is done, you can see messages from the CookieWriterServlet in the libIDPDiscovery log file where you set up logging when you configured the identity provider discovery service, such as /tmp/debug/libIDPDiscovery. Output generated during a test follows, with some lines folded to fit on the printed page. 

    08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieUtils.init : idpDiscoveryOnlyWar=true
08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet Initializing...
08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Preferred Cookie Name is _saml_idp
08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: URL Scheme is null, set to https.
08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Preferred IDP Cookie Not found
08/08/2012 11:43:38:342 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Cookie Type is PERSISTENT
08/08/2012 11:43:38:342 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Cookie value is
 aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=
08/08/2012 11:43:38:342 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Preferred Cookie Name _saml_idp
08/08/2012 11:43:38:343 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Redirect to
 http://www.that-idp.example:8080/openam/SSORedirect/metaAlias/idp?resInfoID=
 s28bc4db004f1365d78d07d69846c54a3c850fe801
08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Preferred Cookie Name is _saml_idp
08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieUtils:cookieValue=aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=,
 result=aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=
08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Cookie Type is PERSISTENT
08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Cookie value is
 aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=
08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Preferred Cookie Name _saml_idp
08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
CookieWriterServlet.doGetPost: Redirect to
 http://www.that-idp.example:8080/openam/SSORedirect/metaAlias/idp?resInfoID=
 s2ce9c465cf39c96f31e1dcf009cf9943695d82901