Chapter 6 Implementing the Liberty Alliance Project Identity-Federation Framework

Sun OpenSSO Enterprise has a robust framework for implementing federated single sign-on infrastructures based on the Liberty Alliance Project Identity-Federation Framework (Liberty ID-FF). It provides interfaces for creating, modifying, and deleting circles of trust, service providers, and identity providers as well as samples to get you started. This chapter covers the following topics:

Customizing the Federation Graphical User Interface

The Federation Service uses JavaServer Pages^TM (JSP^TM) to define its look and feel. JSP are HTML files that contain additional code to generate dynamic content. More specifically, a JavaServer page contains HTML code to display static text and graphics, as well as application code to generate information. When the page is displayed in a web browser, it contains both the static HTML content and, in the case of the Federation component, dynamic content retrieved through calls to the Federation API. An administrator can customize the look and feel of the interface by changing the HTML tags in the JSP but the invoked APIs must not be changed.

After a default installation, the JSP are located in /path-to-context-root/opensso/config/federation/default. The files in this directory provide the default content to the Liberty ID-FF Federation capability. To customize the pages for a specific organization, this default directory can be copied and renamed to reflect the name of the organization (or any value). This directory would then be placed at the same level as the default directory, and the files within this directory would be modified as needed. The following table lists the JSP including details on what each page is used for and the invoked API that cannot be modified.

Table 6–1 Federation JSP and Invoked Interfaces


JSP Name	Description
`CommonLogin.jsp`	Displays a link to the local login page as well as links to the login pages of the trusted identity providers. This page is displayed when a user is not logged in locally or with an identity provider. `com.sun.liberty.LibertyManager` is the invoked interface. The list of identity providers is obtained by using the `getIDPList(hostedProviderID)` method.
`Error.jsp`	Displays an error page when an error has occurred. `com.sun.liberty.LibertyManager` is the invoked interface.
`Federate.jsp`	When a user clicks a federate link on a provider page, this page displays a drop-down list of all providers with which the user is not yet federated. `com.sun.liberty.LibertyManager` is the invoked interface. The list is constructed with the `getProvidersToFederate(realm,providerID,providerRole,userName)` method.
`FederationDone.jsp`	Displays the status of a federation (success or cancelled). `com.sun.liberty.LibertyManager` is the invoked interface. It checks the status with the `isFederationCancelled(request)` method.
`Footer.jsp`	Displays a branded footer that is included on all the pages. No APIs are invoked.
`Header.jsp`	Displays a branded header that is included on all the pages. No APIs are invoked.
`ListOfCOTs.jsp`	Displays a list of circles of trust. When a user is authenticated by an identity provider and the service provider belongs to more than one circle of trust, this page displays and the user is prompted to select a circle of trust as their preferred domain. In the case that the provider belongs to only one domain, this page will not be displayed. `com.sun.liberty.LibertyManager` is the invoked interface. The list is obtained with the `getListOfCOTs(providerID)` method.
`LogoutDone.jsp`	Displays the status of the local logout operation. `com.sun.liberty.LibertyManager` is the invoked interface.
`NameRegistration.jsp`	When a federated user clicks a Name Registration link on a provider page to register a new Name Identifier from one provider to another, this JSP is displayed. `com.sun.liberty.LibertyManager` is the invoked interface.
`NameRegistrationDone.jsp`	Displays the status of `NameRegistration.jsp`. When finished, this page is displayed. `com.sun.liberty.LibertyManager` is the invoked interface.
`Termination.jsp`	When a user clicks a defederate link on a provider page, this page displays a drop-down list of all providers with which the user has federated and from which the user can choose to defederate. `com.sun.liberty.LibertyManager` is the invoked interface. The list is constructed with the `getFederatedProviders(userName)` method which returns all active providers to which the user is already federated.
`TerminationDone.jsp`	Displays the status of federation termination (success or cancelled). `com.sun.liberty.LibertyManager` is the invoked interface. Status is checked using the `isTerminationCancelled(request)` method.

Using the Liberty ID-FF Packages

The following packages form the Federation API. For more detailed information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

`com.sun.identity.federation.accountmgmt`

