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
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 identity provider discovery service in a common domain, such as
discovery.example.com, 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.
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:
Deploy the WAR file into your web application container.
Configure the discovery service.
Add the discovery service endpoints for writing cookies to and reading cookies from the common domain to the CoT.
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.
IDPDiscovery-7.1.0.warfile to the
cp ~/Downloads/openam/IDPDiscovery-7.1.0.war /path/to/tomcat/webapps/disco.war
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
The configuration screen shows the following fields:
- Debug Directory
The discovery service logs to flat files in this directory.
- Debug Level
error. Other options include
Set this to
messagein 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,
- 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
RelayStateparameter 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 "To Configure the Validation Service".
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.
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:
On the service provider console, log in as AM Administrator.
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
https://discovery.example.com:8443/disco/saml2writer, and the reader URL is
On each identity provider console, log in as AM Administrator.
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.