Sun OpenSSO Enterprise 8.0 Administration Guide

Finding an Identity Provider for Authentication

If there is only one Identity Provider in a Circle-of-Trust, Service Providers will send users directly to the Identity Provider for authentication. In the case when there are multiple Identity Providers in a Circle-of-trust, a Service Provider requires a way to determine which identity provider is used by a principal requesting authentication. Because Service Providers are configured without regard to their location, this function must work across DNS-defined domains. OpenSSO Enterprise implements the following solutions for this use case:

Identity Provider Discovery Service in SAMLv2
Identity Provider Introduction Service in ID-FF
Home Realm Discovery Service in WS-Federation

When these services are configured, the Service Provider determines and redirects the user agent to the appropriate identity provider for authentication. The following sections contain more information.

Configuring the SAMLv2 Identity Provider Discovery Service

The SAMLv2 Identity Provider Discovery Service is provided by OpenSSO Enterprise after deployment. Alternatively, the Identity Provider Discovery Service can be configured as a standalone service. After the SAMLv2 Identity Provider Discovery Service is configured, an administrator creates and configures a Circle-of-Trust to use the Identity Provider Discovery service for the IDPs and SPs. In OpenSSO Enterprise, the Identity Provider Discovery Service for SAMLv2 providers is configured using two URLs that point to servlets developed for writing and reading a special cookie called Common Domain cookie. Go to the circle-of-trust entity and configure the following:

SAMLv2 Writer Service URL

The Writer Service URL is used by the identity provider. After successful authentication, the common domain cookie is appended with the query parameter _saml_idp=entity-ID-of-identity-provider. This parameter is used to redirect the principal to the Writer Service URL defined for the identity provider. The URL is configured as the value for the SAML2 Writer Service URL attribute when a circle of trust is created. Use the format http://idp-discovery-host:port/deployment-uri/writer where idp-discovery-host:port refers to the machine on which the SAMLv2 Identity Provider Discovery service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

SAMLv2 Reader Service URL

The Reader Service URL is used by the service provider. The service provider redirects the principal to this URL in order to find the preferred identity provider. Once found, the principal is redirected to the identity provider for single sign-on. The URL is defined as the value for the Reader Service URL attribute when a circle of trust is created. It is formatted as http://idp-discovery-host:port/deployment-uri/transfer where idp-discovery-host:port refers to the machine on which the SAMLv2 IDP Discovery service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

Configuring the ID-FF Identity Provider Introduction Service

OpenSSO Enterprise provides the Liberty ID-FF Identity Provider Introduction Service upon deployment. Alternatively, the Identity Provider Introduction Service could be configured as a standalone service (refer to later section for details).

After the Liberty ID-FF Identity Provider Introduction Service is configured, an administrator needs create and configure a Circle-of-Trust to use the service. In OpenSSO Enterprise, the Identity Provider Introduction Service for ID-FF providers is configured using two URLs that point to servlets developed for writing and reading a special cookie called Common Domain cookie. Go to the circle-of-trust entity and configure the following:

ID–FF Writer Service URL

The Writer Service URL is used by the identity provider. After successful authentication, the common domain cookie is appended with the query parameter _liberty_idp=entity-ID-of-identity-provider. This parameter is used to redirect the principal to the ID-FF Writer Service URL defined for the identity provider. The URL is configured as the value for the ID-FF Writer Service URL attribute when a circle of trust is created. Use the format http://idp-introduction-host:port/deployment-uri/idffwriter where idp-introduction-host:port refers to the machine on which the ID-FF Identity Provider Introduction service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

ID-FF Reader Service URL

The ID-FF Reader Service URL is used by the service provider. The service provider redirects the principal to this URL in order to find the preferred identity provider. Once found, the principal is redirected to the identity provider for single sign-on. The URL is defined as the value for the ID-FF Reader Service URL attribute when a circle of trust is created. It is formatted as http://idp-introduction-host:port/deployment-uri/transfer where idp-intorductoin-host:port refers to the machine on which the ID-FF Identity Provider Introduction service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

Configuring WS-Federation Home Realm Discovery Service

To configure a WS-Federation service provider to use the Home Realm Discovery Service, click on the WS-Federation entity name in the OpenSSO Enterprise console, select the Service Provider (SP) tab and configure the following:

Home Realm Discovery: Specifies the service so that the service provider can identify the preferred identity provider. The service URL is specified as a contact endpoint by the service provider.
Account Realm Selection: Specifies the identity provider selection mechanism and configuration. Either the cookie or HTTP Request header attribute can be used to locate the identity provider.

Customizing SAMLv2 the Identity Provider Discovery Service and the ID-FF Identity Provider Introduction Service

There are two ways to obtain the SAMLv2 IDP Discovery Service/ID-FF IDP Introduction service:

Create and deploy a specialized WAR file used for the SAMLv2 Identity Provider Discovery Service and ID-FF Identity Provider Introduction Service only. See To Create a Specialized WAR file for the Identity Provider Services.
Customize the SAMLv2 Identity Provider Discovery Service and ID-FF Identity Provider Introduction Service through the console. See To Customize the Identity Provider Services Through the Console.

To Create a Specialized WAR file for the Identity Provider Services

OpenSSO Enterprise provides a mechanism to create a specialized WAR file for the SAMLv2 Identity Provider Discovery Service and the ID-FF Identity Provider Introduction Service. The WAR file can be deployed as standalone application, independent of Identity Provider and Service Provider domains. See Creating and Deploying Specialized OpenSSO Enterprise WAR Files in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

After you deploy and run the Configurator for the specialized WAR file, locate the configuration property file named libIDPDiscoveryConfig.properties.

This file is created under the web container user's home directory. This file is the same for both the SAMLv2 IDP Discovery service and the ID-FF IDP Introduction service.

Customize the following properties to meet your specific deployment needs:

com.sun.identity.federation.services.introduction.cookiedomain

The value of this property is the name of the common domain.

com.sun.identity.federation.services.introduction.cookietype

This property takes a value of either PERSISTENT or SESSION. PERSISTENT defines the cookie as one that will be stored and reused after a web browser is closed and reopened. SESSION defines the cookie as one that will not be stored after the web browser has been closed.

com.iplanet.am.cookie.secure

This property takes a value of either false or true. It defines whether the cookie needs to be secured or not.

com.iplanet.am.cookie.encode

This property takes a value of either false or true. It defines whether the cookie will be URL encoded or not. This property is useful if, for example, the web container that reads or writes the cookie decrypts or encrypts it by default.

To Customize the Identity Provider Services Through the Console

Click the Configuration tab.

Click the Global sub-configuration tab.

Select the SAMLv2 Service Configuration service.

Customize the following attributes. These attributes are applicable for both the SAMLv2 Identity Provider Discovery Service and ID-FF Identity Provider Introduction Service:

Cookie Domain for IDP Discovery Service

Specifies the cookie domain for the SAMLv2 IDP discovery cookie.

Cookie Type for IDP Discovery Service

Specifies cookie type used in SAMLv2 IDP Discovery Service, either Persistent or Session. Default is Session.

URL Scheme for IDP Discovery Service

Specifies URL scheme used in SAMLv2 IDP Discovery Service.