Sun OpenSSO Enterprise 8.0 Technical Overview

Part III Federation Management Using OpenSSO Enterprise

Sun OpenSSO Enterprise provides a framework for implementing a federated identity infrastructure, enabling single sign-on, provisioning users dynamically, and sharing identity attributes across security domains. The chapters in this third part of the Sun OpenSSO Enterprise Technical Overview contains information on federation management.

Chapter 9 What is Federation?

Federation establishes a standards-based method for sharing and managing identity data and establishing single sign-on across security domains and organizations. It allows an organization to offer a variety of external services to trusted business partners as well as corporate services to internal departments and divisions. Forming trust relationships across security domains allows an organization to integrate applications offered by different departments or divisions within the enterprise as well as engage in relationships with cooperating business partners that offer complementary services. Towards this end, multiple industry standards, such as those developed by the Organization for the Advancement of Structured Information Standards (OASIS) and the Liberty Alliance Project, are supported. This chapter contains an overview of federation.

The Concept of Federation

As a concept, federation encompasses both identity federation and provider federation.

Identity Federation

In one dictionary, identity is defined as ”a set of information by which one person is definitively distinguished.” This information undoubtedly begins with the document that corroborates a person's name: a birth certificate. Over time, additional information further defines different aspects of an individual's identity. The composite of this data constitutes an identity with each specific piece providing a distinguishing characteristic. Each of the following represents data that designates a piece of a person's identity as it relates to the enterprise for which the data was defined.

An address
A telephone number
One or more diplomas
A driver’s license
A passport
Financial institution accounts
Medical records
Insurance statements
Employment records
Magazine subscriptions
Utility bills

Because the Internet is now one of the primary vehicles for the types of interactions represented by identity-defining information, people are creating online identities specific to the businesses with which they are interacting. By creating a user account with an identifier and password, an email address, personal preferences (such as style of music, or opt-in/opt-out marketing decisions) and other information specific to the particular business (a bank account number or ship-to address), a user is able to distinguish their account from others who also use the enterprise’s services. This distinguishing information is referred to as a local identity because it is specific to the service provider (a networked entity that provides one or more services to other entities) for which it has been defined. Sending and receiving email, checking bank balances, finalizing travel arrangements, accessing utility accounts, and shopping are just a few online services for which a user might define a local identity. If a user accesses all of these services, many different local identities have been configured. Considering the number of service providers for which a user can define a local identity, accessing each one can be a time-consuming and frustrating experiencing. In addition, although most local identities are configured independently (and fragmented across the Internet), it might be useful to connect the information. For example, a user's local identity with a bank could be securely connected to the same user's local identity with a utility company for easy, online payments. This virtual phenomenon offers an opportunity for a system in which users can federate these local identities. Identity federation allows the user to link, connect, or bind the local identities that have been created for each service provider. The linked local identities, referred to as a federated identity, allow the user to log in to one service provider site and click through to an affiliated service provider without having to reauthenticate or reestablish identity; in effect, single sign-on (SSO).

Provider Federation

Provider federation begins with a circle of trust. A circle of trust is a group of service providers who contractually agree to exchange authentication information. Each circle of trust must include at least one identity provider, a service provider that maintains and manages identity data, and provides authentication services. After the business contracts and policies defining a circle of trust are in place, the specific protocols, profiles, endpoints, and security mechanisms being used by each member is collected into a metadata document that is exchanged among all other members of the circle. OpenSSO Enterprise provides the tools necessary to integrate the metadata and enable a circle of trust technologically. Authentication within this federation is honored by all membered providers.

Note –

The establishment of contractual trust agreements between providers is beyond the scope of this guide. See The Concept of Trust for an overview.

The Concept of Trust

Federating identities assumes existing trust relationships between participants. This trust is usually defined through business arrangements or contracts that describe the technical, operational, and legal responsibilities of each party and the consequences for not completing them. When defined, a trust relationship allows one organization to trust the user authentication and authorization decisions of another organization. This trust then enables a user to log in to one site and, if desired, access a trusted site without reauthentication.

Ensure that trust agreements are in force before configuring circles of trust with OpenSSO Enterprise and going live. The Liberty Alliance Project has created a support document for helping to establish these trust arrangements. The Liberty Trust Model Guidelines document is located on the Support Documents and Utility Schema Files page of the Liberty Alliance Project web site.

How Federation Works

