Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

Chapter 2 Implementation of the Liberty Alliance Project Specifications

Sun Java System Access Manager contains the Sun Microsystems implementation of the Liberty Alliance Project specifications. This chapter provides an overview of how these specifications have been implemented. It covers the following topics:

Overview

Sun Java System Access Manager is a software product that helps organizations manage secure access to the resources and web applications within their intranet and across the Internet. The initial release of Access Manager implemented the Liberty Identity Federation Framework (Liberty ID-FF) specifications, focusing on identity and provider federation, authentication domains, and single sign-on. Subsequent releases of Access Manager added new features as defined in version 1.2 of the Liberty ID-FF specifications as well as the version 1.1 specifications of the Liberty Identity Web Services Framework (Liberty ID-WSF). These web services include a framework for retrieving and updating identity data.

Identity data consists of all the information that companies maintain about individual customers, corporate partners, and employees. The data is stored in identity-based service providers (also referred to as identity providers) across the Internet. Federating the sources of identity data allows for accessing, transporting, sharing, and managing the data between partnered organizations and their applications without weakening existing security safeguards. For example, many corporations provide access to outsourced human resources services, such as health benefits and 401(k) plans. The corporate intranet offers central access to these services, but employees have to log in and authenticate themselves every time they access each service. Since employees might not want to share the same profile and password with both their 401(k) provider and their health care provider, federation of their identity data can provide seamless integration of these web resources across multiple security domains within the same enterprise.

To achieve this integration, enterprises can construct a network of partnered services for securely exchanging customer account information, transaction data, and credentials through a set of interoperable web services. Federation among partner networks allows identities to share key pieces of their respective data without sharing control. For example, logging in to one web site that represents an authentication domain consisting of an airline, a car rental company, and a hotel chain allows an identity to make travel plans even if one of the sites does not contain an identity data store.

The following sections contain additional information regarding the implementation of the Liberty Alliance Project specifications in Access Manager.

Sample Use Case

Using a cell phone, a principal is able to access a ring-tone vendor's site. Due to implementation of single sign-on, the ring-tone vendor recognizes the principal from the cell-phone provider's authentication. This allows the principal to purchase ring tones by interacting with the user's bank for payment. The following figure illustrates the process of requesting a service and being authenticated for access. It assumes the following:

MyWireless is a cellular service provider and an identity provider in a federation framework that contains access to the discovery service in a web services framework.
MyRingtones is a service provider in a federation framework that also acts as a web service consumer (WSC) in a web services framework. It sells ringtones for use with cellular phones.
MyBank is a web service provider (WSP) in a web services framework. Linking MyBank to My Ringtones offers the opportunity for seamless purchases.

Note –

The same web service can act as a different entity in different scenarios.

Figure 2–1 Process in a Liberty-enabled Use Case

This figure illustrates the process behind a
Liberty-enabled use case.

The user attempts to access MyRingtones and, after being prompted for credentials stored with MyBank, receives authorization through MyWireless. Single sign-on is accomplished in the back end. The entire process is based on implementations of the Liberty ID-FF, Liberty ID-WSF, and Liberty ID-SIS specifications.

Liberty Alliance Project Architecture in Access Manager

The figure below shows the architecture of the Access Manager features that are based on the Liberty Alliance Project specifications. These features leverage existing Access Manager services including those for policy, service management, session management, and auditing.

Figure 2–2 Liberty-based Architecture of Access Manager

Basic architecture of Liberty-based features
in Access Manager.

Note –

For a complete architectural overview of Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.

The Federation Module

The Federation component of Access Manager provides an interface for creating, modifying, and deleting authentication domains and service and identity providers (both remote and hosted types) for implementing a federated model. The web interface for the Liberty ID-FF in Access Manager is accessible from the Federation tab in the Access Manager Console, as shown.

Screen shot of the Federation interface in Access Manager Console

The Federation module includes the capabilities described in the following sections.

More information can be found in Chapter 3, Federation. For more information about the Liberty ID-FF functions, see the Liberty ID-FF Protocols and Schema Specifications.

Identity Federation and Single Sign-On

Let's assume that a principal has separate user accounts with a service provider and an identity provider in the same authentication domain. In order to gain access to these individual accounts, the principal authenticates with each provider separately. After authenticating with the service provider though, the principal can be given the option to federate the service provider account with the identity provider account. Consenting to the federation of these two accounts links them for the purpose of single sign-on. Single sign-on (SSO) is the means of passing a user's credentials between applications without the user having to reauthenticate each time an application is accessed. With Access Manager, 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 using the application's API.

