PingAM 7.5.1

Deploy 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 IDP 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 sp.example.com domain, the service provider has no way of knowing whether the user has possibly authenticated at this-idp.example.com, or at that-idp.example.com. The providers therefore host an IDP Discovery service in a common domain, such as discovery.example.com, and use that service to discover where the user logged in. The IDP Discovery service essentially writes and reads cookies from the common domain. The providers configure their circle of trust to use the IDP Discovery service as part of SAML v2.0 federation.

Before you continue, ensure that you have a CoT with more than one IDP configured, and at least one SP. See Deployment considerations. You will configure the IDP Discovery service in the CoT later.

Deploying the IDP Discovery service involves the following stages:

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

  2. Configure the Discovery service.

  3. Add the Discovery service endpoints for writing cookies to and reading cookies from the common domain to the CoT.

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

    $ cp ~/Downloads/openam/IDPDiscovery-7.5.1.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 discovery.example.com:8443, and Tomcat has unpacked the application under /disco, so the URL is https://discovery.example.com:8443/disco, which redirects to Configurator.jsp.

    Configure the IDP Discovery service.
    Figure 1. Completed Discovery Service Configuration Screen

    The configuration screen shows the following fields:

    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, example.com.

    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.

    Valid Redirects

    A list of valid URLs the user can be redirected to once the IDP Discovery process is complete. For example, the SPs in your CoT.

    Incoming requests with URLs specified in the RelayState parameter that are not configured in this field are rejected.

    Add each URL in a new line, for example, by pressing the enter key after each one.

    Use wildcards (*) to match one or more resources in the URL.

    You must configure the same URLs in the Validation service of each of the IDPs in the Top Level Realm.

    For more information, see Configure the Validation service.

  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.

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 IDP Discovery service as described in the following steps:

  1. On the SP console, log in as AM Administrator.

  2. On the SP console, under Realms > Realm Name > Applications > Federation > Circle of Trust > Circle of Trust Name, add SAML2 Writer and Reader Service URLs for the IDP Discovery service endpoints, and save your work.

    In this example, the writer URL is https://discovery.example.com:8443/disco/saml2writer, and the reader URL is https://discovery.example.com:8443/disco/saml2reader.

  3. On each IDP console, log in as AM Administrator.

  4. On the IDP 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 IDP Discovery service endpoints, and save your work.