The goal of federation is to enable individuals and service providers to protect identity data while conducting network transactions across secure domains. When organizations form a trust agreement, they agree to exchange user authentication information using specific web technologies. The trust agreement would be among multiple service providers that offer web-based services to users and, at least, one identity provider (a service provider that maintains and manages identity information). Once metadata (a particular provider's federation configuration information) is exchanged and the trust is established technologically, single sign-on can be enabled between all the included providers, and users may opt to federate their multiple identities (depending on the protocol being used). In OpenSSO Enterprise, the trust agreement is virtually configured as a circle of trust using the console or command line interface. A circle of trust contains providers (service providers or identity providers) that are grouped together for the purpose of offering identity federation. Identity federation occurs when a user chooses to unite distinct service provider and identity provider accounts while retaining the individual account information with each provider. The user establishes a link that allows the exchange of authentication information between provider accounts. Users can choose to federate any or all identities they might have. After identity federation, when a user successfully authenticates to one of the service providers, access to any of the federated accounts within the circle of trust is allowed without having to reauthenticate. The following figure shows the subjects involved in federation.

Figure 9–1 Subjects Involved in an Identity Federation

A figure illustrating the federation model.

A principal can have a defined local identity with more than one provider, and it has the option to federate the local identities. The principal might be an individual user, a group of individuals, a corporation, or a component of the Liberty architecture.
A service provider is a commercial or not-for-profit organization that offers a web-based service such as a news portal, a financial repository, or retail outlet.
An identity provider is a service provider that stores identity profiles and offers incentives to other service providers for the prerogative of federating their user identities. Identity providers might also offer services above and beyond those related to identity profile storage.
To support identity federation, all service providers and identity providers must join together into a circle of trust. A circle of trust must contain at least one identity provider and at least one service provider. (One organization may be both an identity provider and a service provider.) Providers in a circle of trust must first write trust agreements to define their relationships. A trust agreement is a contract between organizations that defines how the circle will work. For more information, see The Concept of Trust.

A travel portal is a good example of a circle of trust. Typically, a travel portal is a web site designed to help you access various travel-related services from one location. The travel portal forms a partnership with each service provider displayed on its web site. (This might include hotels, airlines, and car rental agencies.) The user registers with the travel portal which, in effect, is the identity provider for the circle of trust. After logging in, the user might click through to an airline service provider to look for a flight. After booking a flight, the user might click through to an accommodations service provider to look for a hotel. Because of the trust agreements previously established, the travel portal shares authentication information with the airline service provider, and the airline service provider with the accommodations service provider. The user moves from the hotel reservations web site to the airline reservations web site without having to reauthenticate. All of this is transparent to the user who must, depending on the underlying federation protocol, choose to federate any or all local identities. The following figure illustrates the travel portal example.

Figure 9–2 Federation Within a Travel Portal

This figure illustrates how a user's identity
can be shared among many businesses such as airlines, car rental agencies,
and hotels.

Chapter 10 Federation Management with OpenSSO Enterprise

Sun OpenSSO Enterprise provides a pluggable framework for implementing federated identity infrastructures. The Federation framework places no restrictions on the use of network technologies, computer hardware, operating systems, programming languages or other hardware or software entities. It is based on, and conforms to, open industry standards to achieve interoperability among different vendors on heterogeneous systems, and provides the facility to log identity interactions and erroneous conditions. The following sections contain information about the federation framework.

Key Federation Management Features

OpenSSO Enterprise creates a comprehensive security and identity management framework optimized to work with, and extend, an identity provider's existing security infrastructure. The following list describes some key features:

Exchange of credentials and security tokens across circle of trust partners for purposes of authentication and single sign-on.
Automatic federation of user accounts across multiple security domains.
Session management across authentication domains to determine when user interactions must be terminated (single logout).
Import or export the data required to establish basic federated communication between providers.
Manages and links providers that are available to participate in a circle of trust.
Exchanges SAML security assertions among providers in a circle of trust.
Data management choices include an LDAPv3 directory (OpenDS, Sun Java System Directory Server or Microsoft Active Directory).
Included service provider interfaces (SPIs) to allow customized logic during the federation process.
Support for bulk federation and auto federation.
Support for The Fedlet, a web archive (WAR) of data that can be embedded into a service provider application.
Support for Virtual Federation.
Support for multiple federation protocols in one circle of trust.

The following sections contain additional information on the final three features listed.

The Fedlet

Fedlet is the name given to fedlet.war. The WAR is a very small archive of a few JARs, properties, and metadata (all stored in flat files) that can be embedded into a service provider's Java EE web application to allow for SSO between an identity provider instance of OpenSSO Enterprise and the service provider application - WITHOUT installing OpenSSO Enterprise on the service provider side. The service provider simply downloads the Fedlet, modifies their application to include the Fedlet JARs and, re-archives and redeploys the modified application. The service provider is now able to accept an HTTP POST (that contains a SAML v2 assertion) from the identity provider and retrieve included user attributes to accomplish SSO. (Currently, the Fedlet only supports the HTTP POST Profile.). The Fedlet can communicate with multiple identity providers, using a Discovery Service to find the preferred identity provider. For more information, see the Sun OpenSSO Enterprise 8.0 Administration Guide.

Secure Attribute Exchange/Virtual Federation Proxy

Secure Attribute Exchange (also referred to as Virtual Federation Proxy) provides a mechanism for one application to communicate identity information to a second application in a different domain. In essence, it provides a secure gateway that enables legacy applications to communicate authentication attributes without having to deal specifically with federation protocols and processing. Virtual Federation Proxy allows:

Identity provider applications to push user authentication, profile and transaction information to a local instance of OpenSSO Enterprise which then passes the data to a remote instance of OpenSSO Enterprise at the service provider using federation protocols.
Service provider applications to consume the received information.

Virtual Federation Proxy uses SAML v2 to transfer identity data between the communicating entities. The Client SDK (which contains Java and .NET interfaces) runs independent of OpenSSO Enterprise and enables existing applications to handle the SAML v2 interactions. The following diagram illustrates this scenario.

Figure 10–1 Virtual Federation Architecture

The following use cases are applicable to Virtual Federation:

Authentication at Identity Provider

When a user is already authenticated within an enterprise, the legacy identity provider application sends a secure HTTP GET/POST message to OpenSSO Enterprise asserting the identity of the user. OpenSSO Enterprise verifies the authenticity of the message and establishes a session for the authenticated user. You can use Virtual Federation to transfer the user's authentication information to the local instance of OpenSSO Enterprise in order to create the session.

Virtual Federation at Identity Provider

When a user is already authenticated by, and attempts access to, a legacy identity provider application, the legacy application sends a secure HTTP POST message to the local instance of OpenSSO Enterprise asserting the user's identity, and containing a set of attribute/value pairs related to the user (for example, data from the persistent store representing certain transactional states in the application). OpenSSO Enterprise verifies the authenticity of the message, establishes a session for the authenticated user, and populates the session with the user attributes.

Virtual Federation at Service Provider

When a user is already authenticated by the instance of OpenSSO Enterprise at the identity provider and invokes an identity provider application that calls for redirection to a service provider, the identity provider invokes one of the previous use cases and encodes a SAML v2 SSO URL as a part of the request. The identity provider instance of OpenSSO Enterprise then initiates SAML v2 SSO with the instance of OpenSSO Enterprise at the service provider. The service provider's instance of OpenSSO Enterprise then verifies the SAML v2 assertion and included attributes, and redirects to the service provider application, securely transferring the user attributes via a secure HTTP POST message. The service provider application consumes the attributes, establishes a session, and offers the service to the user.

Global Single Logout

When a user is already authenticated and has established, for example, SSO with the instance of OpenSSO Enterprise at the service provider, the user might click on a Global Logout link. The identity provider will then invalidate its local session (if created) and trigger SAML v2 single log out by invoking a provided OpenSSO Enterprise URL. The OpenSSO Enterprise identity provider executes the SAML v2 single log out, terminating the session on both provider instances of OpenSSO Enterprise.

Note –

An identity provider side application can initiate single logout by sending sun.cmd=logout attributes via a Virtual Federation interaction to a local instance of OpenSSO Enterprise acting as the identity provider. In turn, this instance will execute SAML v2 single logout based on the current session.

For more information, see the Sun OpenSSO Enterprise 8.0 Administration Guide.

Multi-Federation Protocol Hub

OpenSSO Enterprise allows a configured circle of trust to contain entities speaking different federation protocols thus supporting cross protocol single sign-on and logout among hosted identity providers in the same circle of trust. For example, you can create a circle of trust containing one identity provider instance that communicates with multiple federation protocol and three service provider instances that speak, respectively, Liberty ID-FF, SAML v2 and WS-Federation. Figure 10–2 illustrates the process of multi-federation protocol single sign-on and single logout.

Figure 10–2 Multi-Federation Protocol Single Sign-on and Single Logout

Process of multi-federation protocol single sign-on
and single logout

For more information, see the Sun OpenSSO Enterprise 8.0 Administration Guide.

The Federation Framework Architecture

OpenSSO Enterprise consists of web-based services [using SOAP, XML over HTTP(S) or HTML over HTTP(S)], and Java—based application provider interfaces (APIs) and service provider interfaces (SPIs). The figure below illustrates this architecture. Additionally, the figure shows an agent embedded into a web container. This agent enables the service provider applications to participate in the SAML or Liberty-based protocols. The darker boxes are components provided by OpenSSO Enterprise.

Figure 10–3 Federation Framework Architecture

This figure illustrates the federation framework
architecture.

The components include:

SAML Service: Provides SAML related services (versions 1.x and 2.0) including artifact and POST profile support, and assertion query support.
Liberty Identity Federation Framework (Liberty ID-FF): Provides services based on the Liberty ID-FF specifications. Features include federation and single sign-on, single logout, federation termination, name registration, and support for the Common Domain. Implemented web services include a SOAP binding service, a discovery service, a personal profile service, and an authentication service.
WS-Federation: Provides services based on the WS-Federation specifications.
Authentication: OpenSSO Enterprise provides a JAAS-based authentication framework.
Session: OpenSSO Enterprise provides session management for service provider applications.
Logging: OpenSSO Enterprise provides a logging service. It also provides activity logs for auditing. Audit logs can be stored in flat files or JDBC-compliant databases.
APIs: Includes a set of APIs for interaction between the SSO, logging, SAML, federation, and authentication components. Also included are APIs to build web services for clients and providers.
SPIs: Includes a set of Service Provider Interfaces (SPIs) into which applications can insert their custom logic. For instance, there is an SPI to do post federation processing, and an SPI for post processing after a successful single logout.

Chapter 11 Choosing a Federation Option

Sun OpenSSO Enterprise supports multiple federation standards, such as those developed by the Organization for the Advancement of Structured Information Standards (OASIS) and the Liberty Alliance Project. This chapter contains information on these federation options.

Federation Options

Federation is used to solve the problem of cooperation across heterogeneous, autonomous environments. In the beginning, federation meant using the Liberty Alliance Project Identity Federation Framework (Liberty ID-FF). Since then, other federation specifications have been developed including the Security Assertion Markup Language (SAML) and WS-Federation. OpenSSO Enterprise supports all of these specifications.

To get started, SAML v2 is strongly preferred for federation. WS-Federation is an alternative for integrating with Active Directory Federation Services (ADFS). Liberty ID-FF and SAML v1.x are still supported but should only be used when SAML v2 is not an option as the SAML v2 specification supersedes both the Liberty ID-FF and SAML v1.x specifications. More information on these options can be found in the following sections:

Note –

OpenSSO Enterprise has appropriated the terms from the Liberty ID-FF for all federation protocol implementations in the OpenSSO Enterprise console.

Using SAML

SAML defines an XML-based framework for exchanging identity information across security domains for purposes of authentication, authorization and single sign-on. It was designed to be used within other specifications (the Liberty Alliance Project, the Shibboleth project, and the Organization for the Advancement of Structured Information Standards have all adopted aspects of SAML) although the latest release (SAML v2) has incorporated back into the framework elements from the specifications developed by those very same organizations. The SAML specifications consist of a number of components, illustrated by Figure 11–1.

Figure 11–1 Components of the SAML Specifications

The SAML specification defines the assertion security token format as well as profiles that standardize the HTTP exchanges required to transfer XML requests and responses between an asserting authority and a trusted partner. An assertion is a package of verified security information that supplies one or more statements concerning a principal’s authentication status, access authorization decisions, or identity attributes. (A person identified by an email address is a principal as might be a printer.) Assertions are issued by an asserting authority (a platform or application that declares whether a subject has been authenticated into its system), and received by relying parties (partner sites defined by the authority as trusted). Asserting authorities use different sources to configure assertion information, including external data stores or assertions that have already been received and verified.

The most recent SAML v2 specifications are defined more broadly than those developed for SAML v1.x — with particular attention paid to functionality dealing with federation. Before SAML v2 was introduced, SAML v1.x was simply a way to exchange identity data. In fact, up to version 1.1, the Liberty Alliance Project Identity Federation Framework (Liberty ID-FF) was developed using the SAML 1.0 specification. Liberty ID-FF version 1.2 was also developed using the SAML v1.1 specification. But, following the release of version 1.2, the Liberty ID-FF was incorporated into the SAML v2 specification. Additionally, SAML v2 adds components of the Shibboleth initiative. Thus, SAML v2 is a major revision, providing significant additional functionality and making the previous versions of SAML incompatible with it. Going forward, SAML v2 will be the basis on which OpenSSO Enterprise implements federation. Figure 11–2 illustrates the convergence.

Figure 11–2 Liberty ID-FF and SAML Convergence

Illustration of Liberty ID-FF and SAML convergence

Note –

For more information on this convergence (including how the Shibboleth Project was also integrated), see the Federation section of Strategic Initiatives on the Liberty Alliance Project web site.

More information on the SAML implementations can be found in the following sections).