To set up federated SSO, you must first establish SSO. Following this, configure the service provider application and the identity provider in Access Manager to enable federation using the Liberty Alliance Project protocols. Liberty ID-FF providers differentiate between federated users by defining a unique handle for each account. (They are not required to use the principal's actual provider account identifier.) Providers can also choose to create multiple handles 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 and service provider in a federation need to remember the principal's handle, they create entries that note the handle in their respective user repositories. In some scenarios, only the identity provider's handle is conveyed to a service provider. For example, if a service provider does not maintain its own user repository, the identity provider's handle is used.

Access Manager can accommodate the following functions:

Providers of either type give the principal notice upon identity federation or identity 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 give the principal a list of their federated identities.
Users can terminate federations or defederate identities.

Additionally, Access Manager can accommodate the following:

Auto-Federation

Auto federation will automatically federate a user's disparate provider accounts based on a common attribute. During single sign-on, 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 Auto-Federation.

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. The organization though needs the ability to federate user accounts behind the scenes. Access Manager 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 Bulk Federation.

Authentication and Authentication Context

Single sign-on 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 Access Manager 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 identities. 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 Security Assertion Markup Language (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. Access Manager provides the following authentication actions:

Supports a range of authentication methods (for example, password or certificate-based SSL).
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)
Allows an identity provider, at the discretion of the service provider, to authenticate a principal by using an identity provider other than itself (proxy) and relay this information back to the service provider.

SAML 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 Alliance Project 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 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 an identity provider. The identity provider sends an assertion that states the principal has been authenticated to a service provider. By including the authentication context, the service provider can place the 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 Alliance Project specifications define authentication context classes against which an identity provider can claim conformance. The Liberty-defined authentication contexts are listed and described in the following table.

Table 2–1 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.

The procedures in Entities contain a number of attributes related to authentication context. For more information, see the Liberty ID-FF Authentication Context Specification. 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.

Identifiers and Name Registration

Access Manager supports name identifiers that are unique across all providers in an authentication domain. This identifier can be used to obtain information for or about the principal (with consent) without requiring the user to consent to a long-term relationship with the service provider. During 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 though, the identity provider or the service provider may register a different opaque value. The reasons for doing this would be implementation-specific. 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.

Note –

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 Dynamic Identity Provider Proxying.

The Liberty-based Web Services Modules

Liberty-based web services are those based on specifications in the Liberty ID-WSF and the Liberty ID-SIS. They are accessible from the Access Manager Console by clicking the Web Services tab. The following diagram illustrates how the different web service specifications have been implemented.

Figure 2–3 Architecture of Liberty-based Web Services

Diagram illustrating the architecture of Liberty-based
web services in Access Manager.

The web interface for the Liberty ID-WSF in Access Manager is accessible from the Web Services tab in the Access Manager Console, as shown. The implemented web services include:

Screen shot of the Web Services interface in Access Manager Console.

Liberty Personal Profile Service

The Liberty Personal Profile Service is a data service that supports storing and modifying a principal's identity attributes. Identity attributes might include information such as first name, last name, home address, and emergency contact information. The Liberty Personal Profile Service is queried or updated by a WSC acting on behalf of the principal. For more information, see Chapter 7, Data Services.

Discovery Service

The Discovery Service is a web service that allows a requesting entity, such as a service provider, to dynamically determine a principal’s registered attribute provider. Typically, a service provider queries the Discovery Service, which responds by providing a resource offering that describes the location of the requested attribute provider. (A resource offering defines associations between a piece of identity data and the service instance that provides access to the data.) The implementation of the Discovery Service includes Java and web-based interfaces. For more information, see Chapter 8, Discovery Service.

Note –

By definition, a discoverable service is assigned a service type Uniform Resource Identifier (URI), allowing the service to be registered in Discovery Service instances. The service type URI is typically defined in the Web Service Definition Language (WSDL) file that defines the service.

SOAP Binding Service

The SOAP Binding Service is the method of transport used to convey identity data between web services. It includes a set of Java APIs used by the developer of a Liberty-enabled identity service. The APIs are used to send and receive identity-based messages using SOAP, an XML-based messaging protocol. The service invokes the correct request handler class (specified by a service endpoint) to handle the messages. For more information, see Chapter 9, SOAP Binding Service.

Authentication Web Service

The Authentication Web Service adds authentication functionality to the SOAP binding. It provides authentication to a WSC, allowing the WSC to obtain security tokens for further interactions with other services at the same provider. These other services may include a discovery service or single sign-on service. Upon successful authentication, the final Simple Authentication and Security Layer (SASL) response contains the resource offering for the Discovery Service. For more information, see Chapter 6, Authentication Web Service.

Caution –

Do not confuse the Liberty-based Authentication Web Service with the proprietary Access Manager Authentication Service discussed in the Sun Java System Access Manager 7.1 Technical Overview.

The Liberty-based Application Programming Interfaces

A number of the Liberty-based web services specifications have also been implemented in the back end of Access Manager as APIs. The services include the Interaction Service and PAOS binding. The following table summarizes the public APIs. They can be used to deploy Liberty-enabled components or extend the core services.

Table 2–2 Public Interfaces


Package Name	Description
`com.sun.identity.federation.plugins`	Contains interfaces which can be implemented to allow applications to customize their actions before and after invoking the federation protocols. See Chapter 3, Federation.
`com.sun.identity.federation.services`	Provides interfaces for writing custom plug-ins that can be used during the federation or single sign-on process. See Chapter 3, Federation.
`com.sun.identity.liberty.ws.authnsvc`	Provides classes to manage the Authentication Web Service. See Chapter 6, Authentication Web Service.
`com.sun.identity.liberty.ws.authnsvc.mechanism`	Provides an interface to process incoming Simple Authentication and Security Layer (SASL) requests and generate SASL responses for the different SASL mechanisms. See Chapter 6, Authentication Web Service.
`com.sun.identity.liberty.ws.authnsvc.protocol`	Provides classes to manage Authentication Web Service protocol. See Chapter 6, Authentication Web Service.
`com.sun.identity.liberty.ws.common`	Defines common classes that are used by many of the Access Manager Liberty-based web service components. See Common Service Interfaces of this chapter.
`com.sun.identity.liberty.ws.common.wsse`	Provides an interface to parse and create a X.509 Certificate Token Profile. See Common Service Interfaces of this chapter.
`com.sun.identity.liberty.ws.disco`	Provides interfaces to manage the Discovery Service. See Chapter 8, Discovery Service.
`com.sun.identity.liberty.ws.disco.plugins`	Provides a plugin interface for the Discovery Service. See Chapter 8, Discovery Service.
`com.sun.identity.liberty.ws.dst`	Provides classes to implement an identity service. See Chapter 7, Data Services for information about services built using this API.
`com.sun.identity.liberty.ws.dst.service`	Provides a handler class that can be used by any generic identity data service. See Chapter 7, Data Services for information about data services.
`com.sun.identity.liberty.ws.interaction`	Provides classes to support the Interaction RequestRedirect Profile. See the section on the Interaction Service for information on this profile.
`com.sun.identity.liberty.ws.interfaces`	Provides interfaces that are common to all Access Manager Liberty-based web service components. See Chapter 8, Discovery Service and Chapter 7, Data Services for information about default implementations. See the section on Common Service Interfaces for more general information.
`com.sun.identity.liberty.ws.paos`	Provides classes for web applications to construct and process PAOS requests and responses. See PAOS Binding of this chapter.
`com.sun.identity.liberty.ws.security`	Provides an interface to manage Liberty-based web service security mechanisms. See Common Security API of this chapter.
`com.sun.identity.liberty.ws.soapbinding`	Provides classes to construct SOAP requests and responses and to change the contact point for the SOAP binding. See Chapter 9, SOAP Binding Service.
`com.sun.identity.saml`	Provides a service provider interface (SPI) in which proprietary XML/signature implementations can be plugged in. See Chapter 10, SAML Administration.
`com.sun.identity.saml.assertion`	Provides classes to manage assertions and profiles. See Chapter 10, SAML Administration.
`com.sun.identity.saml.common`	Provides classes that are common to all SAML elements. See Chapter 10, SAML Administration.
`com.sun.identity.saml.plugins`	Provides SPIs to integrate SAML into custom services. See Chapter 10, SAML Administration.
`com.sun.identity.saml.protocol`	Provides classes that parse the XML messages used to exchange assertions and information. See Chapter 10, SAML Administration.
`com.sun.identity.saml.xmlsig`	Provides an SPI in which proprietary XML/signature implementations can be plugged in. See Chapter 10, SAML Administration.
`com.sun.liberty`	Provides interfaces common to the Access Manager Federation Management module. See Chapter 3, Federation.

For more information, see Chapter 11, Application Programming Interfaces. For detailed API documentation, including classes, methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

The SAML Service

Access Manager uses SAML as the means for exchanging security information. SAML uses an eXtensible Markup Language (XML) framework to achieve interoperability between vendor platforms that provide SAML assertions. Originally, the Liberty ID-FF was created as an extension of SAML 1.0 and 1.1. With the release of SAML 2.0 though, the Liberty ID-FF has been rolled into the SAML 2.0 specifications. Going forward, SAML 2.0 will be used by the Liberty Alliance Project to build additional federation—based applications. See The Liberty ID-FF Convergence for more information.

Note –

The configuration and usage of the SAML Service is independent of the SAML functionality used by the Liberty-based features in Access Manager. SAML usage by the Liberty-based features in Access Manager is behind the scenes and not configurable.

Access Manager 7.1 supports SAML 1.1 and 2.0. SAML 1.1 is supported out of the box and can be configured using the Access Manager Console. SAML 2.0 is supported after installing the SAML v2 Plug-in for Federation Services on top of a working instance of Access Manager. For more information on the SAML Service (based on SAML 1.1), see Chapter 10, SAML Administration. For more information on the SAML v2 Plug-in for Federation Services, see the Sun Java System SAML v2 Plug-in for Federation Services Release Notes and the Sun Java System SAML v2 Plug-in for Federation Services User’s Guide.

Liberty-Based Samples

Access Manager has included sample code and files that can be used to further understand the implementation of the Liberty Alliance Project specifications. For information about the specifics of these samples, see the individual chapters or Appendix A, Liberty-based and SAML Samples.