Federation Management

Sun^™ ONE Identity Server contains a Federation Management module which implements the open standards for federated network identity being developed by the Liberty Alliance Project. This chapter explains the Liberty Alliance Project and the concept of federated network identity as well as describing how it is integrated within the Identity Server. It contains the following sections:

Overview

On the Internet, one person might have a multitude of accounts set up to access various business, community and personal service providers; for example, the person might have used different names, user IDs, passwords or preferences to set up accounts for a news portal, a bank, a retailer, and an email provider. A local identity refers to the set of attributes that an individual might have with each of these service providers. These attributes uniquely identify the individual with that provider and can include a name, phone number, passwords, social security number, address, credit records, bank balances or bill payment information.

Because the Internet is fast becoming the prime vehicle for business, community and personal interactions, it has become necessary to fashion a system for online users to link their local identities, enabling them to have one network identity. This system is identity federation. Identity federation allows a user to associate, connect or bind the local identities configured with multiple service providers. A federated identity allows users to login at one service provider’s site and move to an affiliated service provider site without having to re-authenticate or re-establish their identity. The Liberty Alliance Project was implemented for this purpose.

The Liberty Alliance Project

The goal of the Liberty Alliance Project is to enable individuals and organizations to easily conduct network transactions while protecting the individual’s identity. To accomplish this, the Alliance has established specifications for identity federation that enables:


Note	The Liberty Alliance Project’s specifications, v. 1.0 is no longer supported by Identity Server. As there are virtually no 1.0 deployments, this does not have a serious impact.

These capabilities can be achieved when commercial or non-commercial organizations join together into a circle of trust based on Liberty-enabled technology and operational agreements. This circle of trust includes service providers (who offer web-based services to users), identity providers (service providers that also maintian and manage identity information), and the users themselves. Once a circle of trust is established between providers, users can choose to federate any or all identities they might have with the service providers that have joined this circle, enabling them to make use of the federated authentication capabilities.

Liberty Specifications 1.1 Changes

Identity Server 6.0 used the Liberty Specifications, v.1.0 as the basis for its Federation Management Service. This current version of Identity Server is based on the Liberty Specifications, v.1.1. Some of the changes include:


Note	This chapter does not describe in detail the Liberty Alliance Project’s specifications, v. 1.1. For more information on the specifications and the authentication process referred to above, see the Liberty Alliance Project’s website at http://www.projectliberty.org.

Federation Concepts

The Federation Management module built into the Identity Server is designed to be compatible with the Liberty Alliance Project’s version 1.1 specifications. A number of concepts are derived from these specifications. For clarification, definitions of these concepts are provided in this section.

Account Federation (Identity Federation)

Account Federation occurs when a user chooses to unite distinct service accounts and identity provider accounts. Users retain the individual account information with each provider in the while, simultaneously, establishing a link that allows the exchange of authentication information between them.

Authentication Domain

Circle Of Trust

A Circle Of Trust is a group of service providers who agree to join together in order to exchange user authentication information using Liberty-enabled technologies. This Circle Of Trust must contain at least one Identity Provider. Once a Circle Of Trust is established, single sign-on is enabled between all the providers.

Common Domain


Note	A Circle Of Trust is, at times, referred to as an Authentication Domain although it is not a domain in the Internet sense of the word.

A common domain is a unique, Liberty-specifiedInternet domain between a Service Provider and an Identity Provider in a Circle Of Trust. The CommonDomain(Introduction) protocol helps service providers to find the preferred identity provider in a circle of trust. When a user authenticates to a service provider, a common domain cookie is used to store the user’s identity provider. (_liberty_idp is the cookie name.) When the user attempts to access a new service provider in the circle of trust, the service provider reads the common domain cookie and the request can be forwarded to the correct identity provider.

Federated Identity

A federated identity refers to the amalgamation of the account information in all service providers accessed by one user (personal data, authentication information, buying habits and history, shopping preferences, etc.). The information is administered by the user yet, with the user’s consent, their privilege to access information is securely shared with their providers of choice.

Federation Termination