Caution –

SAML v1.x and SAML v2 assertions and protocol messages are incompatible.

About SAML v2

OpenSSO Enterprise delivers a solution that allows businesses to establish a framework for sharing trusted information across a distributed network of partners using the standards-based SAML v2. Towards this end, HTTP(S)-based service endpoints and SOAP service endpoints are supplied as well as assertion and protocol object manipulating classes. A web browser can access all HTTP(S)-based service endpoints and an application can make use of the SOAP endpoints and API as long as metadata for each participating business on BOTH sides of the SAML v2 interaction is exchanged beforehand.

Figure 11–3 illustrates the SAML v2 framework which consists of web-based services [using SOAP, XML over HTTP(S) or HTML over HTTP(S)], and Java™-based application provider interfaces (API) and service provider interfaces (SPI). Additionally, the figure shows an agent embedded into a web container in which a service provider application is deployed. This agent enables the service provider to participate in the SAML v1.x or Liberty ID-FF protocols.

Figure 11–3 SAML v2 Architecture

This figure illustrates the architecture of SAML v2.

The following sections contain more information about the SAML v2 framework.

Key Features

The key features of SAML v2 in OpenSSO Enterprise include:

Single sign-on using the POST profile, the Artifact binding (also referred to as HTTP redirect), and unsolicited responses (initiated by the identity provider)
Single logout using HTTP redirect and SOAP binding
Federation termination using HTTP redirect and SOAP binding
Auto-federation (automatic linking of service provider and identity provider user accounts based on a common attribute)
Bulk federation
Dynamic creation of user accounts
One time federation (transient NameID format for SSO)
Basic Authentication, SSL and SSL with client authentication for SOAP binding security
SAML v2 authentication
Identity provider discovery
XML verification, signing, encryption and decryption
Profile initiation and processing using included JavaServer Pages™ (JSP™)
Load balancing support
IDP Proxy
Assertion failover
Enhanced Client or Proxy (ECP) support in SP and IDP
Assertion queries and requests
Attribute queries
New Name Identifier
Affiliation
Name Identifier Mapping
XACML profile for authorization

