Deploying the IDP 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 discovery 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 v2.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.

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 IDPDiscovery-7.0.2.war file to the webapps/ directory.

    $ cp ~/Downloads/openam/IDPDiscovery-7.0.2.war /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.

    Completed Discovery Service Configuration Screen
    Completed discovery service configuration screen

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

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

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, log in as AM Administrator.

  2. On the service provider console, under Realms > Realm Name > Applications > 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, log in as AM Administrator.

  4. On the identity provider console, under Realms > Realm Name > Applications > Federation > Entity Providers > Circle of Trust > Circle of Trust Name, also add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and save your work.

To Share Identity and Service Provider Metadata

Before performing these steps, install the administration tools for each provider as described in Setting Up Administration Tools. The administration tools include the ssoadm command 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 https://www.sp.com:8443/openam/saml2/jsp/exportmetadata.jsp.

  2. Create metadata templates for each identity provider:

    $ ssh www.this-idp.example
    $ cd /path/to/openam-tools/admin/openam/bin
    $ ./ssoadm create-metadata-templ \
    --entityid "http://www.this-idp.example:8080/openam" \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --identityprovider /idp \
    --meta-data-file this-standard.xml \
    --extended-data-file 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 \
    --entityid "http://www.that-idp.example:8080/openam" \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --identityprovider /idp \
    --meta-data-file that-standard.xml \
    --extended-data-file 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 \
    --cot discocot \
    --meta-data-file ~/Downloads/this-standard.xml \
    --extended-data-file ~/Downloads/this-extended.xml \
    --adminid amadmin \
    --password-file /tmp/pwd.txt
    
    Import file, /Users/forgerock/Downloads/this-standard.xml.
    Import file, /Users/forgerock/Downloads/this-extended.xml.
    
    $ ./ssoadm import-entity \
    --cot discocot \
    --meta-data-file ~/Downloads/that-standard.xml \
    --extended-data-file ~/Downloads/that-extended.xml \
    --adminid amadmin \
    --password-file /tmp/pwd.txt
    
    Import file, /Users/forgerock/Downloads/that-standard.xml.
    Import file, /Users/forgerock/Downloads/that-extended.xml.
Read a different version of :