Users have the ability to terminate federations. Federation termination (or defederation) results in the cancellation of affiliations established between the user’s identity provider and federated service provider accounts.

Identity Provider

Identity providers are service providers that specialize in providing authentication services. As the administrating service for authentication, they also maintain and manage identity information. Authentication accomplished by an Identity Provider is honored by all service providers with whom it is affiliated.

Name Identifier

To help preserve anonymity, identity federation maps a user’s account information across a number of service and identity provider organizations. The user’s identity is exchanged between the identity and service providers using a pseudonym or name identifier. Neither the identity provider nor the service provider should have knowledge of the user’s actual identity.

Service Provider

Service providers are commercial or not-for-profit organizations that offer web-based services. This broad category can include internet portals, retailers, transportation providers, financial institutions, entertainment companies, libraries, universities, and governmental agencies.

Single Logout

When a user logs out from an Identity Provider or a Service Provider, they will effectively be logged out from all service providers or identity providers in that authentication domain.

Single Sign-on

Single sign-on is established when a user with a Federated Identity authenticates to an Identity Provider. Because they have previously opted-in for federation, they are now able to access affiliated service providers without having to re-authenticate.

Trusted Provider

A Trusted Provider is a generic term for one of a group of service and identity providers in an Circle Of Trust. Users can transact and communicate with Trusted Providers in a secure environment.

Federation Process

Out of the box, Identity Server has two options for user authentication. The first is the proprietary Authentication Service; the second is the Liberty-enabled Federation Management. With the first option when a user tries to access a resource protected by Identity Server, they are redirected to the Authentication Service for authorization using an Identity Server login page. When the user provides credentials, the Authentication Service verifies them and either allows or denies access.

With the second option, Liberty-enabled Federation Management, when a user attempts to access an identity or service provider resource protected by Identity Server, the authentication process begins with a search for a valid Identity Server session token.


Note	More information on the process flow of the proprietary Authentication Service can be found in Chapter 3, "Authentication Service," of this manual.


Note	As discussed in "Cookies and Sessions" of Chapter 4, "Single Sign-On And Sessions," an Identity Server session token is inserted in a web server cookie.

If a session token is found, the user is granted access to the requested page. This page, assuming it belongs to a member of the Circle Of Trust, contains a link which, if clicked, directs the user through the Federation Single Sign-On Process process. If, on the other hand, no session token is found, the user moves through the Pre-Login Process.

Pre-Login Process

The purpose of the Pre-Login process is to establish a valid user session at the service provider site. When no Identity Server session token is found, the pre-login process begins with the search for another type of cookie, a Federation cookie.


Note	This sample process occurs when there is one identity provider. The flow changes a bit if there are mutiple identity providers.


Note	The Federation cookie is not the Identity Server cookie discussed in "Cookies and Sessions" of Chapter 4, "Single Sign-On And Sessions." The Federation cookie is a persistent cookie; it lives on the computer’s hard drive and is read into cache each time the browser is opened.

If, after the search for an Identity Server session token proves null, no Federation cookie is found either, an Identity Server login page is displayed and the user submits credentials to the Authentication Service. When authenticated by the Identity Server, the user is redirected to the requested page which contains a link to allow the user to federate their identity. If the user clicks this link, they are directed through the Federation Single Sign-On Process.

If though, after the search for an Identity Server session token proves null, a valid Federation cookie is found, it means the user has already been federated but not yet authenticated by an identity provider within the Circle Of Trust. This is confirmed by sending a request for authentication to the user’s identity provider. When an affirmative response is received back, the user is redirected to the Identity Server Authentication Service where they are automatically granted a session token and redirected to the requested page. If the response from the identity provider is negative (for instance, if the session has timed out), the user is sent back through the Federation Single Sign-On Process.

Federation Single Sign-On Process

The Federation Single Sign-On process gives the user the option to authenticate to, and federate their identity with, an identity provider. This federation affords access to all provider sites within the Circle Of Trust (including the service provider which houses the resource originally requested) without having to reauthenticate. Therefore, if an identity provider has responded to a request for authentication confirmation in the negative, the user is directed to a list of identity providers from which they can choose for authentication using the Federation Single Sign-On process. The user selects an identity provider and sends their credentials for authentication. Once authentication is granted, the user is redirected to the Identity Server Authentication Service where they are automatically granted a session token and redirected to the requested page which contains a link to allow the user to federate their identity for future single sign-on opportunities.