Note –
See XACML Service for more information.
Protocol coexistence with the SAML v1.x and the Liberty ID-FF

Additionally, OpenSSO Enterprise has received high scores and passed the Liberty Alliance Project interoperability tests for SAML v2. For more information, see the SAMLv2 support matrix on the Liberty Alliance Project web site.

Administration

In order to communicate using the SAML v2 profiles you need, at least, two instances of OpenSSO Enterprise. One instance will act for the identity provider and the other will act for the service provider. Name identifiers are used to communicate regarding a user.

Note –

SAML v2 single sign-on interactions support both persistent and transient identifiers. A persistent identifier is saved to a particular user entry as the value of two attributes. A transient identifier is temporary and no data will be written to the user's data store entry.

To prepare your instances for SAML v2 interactions, you need to exchange a particular provider's configuration information or metadata between all participating identity and service providers, and assemble the providers into a circle of trust. Utility APIs can then be used to communicate with the data store, reading, writing, and managing the relevant properties and property values. For more information see the Sun OpenSSO Enterprise 8.0 Administration Guide.

Application Programming Interfaces

The SAML v2 framework contains API that can be used to construct and process assertions, requests, and responses. The SAML v2 Java API packages include:

The com.sun.identity.saml2.assertion package provides interfaces to construct and process SAML v2 assertions. It also contains the AssertionFactory, a factory class used to obtain instances of the objects defined in the assertion schema.
The com.sun.identity.saml2.common package provides interfaces and classes used to define common SAML v2 utilities and constants.
The com.sun.identity.saml2.protocol package provides interfaces used to construct and process the SAML v2 requests and responses. It also contains the ProtocolFactory, a factory class used to obtain object instances for concrete elements in the protocol schema.

More information can be found in Using the SAML v2 SDK in Sun OpenSSO Enterprise 8.0 Developer’s Guide and the Sun OpenSSO Enterprise 8.0 Java API Reference.

Service Provider Interfaces

The com.sun.identity.saml2.plugins package provides pluggable interfaces to implement SAML v2 functionality into your application. Default implementations are provided, but a customized implementation can be plugged in by modifying the corresponding attribute in the provider's extended metadata configuration file. The interfaces include mappers for:

Account mapping (map between the account referred to in the incoming request and the local user account)
Attribute mapping (specifies which set of user attributes in an identity provider user account needs to be included in an assertion, and maps the included attributes to attributes in the user account defined by the service provider)
Authentication context mapping (map between Authentication Contexts defined in the SAML v2 specifications and authentication framework schemes defined in OpenSSO Enterprise (user/module/service/role/level based authentication)
Service provider adapter (allows user to plug-in application specific logic before and/or after single sign-on, single logout, termination and new name identifier process.

More information can be found in Service Provider Interfaces in Sun OpenSSO Enterprise 8.0 Developer’s Guide and the Sun OpenSSO Enterprise 8.0 Java API Reference.

JavaServer Pages

The SAML v2 framework provides JSP that can be used to initiate single sign-on, single logout and termination requests from either the identity provider or the service provider using a web browser. The JSP accept query parameters to allow flexibility in constructing SAML v2 requests; they can be modified for your deployment. More information can be found in JavaServer Pages in Sun OpenSSO Enterprise 8.0 Developer’s Guide.

About SAML v1.x

OpenSSO Enterprise can be configured to use SAML v1.x to achieve interoperability between vendor platforms that provide SAML v1.x assertions. Assertions are issued by a SAML v1.x asserting authority (a platform or application that declares whether a subject has been authenticated into its system), and received by relying parties (partner sites defined by the authority as trusted). SAML v1.x authorities use different sources to configure the assertion information, including external data stores or assertions that have already been received and verified. SAML v1.x can be used to allow OpenSSO Enterprise to:

Authenticate users and access trusted partner sites without having to reauthenticate; in effect, single sign-on.
Act as a policy decision point (PDP), allowing external applications to access user authorization information for the purpose of granting or denying access to their resources. For example, employees of an organization can be allowed to order office supplies from suppliers if they are authorized to do so.
Act as both an attribute authority that allows trusted partner sites to query a subject’s attributes, and an authentication authority that allows trusted partner sites to query a subject’s authentication information.
Validate parties in different security domains for the purpose of performing business transactions.
Build Authentication, Authorization Decision, and Attribute Assertions using the SAML v1.x API.
Permit an XML-based digital signature signing and verifying functionality to be plugged in.

Note –

Although Liberty ID-FF (as described in Using the Liberty ID-FF) integrates aspects of the SAML v1.x specifications, its usage of SAML v1.x is independent of the SAML v1.x framework as described in this section.

Figure 11–4 illustrates how SAML v1.x interacts with the other components in OpenSSO Enterprise.

Figure 11–4 SAML v1.x Interaction in OpenSSO Enterprise

This figure illustrates SAML v1.x interaction
within OpenSSO Enterprise.

Which Flavor of SAML to Use?

When choosing the flavor of SAML to use there are a number of things that should be taken into account. For example, SAML v1.x and SAML v2 assertions and protocol messages are incompatible. The following section have more information to help make the decision.

Using SAML v2 or OpenSSO Enterprise CDSSO

Cross Domain Single Sign On (CDSSO) is a proprietary mechanism from Sun OpenSSO Enterprise, designed before any federation specifications existed. The basic difference between the proprietary CDSSO (as described in Part II, Access Control Using OpenSSO Enterprise) and SAML v2 is that CDSSO uses a single authentication authority, a mechanism to move a cookie between multiple DNS domains. SAML v2, on the other hand, gives you the option of using multiple authentication authorities, with one authority asserting the identity of the user to the other.

CDSSO, in certain cases, is easier to set up and manage than federation but, federation solves a broader set of single sign-on issues than CDSSO. CDSSO requires all policy agents to be configured to use a single OpenSSO Enterprise server. This means only one user identity can exist in the entire system whereas, when using SAML v2, user identities can exist on multiple systems (service providers or identity providers). Because of the single identity in CDSSO interactions, issues such as account mapping, attribute flow and session synchronization are not relevant thus, if you need to implement these features, use SAML v2. If the following points are valid to your planned deployment, CDSSO may be a simpler and more suitable solution than federation.

Only Sun OpenSSO Enterprise and Sun policy agents are involved.
Sun policy agents are configured to use the same OpenSSO Enterprise infrastructure where multiple instances can exist.
OpenSSO Enterprise uses a single user identity store.
Multiple instances of OpenSSO Enterprise (configured for high-availability) must reside in a single DNS domain. Only policy agents can reside in different DNS domains.

For more information on CDSSO, see Chapter 6, Models of the User Session and Single Sign-On Processes.

Using SAML v1.x or Liberty ID-FF

The Liberty ID-FF (as described in Using the Liberty ID-FF) and SAML v1.x should only be used when integrating with a partner that is not able to use SAML v2. SAML v1.x was designed to address the issue of cross-domain single sign-on. It does not solve issues such as privacy, single logout, and federation termination. The Liberty Alliance Project was formed to develop technical specifications that would solve business process issues including single sign-on, account linking and consent, among others.

The SAML v1.x specifications and the Liberty Alliance Project specifications do not compete with one another. They are complementary. In fact, the Liberty Alliance Project specifications leverage profiles from the SAML specifications. The decision of whether to use SAML v1.x or the Liberty specifications depends on your goal. In general, SAML v1.x should suffice for single sign-on basics. The Liberty Alliance Project specifications can be used for more sophisticated functions and capabilities, such as global sign-out, attribute sharing, web services. The following table compares the benefits of the two.

Table 11–1 Comparison of the SAML v1.x and Liberty Alliance Project Specifications


SAML v1.x Uses	Liberty Alliance Project Uses
Cross-domain single sign-on	Single sign-on only after user federation
No user federation	User federation
No privacy control, best for use within one company	Built on top of SAML
User identifier is sent in plain text	User identifier is sent as a unique handle
Single log out	Single log out

Using the Liberty ID-FF

The Liberty Alliance Project was formed to develop technical specifications that would solve business process issues including single sign-on, federation and consent. The Liberty Alliance Project Identity Federation Framework (Liberty ID-FF) uses a name identifier to pass identity data between identity providers and service providers. The name identifier is a randomly generated character string that is assigned to a principal and used to federate the principal's accounts at the identity provider and service provider sites. This pseudonym allows all providers to identify a principal without knowing the user's actual identity. The name identifier has meaning only in the context of the relationship between providers. SAML v1.x is used for provider interaction.

Note –

Liberty ID-FF was initially defined as an extension of SAML 1.0 (and later SAML 1.1). The extensions have now been contributed back into SAML v2 which, going forward, will be the basis on which the Liberty Alliance Project builds additional federated identity applications. See Using SAML for more information on this convergence.

The following sections contain information about the Liberty ID-FF and the features implemented in OpenSSO Enterprise.

Liberty ID-FF Features

The following sections contain information about the Liberty ID-FF features implemented in OpenSSO Enterprise.

Federated Single Sign-On

Let's assume that a principal has separate user accounts with a service provider and an identity provider in the same circle of trust. In order to gain access to these individual accounts, the principal would authenticate with each provider separately. If federating with the Liberty ID-FF though, after authenticating with the service provider, the principal may be given the option to federate the service provider account with the identity provider account. Consenting to the federation of these accounts links them for SSO, the means of passing a user's credentials between applications without the user having to reauthenticate. SSO and federated SSO have different processes. With OpenSSO Enterprise, you can achieve SSO in the following ways:

Install a policy agent in a web container to protect the application and pass the HTTP_HEADER and REMOTE_USER variables to the application to capture the user credentials. You may or may not need a custom authentication module.
Customize the application's authentication module to create an SSOToken from the request object or from the SSO cookie. Afterwards, retrieve the user credentials using the SSO API and create a session data structure using the application's API.

To set up federated SSO, you must first establish SSO. Following that, enable federation in the metadata for the service provider entity and the identity provider entity using OpenSSO Enterprise. Liberty ID-FF providers differentiate between federated users by defining a unique identifier for each account. (They are not required to use the principal's actual provider account identifier.) Providers can also choose to create multiple identifiers for a particular principal. However, identity providers must create one handle per user for service providers that have multiple web sites so that the handle can be resolved across all of them.

Note –

Because both the identity provider entity and the service provider entity in a federation need to remember the principal's identifier, they create entries that note the value in their respective user repositories. In most scenarios, the identity provider's identifier is conveyed to a service provider and not visa versa. For example, if a service provider does not maintain its own user repository, the identity provider's identifier is used.

OpenSSO Enterprise can accommodate the following SSO and federation-related functions:

Providers of either type notify the principal upon identity federation or defederation.
Providers of either type notify each other regarding a principal's defederation.
Identity providers notify the appropriate service providers regarding a principal's account termination.
Providers of either type display a list of federated identities to the principal.
Users can terminate federations or defederate identities.

Additionally, OpenSSO Enterprise can accommodate the federation features explained in the following sections.

Auto-Federation

Auto federation will automatically federate a user's disparate provider accounts based on a common attribute. During SSO, if it is deemed a user at provider A and a user at provider B have the same value for the defined common attribute (for example, an email address), the two accounts will be federated without consent or interaction from the principal. For more information, see Part II, Federation, Web Services, and SAML Administration, in Sun OpenSSO Enterprise 8.0 Administration Guide.

Bulk Federation

Federating one user's service provider account with their identity provider account generally requires the principal to visit both providers and link them. An organization though needs the ability to federate user accounts behind the scenes. OpenSSO Enterprise provides a script for federating user accounts in bulk. The script allows the administrator to federate many (or all) of a principal's provider accounts based on metadata passed to the script. Bulk federation is useful when adding a new service provider to an enterprise so you can federate a group of existing employees to the new service. For more information, see Part II, Federation, Web Services, and SAML Administration, in Sun OpenSSO Enterprise 8.0 Administration Guide.

Authentication and Authentication Context

SSO is the means by which a provider of either type can convey to another provider that a principal has been authenticated. Authentication is the process of validating user credentials; for example, a user identifier accompanied by an associated password. You can authenticate users with OpenSSO Enterprise in the following ways:

Use a policy agent to insert HTTP header variables into the request object. This functions for web applications only.
Use the authentication API to validate and retrieve user identity data. This will work with either web or non-web applications.

Identity providers use local (to the identity provider) session information mapped to a user agent as the basis for issuing SAML authentication assertions to service providers. Thus, when the principal uses a user agent to interact with a service provider, the service provider requests authentication information from the identity provider based on the user agent's session information. If this information indicates that the user agent's session is presently active, the identity provider will return a positive authentication response to the service provider. OpenSSO Enterprise allows providers to exchange the following minimum set of authentication information with regard to a principal.

Authentication status (active or not)
Instant (time authenticated)
Authentication method
Pseudonym (temporary or persistent)

SAML v1.x is used for provider interaction during authentication but not all SAML assertions are equal. Different authorities issue SAML assertions of different quality. Therefore, the Liberty ID-FF defines how the consumer of a SAML assertion can determine the amount of assurance to place in the assertion. This is referred to as the authentication context, information added to the SAML assertion that gives the assertion consumer the details they need to make an informed entitlement decision. For example, a principal uses a simple identifier and a self-chosen password to authenticate to a service provider. The identity provider sends an assertion to a second service provider that states how the principal was authenticated to the first service provider. By including the authentication context, the second service provider can place an appropriate level of assurance on the associated assertion. If the service provider were a bank, they might require stronger authentication than that which has been used and respond to the identity provider with a request to authenticate the user again using a more stringent context. The authentication context information sent in the assertion might include:

The initial user identification mechanism (for example, face-to-face, online, or shared secret).
The mechanisms for minimizing compromise of credentials (for example, private key in hardware, credential renewal frequency, or client-side key generation).
The mechanisms for storing and protecting credentials (for example, smart card, or password rules).
The authentication mechanisms (for example, password or smart card with PIN).

The Liberty ID-FF specifications define authentication context classes against which an identity provider can claim conformance. The Liberty ID-FF authentication contexts are listed and described in the following table.

Table 11–2 Authentication Context Classes


Class	Description
MobileContract	Identified when a mobile principal has an identity for which the identity provider has vouched.
MobileDigitalID	Identified by detailed and verified registration procedures, a user's consent to sign and authorize transactions, and DigitalID-based authentication.
MobileUnregistered	Identified when the real identity of a mobile principal has not been strongly verified.
Password	Identified when a principal authenticates to an identity provider by using a password over an unprotected HTTP session.
Password-ProtectedTransport	Identified when a principal authenticates to an identity provider by using a password over an SSL-protected session.
Previous-Session	Identified when an identity provider must authenticate a principal for a current authentication event and the principal has previously authenticated to the identity provider. This affirms to the service provider a time lapse from the principal's current resource access request. Note – The context for the previously authenticated session is not included in this class because the user has not authenticated during this session. Thus, the mechanism that the user employed to authenticate in a previous session should not be used as part of a decision on whether to now allow access to a resource.
Smartcard	Identified when a principal uses a smart card to authenticate to an identity provider.
Smartcard-PKI	Identified when a principal uses a smart card with an enclosed private key and a PIN to authenticate to an identity provider.
Software-PKI	Identified when a principal uses an X.509 certificate stored in software to authenticate to the identity provider over an SSL-protected session.
Time-Sync-Token	Identified when a principal authenticates through a time synchronization token.

For more information, see the Liberty ID-FF Authentication Context Specification and . Additionally, there is an XML schema defined which the identity provider authority can use to incorporate the context of the authentication in the SAML assertions it issues.

The Common Domain for Identity Provider Discovery

Service providers need a way to determine which identity provider in a circle of trust is used by a principal requesting authentication. Because circles of trust are configured without regard to their location, this function must work across DNS-defined domains. A common domain is configured, and a common domain cookie written, for this purpose.

Let's suppose a circle of trust contains more than one identity provider. In this case, a service provider trusts more than one identity provider so, when a principal needs authentication, the service provider with which the principal is communicating must have the means to determine the correct identity provider. 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, the service provider will present a list of trusted identity providers from which the principal can choose. After successful authentication, the identity provider writes (using the configured Writer Service URL) a common domain cookie and, the next time the principal attempts to access a service, the service provider finds and reads the common domain cookie (using the configured Reader Service URL), to determine the identity provider. More information on the Common Domain for Identity Provider Discovery is available in the following sections, and in Finding an Identity Provider for Authentication in Sun OpenSSO Enterprise 8.0 Administration Guide.

The Common Domain

The common domain is established for use only within the scope of identity provider discovery in a defined circle of trust. In OpenSSO Enterprise deployments, the identity provider discovery WAR is deployed in a web container installed in a predetermined and preconfigured common domain so that the common domain cookie is accessible to all providers in the circle of trust. For example, if an identity provider is available at http://www.Bank.com, a service provider is available at http://www.Store.com, and the defined common domain is RetailGroup.com, the addresses will be Bank.RetailGroup.com and Store.RetailGroup.com, respectively. 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.

The Common Domain Cookie

After an identity provider authenticates a principal, the identity provider sets a URL-encoded cookie defined in a predetermined domain common to all identity providers and service providers in the circle of trust. The common domain cookie is named _liberty_idp for Liberty ID-FF and _saml_idp for SAML v2. After successful authentication, a principal’s identity provider appends their particular 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.

Note –

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 circle of trust. Service providers then use this SuccinctID element to find the user's preferred identity provider.

The Writer Service and the Reader Service

After a principal authenticates with a particular identity provider, the identity provider redirects the principal's browser to the configured Writer Service URL using a parameter that indicates they are the identity provider for this principal. The Writer Service then writes a cookie using the parameter. Thereafter, all providers configured in this common domain will be able to tell which identity provider is used by this principal. Thus, the next time the principal attempts to access a service hosted by a service provider in the same common domain, the service provider retrieves and reads the common domain cookie, using the configured Reader Service URL, to determine the identity provider.

The Writer Service URL and the Reader Service URL can be defined for use with the Liberty ID-FF or the SAML v2 federation protocol. The URLs are defined when you create a circle of trust for federation. The Common Domain for Identity Provider Discovery for Liberty ID-FF is based on the Identity Provider Introduction Profile detailed in the Liberty ID-FF Bindings and Profiles Specifications. The Common Domain for Identity Provider Discovery for SAML v2 is an implementation of the Identity Provider Discovery Profile as described in the Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 specification.

Identifiers and Name Registration

OpenSSO Enterprise supports name identifiers that are unique across all providers in a circle of trust. This identifier can be used to obtain information for or about the principal without requiring the user to consent to a long-term relationship with the service provider. When beginning federation, the identity provider generates an opaque value that serves as the initial name identifier that both the service provider and the identity provider use to refer to the principal when communicating with each other. After federation, the identity provider or the service provider may register a different opaque value. If a service provider registers a different opaque value for the principal, the identity provider must use the new identifier when communicating with the service provider about the principal. The reasons for changing an identifier would be implementation-specific. The initial name identifier defined by the identity provider is always used to refer to the principal unless a new name identifier is registered.

Global Logout

A principal may establish authenticated sessions with both an identity provider and individual service providers, based on authentication assertions supplied by the identity provider. When the principal logs out of a service provider session, the service provider sends a logout message to the identity provider that provided the authentication for that session. When this happen, or the principal manually logs out of a session at an identity provider, the identity provider sends a logout message to each service provider to which it provided authentication assertions under the relevant session. The one exception is the service provider that sent the logout request to the identity provider.

Dynamic Identity Provider Proxying

An identity provider can choose to proxy an authentication request to an identity provider in another authentication domain if it knows that the principal has been authenticated with this identity provider. The proxy behavior is defined by the local policy of the proxying identity provider. However, a service provider can override this behavior and choose not to proxy. This function can be implemented as a form of authentication when, for instance, a roaming mobile user accesses a service provider that is not part of the mobile home network. For more information see ID-FF Federation Operations in Sun OpenSSO Enterprise 8.0 Administration Guide.

About the Liberty ID-FF Process

The Liberty ID-FF is designed to work with heterogeneous platforms, various networking devices (including personal computers, mobile phones, and personal digital assistants), and emerging technologies. The process of Liberty ID-FF federation begins with authentication. A user attempting to access a resource protected by OpenSSO Enterprise are redirected to the proprietary Authentication Service via an OpenSSO Enterprise login page. After the user provides credentials, the Authentication Service allows or denies access to the resource based on the outcome.

Note –

For more information about the proprietary Authentication Service, see the Chapter 7, Authentication and the Authentication Service.

When the user attempts access to a resource that belongs to a trusted member provider of a configured circle of trust, the process of user authentication begins with the search for a valid OpenSSO Enterprise session token from the proprietary Authentication Service. The process can go in one of two directions based on whether a session token is found.

If no session token is found, the principal is redirected to a location defined by the pre-login URL to establish a valid session.
If a session token is found, the principal is granted (or denied) access to the requested page. Assuming access is granted, the requested page contains a link so the principal may federate the OpenSSO Enterprise identity with the identity local to the requested site. If the principal clicks this link, federation begins.

Figure 11–5 illustrates these divergent paths. The process shown is the default process when no application has been deployed. When an application is deployed and using OpenSSO Enterprise, the process will change based on the query parameters and preferences passed to OpenSSO Enterprise from the participating application. For more information, see Sun OpenSSO Enterprise 8.0 Administration Guide.

Figure 11–5 Default Process of Federation

Illustration depicting the default process of Liberty ID-FF federation
in OpenSSO Enterprise.

As illustrated, the pre-login process establishes a valid OpenSSO Enterprise session. When a principal attempts to access a service provider site and no OpenSSO Enterprise session token is found, OpenSSO Enterprise searches for a federation cookie. A federation cookie is implemented by OpenSSO Enterprise and is called fedCookie. It can have a value of either yes or no, based on the principal’s federation status.

Note –

A federation cookie is not defined in the Liberty Alliance Project specifications.

At this point, the pre-login process may take one of the following paths:

If a federation cookie is found and its value is no, a OpenSSO Enterprise login page is displayed and the principal submits credentials to the proprietary Authentication Service. When authenticated by OpenSSO Enterprise, the principal is redirected to the requested page, which might contain a link to allow for identity federation. If the principal clicks this link, federation begins.
If a federation cookie is found and its value is yes, the principal has already federated an identity but has not been authenticated by an identity provider within the circle of trust for this OpenSSO Enterprise session. Authentication to OpenSSO Enterprise is achieved on the back end by sending a request to the principal’s identity provider. After authentication, the principal is directed back to the requested page.
If no federation cookie is found, a passive authentication request (one that does not allow identity provider interaction with the principal) is sent to the principal’s identity provider. If an affirmative authentication is received back from the identity provider, the principal is directed to the OpenSSO Enterprise Authentication Service, where a session token is granted. The principal is then redirected to the requested page. If the response from the identity provider is negative (for example, if the session has timed out), the principal is sent to a common login page to complete either a local login or Liberty ID-FF federation.

Using WS-Federation

WS-Federation is part of the larger Web Services Security (WS-Security) framework which provides a means for applying security to web services through the use of security tokens. WS-Security describes how to attach signature and encryption headers as well as security tokens (including binary security tokens such as X.509 certificates and Kerberos tickets) to SOAP messages. WS-Trust, another specification in the WS-Security framework, provides for federation by defining a Security Token Service (STS) and a protocol for requesting and issuing the security tokens. WS-Federation, as implemented in OpenSSO Enterprise, uses the OpenSSO Enterprise Security Token Service (modelled on the WS-Trust specification) to allow providers in different security realms to broker trust using information on identities, identity attributes and authentication, and provider federation. A principal requests a token from the Security Token Services. This token, which may represent the principal's primary identity, a pseudonym, or the appropriate attributes, is presented to the service provider for authentication and authorization. WS-Federation uses several security tokens as well as the mechanism for associating them with messages. This release of OpenSSO Enterprise has implemented the following features of the WS-Federation specification.

The Web (Passive) Profile defines single sign-on, single logout, attribute and pseudonym token exchanges for passive requestors; for example, a web browser that supports HTTP. For the passive mechanisms to provide a single or reduced sign-on, there needs to be a service that will verify that the claimed requestor is really the requestor. Initial verification MUST occur in a secure environment; for example, using SSL/TLS or HTTP/S. The token is abstract and the token exchange is based on the Security Token Service model of WS-Trust.
Tokens based on the Web Services-Interoperability Basic Security Profile (WS-I BSP) define security that is implemented inside a SOAP message; and security implemented at the transport layer, using HTTPS. The protocol covers how you generate or handle security tokens.

The WS-Federation implementation in OpenSSO Enterprise is based on the application's SAML v2 code and uses WS-Federation 1.1 metadata. Authentication request parameters are represented directly as GET parameters, and the authentication response is a WS-Trust RequestSecurityTokenResponse element.

Note –

There is no authentication context mapping, persistent or transient NameID identifiers or auto-federation in the OpenSSO Enterprise implementation of WS-Federation.

The entry points for all WS-Federation functionality will be implemented as servlets. JavaServer Pages (JSP) are used only for HTML content (for example, the HTML form used to send the WS-Federation single response from the identity provider to the service provider). The following figure illustrates the flow of messages between OpenSSO Enterprise (acting as the service provider) and the Active Directory (acting as the identity provider).

Figure 11–6 WS-Federation Process Flow

Process flow of WS-Federation functionality

In a WS-Federation interaction, the request by an unauthenticated user attempting to access a protected web site is redirected to the Active Directory for Federation Services (ADFS) identity provider. After the user is authenticated (either by a back-end single sign-on or by entering credentials), ADFS posts a form containing a signed SAML assertion to the service provider. The service provider validates the assertion, copies the attributes into the user's session, and gives the appropriate access.

Note –

Microsoft Active Directory Federation Services supports single sign-on via WS-Federation.