Sun OpenSSO Enterprise 8.0 Technical Overview

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

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 – 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:

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.


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:

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:

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:

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.

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