Note	A user who has an account defined with a service provider can only login to that service provider without federating. This is a local login. A federated login is when that same user logs into a different service provider via federation with an identity provider. The service provider has the option to turn off local login if it wants to honor federated login only. Both types of logins are demonstrated in the samples, located in IdentityServer_base/SUNWam/samples/liberty/.

The Federation Management Interface

The Federation Management module uses JavaServer Pages (JSP) to define the look and feel of its pages. JSP are HTML files that contain additional code to generate dynamic content. More specifically, JSP contain 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 will contain both the static HTML content and, in the case of the Federation Management module, dynamic content retrieved via calls to the Federation Management API. An administrator can customize the look and feel of the interface by changing the HTML tags in the JSP, but the APIs invoked must not be changed. By default, the JSP are located in IdentityServer_base/SUNWam/web-apps/services/config/federation/default. The files in this directory provide a default interface. To customize it for a specific organization, this default directory can be copied and renamed to reflect the name of the organization (or any value). It would then be placed at the same level as the default directory and the files within this directory would be modified as needed. Table 9-1 a list of the JSP with details on what each page is used for and the invoked APIs that cannot be modified.

Table 9-1 Federation Management Module JSP
File Name and its Purpose	Invoked APIs
CommonLogin.jsp displays the links to the login pages of the trusted Identity Providers as well as the local login page. It is displayed when the user is not logged in locally or at an Identity Provider site. The list of identity providers is obtained by the getIDPList(hostedProviderID) method.	LibertyManager.getLoginURL(request) LibertyManager.getInterSiteURL(request) LibertyManager.getIDPList(providerID) LibertyManager.getNewRequest(request) LibertyManager.getSuccintID(idpID) LibertyManager.cleanQueryString(request)
Error.jsp displays an error page when an error has occurred.	No APIs are invoked.
Federate.jsp is displayed when the user clicks a Federate link. It displays a drop-down list of all providers with which the user is not yet federated. This list is constructed from the getProvidersToFederate(userName, providerID) method.	LibertyManager.isLECPProfile(request) LibertyManager.getAuthnRequestEnvelope(request) LibertyManager.getUser(request) LibertyManager.getProvidersToFederate(providerID,userDN)
FederationDone.jsp displays the status of federation (success or cancelled). It checks this status using the isFederationCancelled(request) method.	LibertyManager.isFederationCancelled(request)
Footer.jsp displays a branded footer included on all the pages.	No APIs are invoked.
Header.jsp displays a branded header 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, they will be shown this JSP to select an authentication domain as their preferred domain. In the case that the provider belongs to only one domain, this page will not be displayed. The list is obtained by using the getListOfCOTs(providerID) method.	LibertyManager.getListOfCOTs(providerID)
LogoutDone.jsp displays the status of the local logout operation.	LibertyManager.isLogoutSuccess(request)
NameRegistration.jsp is displayed when a federated user chooses to register a new Name Identifier from a service provider to an identity provider. When the Name Registration link is clicked, this JSP is displayed.	LibertyManager.getUser(request) LibertyManager.getRegisteredProviders(userDN)
NameRegistrationDone.jsp displays the status of NameRegistration.jsp. When finished, this page is displayed.	LibertyManager.isNameRegistrationSuccess(request) LibertyManager.isNameRegistrationCanceled(request
Termination.jsp is displayed when the user clicks the defederate link. It shows a drop-down menu of all providers to which the user has federated; from this list, the user can choose to defederate. The list is constructed using the getFederatedProviders(userName) method which returns all active providers to which the user is already federated.	LibertyManager.getUser(request) LibertyManager.getFederatedProviders(userDN)
TerminationDone.jsp displays the status of federation termination (success or cancelled). It checks status using the isTerminationCancelled(request) method.	LibertyManager.isTerminationSuccess(request) LibertyManager.isTerminationCanceled(request)

Federation Management Protocols

The Federation Process is based on one of the protocols defined by the Liberty Alliance Project’s specifications. They are:

Identity Server provides the implementation of these Liberty protocols. A brief explanation of each protocol follows.

Single Sign-on and Federation Protocol

This is the protocol on which Identity Server bases the Federation Process. It defines the process that a user at a service provider goes through to authenticate their identity with an identity provider. It also specifies the means by which a service provider obtains an Authentication Assertion from an identity provider to allow single sign-on to the user. There are two types which either the identity or service provider can implement:

Federation Termination Notification Protocol

This is the protocol used to notify providers when a user’s existing federated identity is terminated. The termination can be initiated at either the identity or service provider. Said provider will notify all other providers in the Circle Of Trust when a user defederates. There are two types of notification which either the identity or service provider can implement:

Name Registration Protocol

At the time of federating a user account, the identity provider generates a name identifier, a pseudonym that all providers use when referring to the user during communications. This is the IDP Provided NameIdentifier. The identity provider may also register the name identifier at any time subsequent to federation. In addition, a service provider may register an SP Provided NameIdentifier which it expects the identity provider to use when communicating with it about the user account. If neither of the previous two scenarios occurs, the IDP Provided NameIdentifier generated at the time of federation is used by both providers.

Single Log-Out Protocol

This is the protocol used to synchronize the session log-out functionality across all sessions that were authenticated and created by a particular identity provider. There are two types which either the identity or service provider can implement:

IDP Introduction Protocol

In a Circle Of Trust that has more than one identity provider, the service providers need a way to determine which provider is preferred by the user. The Liberty specification defines a protocol which relies on a cookie written in a domain that is common between identity providers and service providers. This predetermined domain is the common domain and the cookie containing the preferred identity provider is known as the common domain cookie. The service provider can read this cookie value to identify a user’s preferred identity provider and get authentication assertions from that identity provider. Both identity providers and service providers can implement this protocol.


Note	It is recommended that the system clocks of all identity provider and service provider servers are synchronized. A time sync server can be used for this purpose.

Federation Management API

The LibertyManager class forms the basis of the Federation Management APIs. This interface is instantiated by web applications that want to access the Federation Management module. It contains the methods needed by the module JSPs for account federation, session termination, log in, log out and other actions. These methods include:

getSPList()—which returns a list of all trusted service providers.

getSPList(String hostedProviderID)—which returns a list of all trusted service providers for the specified hosted provider.

getIDPList()—which returns a list of all trusted identity providers.

getIDPList(String hostedProviderID)—which returns a list of all trusted identity providers for the specified hosted provider.

getSPFederationStatus(String user, String provider)—which retrieves the federations status of a user with a specific service provider. This method assumes that the user is already federated with the provider.

getIDPFederationStatus(String user, String provider)—which retrieves the federation status of a user with a specific identity provider. This method assumes that the user is already federated with the provider.

getFederatedProviders(String userName)—which returns a specific user’s federated providers.

getProvidersToFederate(String providerID, String userName)—which returns the list of all trusted identity providers to which the specified user is not already federated.

getListOfCOTs(String providerID)—which returns a list of authentication domains for the given provider.

Federation Management Samples

There are a number of samples included with the Identity Server that demonstrate the different protocols used in the Federation Management module. They are located in the IdentityServer_base/SUNWam/samples/liberty/ directory. Instructions on how to implement the samples can be found in the README.html file.

Sample 1 illustrates a scenario with one Service Provider and one Identity Provider configured on two separate Identity Server installations. Two server machines are required.

Sample 2 illustrates a scenario with one Service Provider whose resources are deployed on a Sun ONE Web Server protected by an Identity Server Policy Agent and one Identity Provider. It also demonstrates the configuration of different authentication levels for different resources. At least two server machines are required for this sample.

Sample 3 illustrates a multiple hosted providers scenario with two Service Providers and two Identity Providers. This sample scenario requires only one server machine and one Identity Server installation. Four hosted providers (two Service Providers and two Identity Providers) are created on the same Identity Server Installation.

Chapter 9 Federation Management