The com.sun.identity.federation.accountmgmt package contains the FSAccountFedInfo class which retrieves the information from the federated user account. After Liberty ID-FF federation is successfully completed, two attributes are set. The FSAccountFedInfo class contains the value of one of them: the iplanet-am-user-federation-info attribute.

`com.sun.identity.federation.common`

The com.sun.identity.federation.common package contains the IFSConstants interface which represents common constants used by the federation API.

`com.sun.identity.federation.message`

The com.sun.identity.federation.message package contains classes which define the federation protocol messages.

`com.sun.identity.federation.message.common`

The com.sun.identity.federation.message.common package contains classes which can be used by federation protocol messages.

`com.sun.identity.federation.plugins`

The com.sun.identity.federation.plugins package contains the FederationSPAdapter interface which can be implemented to allow applications to customize user specific processing before and after invoking the federation protocols. For example, a service provider may want to choose to redirect to a specific location after successful single sign-on. A singleton instance of this FederationSPAdapter is used during runtime so make sure the implementation of the methods (except initialize()) are thread safe.

`com.sun.identity.federation.services`

The com.sun.identity.federation.services package provides interfaces for writing custom plug-ins that can be used during the federation or single sign-on process. The interfaces are described in the following table.

Table 6–2 com.sun.identity.federation.services Interfaces


Interface	Description
`FSRealmAttributeMapper`	Plug-in for mapping the attributes passed from the identity provider to local attributes on the service provider side during the single sign-on. `com.sun.identity.federation.services.FSDefaultRealmAttributeMapper` is the default implementation.
`FSRealmAttributePlugin`	Plug-in for an identity provider to add `AttributeStatements` into a SAML assertion during the single sign-on process. `com.sun.identity.federation.services.FSDefaultRealmAttributePlugin` is the default implementation.
`FSRealmIDPProxy`	Interface used to find a preferred identity provider to which an authentication request can be proxied. `com.sun.identity.federation.services.FSRealmIDPProxyImpl` is the default implementation.

`com.sun.liberty`

The com.sun.liberty package contains the LibertyManager class which must be instantiated by web applications that want to access the Federation framework. It also contains the methods needed for account federation, session termination, log in, log out and other actions. Some of these methods are described in the following table.

Table 6–3 com.sun.liberty Methods


Method	Description
`getFederatedProviders()`	Returns a specific user's federated providers.
`getIDPFederationStatus()`	Retrieves a user's federation status with a specified identity provider. This method assumes that the user is already federated with the provider.
`getIDPList()`	Returns a list of all trusted identity providers.
`getIDPList()`	Returns a list of all trusted identity providers for the specified hosted provider.
`getProvidersToFederate()`	Returns a list of all trusted identity providers to which the specified user is not already federated.
`getSPList()`	Returns a list of all trusted service providers.
`getSPList()`	Returns a list of all trusted service providers for the specified hosted provider.
`getSPFederationStatus()`	Retrieves a user's federation status with a specified service provider. This method assumes that the user is already federated with the provider.

Accessing Liberty ID-FF Endpoints

For each Liberty ID-FF feature, there are endpoints listening for requests or generating responses. The endpoint URLs are provided in the metadata that is exchanged with other partners in the circle of trust. Following is a list of the Liberty ID-FF endpoints:

SOAPReceiver is a servlet that listens for SOAP-communicated requests. For example, single logout or requests for artifacts.
ProcessLogout is a servlet that accepts HTTP-based single logout requests.
ProcessTermination is a servlet that accepts HTTP-based federation termination requests.
ProcessRegistration is a servlet that accepts Name Identifier registration requests.
SingleSignOnService is a servlet on the identity provider side that accepts single sign-on requests.
ReturnLogout is a servlet that accepts single logout return requests.
AssertionConsumerService is a servlet on the service provider side that accepts single sign-on responses.

Executing the Liberty ID-FF Sample

OpenSSO Enterprise includes sample code and files that can be used to demonstrate the different Liberty ID-FF protocols such as Account Federation, Single Sign On, Single Logout and Federation Termination. The sample is located in /path-to-context-root/opensso/samples/idff. Open index.html for more information.