Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

Chapter 4 Common Domain Services for Federation Management

Sun Java System Access Manager provides the Common Domain Services for Federation Management that enable a service provider to determine the identity provider used by a principal in an authentication domain that contains multiple identity providers.

This chapter covers the following topics:

Common Domain

Service providers need a way to determine which identity provider is used by a principal requesting authentication. Because authentication domains are configured without regard to their location, this function must work across DNS-defined domains. Thus, a common domain is configured for this purpose. The common domain is established for use only within the scope of the Common Domain Services for Federation Management. In Access Manager deployments, the Common Domain Services for Federation Management are deployed in a web container installed in a predetermined and pre-configured common domain so that the common domain cookie is accessible to all providers in the authentication domain. If the HTTP server in the common domain is operated by the service provider, the service provider will redirect the user agent to the appropriate identity provider.

Let's suppose an authentication domain contains more than one identity provider; in this case, a service provider in the authentication domain trusts more than one identity provider. But, a principal can only issue a federation request to one identity provider, so the service provider to which the principal is requesting access must have the means to determine the correct one. To ascertain a principal’s identity provider, the service provider invokes a protocol exchange to retrieve the common domain cookie, a cookie written for the purpose of introducing the identity provider to the service provider. If no common domain cookie is found when the principal issues a federation request, the service provider must present a list of trusted identity providers from which the principal will choose. After successful authentication, the identity provider writes (using the Writer Service URL as defined in Configuring the Common Domain Services for Federation Management URLs) a common domain cookie. The next time the principal attempts to access a service, the service provider finds and reads the common domain cookie (using the Reader Service URL as defined in Configuring the Common Domain Services for Federation Management URLs), to determine the identity provider.

After a principal authenticates with a particular identity provider, the identity provider redirects the principal's browser to their Common Domain Services for Federation Management using a parameter that indicates they are the identity provider for this principal. The Common Domain Services for Federation Management then writes a cookie using that parameter. Thereafter, all providers configured in this common domain will be able to tell which identity provider is used by the principal. For example, suppose an identity provider is available at http://www.Bank.com and a service provider is available via http://www.Store.com. If the common domain they define is RetailGroup.com, the addresses will be Bank.RetailGroup.com and Store.RetailGroup.com, respectively.


Note –

The Common Domain Services for Federation Management is based on the Identity Provider Introduction Profile detailed in the Liberty ID-FF Bindings and Profiles Specifications.


Common Domain Cookie

After an identity provider authenticates a principal, the identity provider sets a URL-encoded cookie that is defined in a predetermined domain common to all identity providers and service providers within the authentication domain. The common domain cookie is named _liberty_idp. After successful authentication, a principal’s identity provider appends their encoded identifier to a list in the cookie. If their identifier is already present in the list, the identity provider may remove the initial appearance and append it again. The intent is that the service provider reads the last identifier on the cookie’s list to find the principal’s most recently established identity provider.

The identifiers in the common domain cookie are a list of SuccinctID elements encoded in the Base64 format. One element maps to each identity provider in the authentication domain. Service providers then use this SuccinctID element to find the user's preferred identity provider.


Note –

When the request contains no common domain cookie, the service provider presents a list of trusted identity providers from which the principal may choose.


Configuring the Common Domain Services for Federation Management URLs

In Access Manager, the Common Domain Services for Federation Management are configured using two URLs that point to servlets developed for writing and reading the common domain cookie. They are:


Note –

For more information on how to configure these URLs, see To Create An Authentication Domain in Chapter 3, Federation.


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 Writer Service URL defined for the identity provider. The URL is configured as the value for the Writer Service URL attribute when an authentication domain is created. Use the format http://common-domain-host:port/deployment-uri/writer where common-domain-host:port refers to the machine on which the Common Domain Services for Federation Management are installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs). The default URI is amcommon.

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 an authentication domain is created. It is formatted as http://common-domain-host:port/deployment-uri/transfer where common-domain-host:port refers to the machine on which the Common Domain Services for Federation Management are installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs). The default URI is amcommon.

Configuring the Common Domain Services for Federation Management Properties

FSIntroConfig.properties is a file that contains properties used to configure the Common Domain Services for Federation Management. It is deployed as part of the web application and located in /AccessManager-base/web-src/common/WEB-INF/classes. It contains the properties described in the following table (which may be modified).

Table 4–1 Common Domain Services for Federation Management Properties in FSConfig.properties

Property 

Description 

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.

Installing the Common Domain Services for Federation Management

The Common Domain Services for Federation Management are installed as a web application within Access Manager using the Sun Java Enterprise System installer. However, the Common Domain Services for Federation Management can also be installed as a standalone web application (separate from the Access Manager product) on a Java Enterprise Edition web container. This option allows for generating common domain cookies on a machine on which Access Manager is not installed. Once the Common Domain Services for Federation Management is installed, you must set up the writer URL attribute for any identity providers and the reader URL for any service providers. These URLs point to the machine on which Common Domain Services for Federation Management is installed. For more information, see the Sun Java Enterprise System 5 Installation Guide for UNIX.


Tip –

In most real world deployments, installing the Common Domain Services for Federation Management on a separate machine is the obvious choice because of the need to setup a third-level common domain between service providers and identity providers in disparate enterprises.


ProcedureTo Test a Common Domain Services for Federation Management Installation

For troubleshooting, make sure the debug level property in FSIntroConfig.properties is set to message.

  1. Install the Common Domain Services for Federation Management as a standalone application in a web container in the common domain.

    Ensure that the common domain has been defined and the web container is installed in it.

  2. Modify the properties in FSIntroConfig.properties as needed.

    See Configuring the Common Domain Services for Federation Management Properties for more information.

  3. Configure at least two identity providers for a service provider.

    Ensure that the Writer Service URL is configured for each identity provider and the Reader Service URL is configured for each service provider.

  4. Login as a user and complete federation and single sign-on between one identity provider and the service provider.

    Ensure that the _liberty_idp cookie is set to the common domain.

  5. Login as a user and complete federation and single sign-on between the second identity provider and the service provider.

    After the initial successful federation and single sign-on, all service providers in the common domain are redirected to the first identity provider based on the information in the common domain cookie.


    Note –

    Whether the cookie is persistent or for this browser session alone is dependent on how FSIntroConfig.properties is configured.