Sun OpenSSO Enterprise 8.0 Developer's Guide

SAML v2

The following sections include information on the implementation of SAML v2 in OpenSSO Enterprise.

Using the SAML v2 SDK

The SAML v2 framework provides interfaces that can be used to construct and process assertions, requests, and responses. The SDK is designed to be pluggable although it can also be run as a standalone application (outside of an instance of OpenSSO Enterprise).

Exploring the SAML v2 Packages

The SAML v2 SDK includes the following packages:

For more detailed information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

com.sun.identity.saml2.assertion Package

This 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.

com.sun.identity.saml2.common Package

This package provides interfaces and classes used to define common SAML v2 utilities and constants.

com.sun.identity.saml2.plugins Package

This package provides service provider interfaces to implement for plug-ins.

com.sun.identity.saml2.protocol Package

This package provides interfaces used to construct and process the SAML v2 request/response protocol. It also contains the ProtocolFactory, a factory class used to obtain object instances for concrete elements in the protocol schema.

Setting a Customized Class

There are two ways you can set a customized implementation class:

  1. Add a customized mapper as a value for the Advanced Properties of the appropriate server using the OpenSSO Enterprise console.

    1. Login to the OpenSSO Enterprise console as the administrator.

    2. Click the Configuration tab.

    3. Click Servers & Sites and select the server.

    4. Click the Advanced tab.

    5. Click Add and enter the full interface name as the Property Name and the implemented class name as the Property Value.

      For example, com.sun.identity.saml2.sdk.mapping.Assertion and com.ourcompany.saml2.AssertionImpl, respectively.

  2. Set an environment variable for the Virtual Machine for the Java™ platform (JVM™). For example, you can add the following environment variable when starting the application:


    -Dcom.sun.identity.saml2.sdk.mapping.Assertion=com.ourcompany.saml2.AssertionImpl

Service Provider Interfaces

The com.sun.identity.saml2.plugins package provides pluggable interfaces to extend SAML v2 functionality into your remote application. The classes can be configured per provider entity. 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 mappers include:

For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Account Mappers

An account mapper is used to associate a local user account with a remote user account based on the Name ID (or another specific attribute value) in the Assertion. A default account mapper has been developed for both sides of the SAML v2 interaction, service providers and identity providers.

If implementing a custom account mapper, change the value of the provider's Account Mapper property using the OpenSSO Enterprise console.

IDPAccountMapper

The IDPAccountMapper interface is used on the identity provider side to map user accounts in cases of single sign-on and federation termination. The default implementation is provided in by com.sun.identity.saml2.plugins.DefaultIDPAccountMapper. During single sign-on, the DefaultIDPAccountMapper returns the Name Identifier to be set in an Assertion based on the entity provider's configuration; for example, the user's profile attributes can be set as the value of the Name ID using the NameID Value Map field in the console.

SPAccountMapper

The SPAccountMapper interface is used on the service provider side to map user accounts in cases of single sign-on and federation termination. The default implementation, com.sun.identity.saml2.plugins.DefaultSPAccountMapper, supports mapping based on the transient and persistent NameID attributes, and attribute federation based on properties defined in the extended metadata configuration file. The user mapping is based on information passed from the identity provider in an <AttributeStatment>.

Attribute Mappers

An attribute mapper is used to associate attribute names passed in the <AttributeStatement> of an assertion. A default attribute mapper has been developed for both participants in the SAML v2 interaction, service providers and identity providers. They are defined in the extended metadata configuration files and explained in the following sections:

If implementing a custom attribute mapper, change the value of the provider's Attribute Mapper property using the OpenSSO Enterprise console.

IDPAttributeMapper

The IDPAttributeMapper interface is used by the identity provider to specify which user attributes will be included in an assertion. The default implementation, com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper, retrieves attribute mappings (SAML v2-attribute=user-attribute) defined in the attributeMap property in the identity provider's extended metadata configuration file. It reads the value of the user attribute from the identity provider's data store, and sets this value as the <AttributeValue> of the specified SAML v2 attribute. The SAML v2 attributes and values are then included in the <AttributeStatement> of the assertion and sent to the service provider. The value of attributeMap can be changed to modify the mapper's behavior without programming. The default mapper itself can be modified to attach any identity provider user attribute with additional programming.

The identity provider can also send different AttributeStatement elements for different service providers. To support this, define an attribute mapping in the remote service provider's metadata hosted on the identity provider side. This configuration will override the attribute mapping defined on the hosted identity provider itself. (The hosted identity provider configuration serves as the default if no attribute mapping is defined in the service provider metadata.

SPAttributeMapper

The SPAttributeMapper interface is used by the service provider to map attributes received in an assertion to its local attributes. The default implementation, com.sun.identity.saml2.plugins.DefaultSPAttributeMapper, retrieves the attribute mappings defined in the attributeMap property in the service provider's extended metadata configuration file. It extracts the value of the SAML v2 attribute from the assertion and returns a key/value mapping which will be set in the user's single sign-on token. The mapper can also be customized to choose user attributes from the local service provider datastore.


Note –

*=* is a special attribute mapping which can be defined for a service provider hosted on an instance of OpenSSO Enterprise only. (It is not valid for a remote service provider configured on the identity provider side.) It will map all the attribute names as presented in the Assertion. (It will keep the same name as in the AttributeStatement element. Enter this as a value of the Attribute Map property under the service provider configuration Assertion Processing tab.


Authentication Context Mappers

Authentication context refers to information added to an assertion regarding details of the technology used for the actual authentication action. For example, a service provider can request that an identity provider comply with a specific authentication method by identifying that method in an authentication request. The authentication context mapper pairs a standard SAML v2 authentication context class reference (PasswordProtectedTransport, for example) to a OpenSSO Enterprise authentication scheme (module=LDAP, for example) on the identity provider side and sets the appropriate authentication level in the user's SSO token on the service provider side. The identity provider would then deliver (with the assertion) the authentication context information in the form of an authentication context declaration added to the assertion. The process for this is described below.

  1. A user accesses spSSOInit.jsp using the AuthnContextClassRef query parameter.

    For example, http://SP_host:SP_port/uri/spSSOInit.jsp?metaAlias=SP_MetaAlias&idpEntityID=IDP_EntityID&AuthnContextClassRef=PasswordProtectedTransport

  2. The SPAuthnContextMapper is invoked to map the value of the query parameter to a <RequestedAuthnContext> and an authentication level.

  3. The service provider sends the <AuthRequest> with the <RequestedAuthnContext> to the identity provider.

  4. The identity provider processes the <AuthRequest> by invoking the IDPAuthnContextMapper to map the incoming information to a defined authentication scheme.


    Note –

    If there is no matching authentication scheme, an authentication error page is displayed.


  5. The identity provider then redirects the user (including information regarding the authentication scheme) to the Authentication Service for authentication.

    For example, http://osso_host:osso_port/uri/UI/Login?module=LDAP redirects to the LDAP authentication module.

  6. After successful authentication, the user is redirected back to the identity provider for construction of a response based on the mapped authentication class reference.

  7. The identity provider then returns the user to the assertion consumer on the service provider side.

  8. After validating the response, the service provider creates a single sign-on token carrying the authentication level defined in the previous step.

A default authentication context mapper has been developed for both sides of the SAML v2 interaction. Details about the mappers are in the following sections:

If implementing a custom authentication context mapper, change the value of the provider's Authentication Context Mapper property using the OpenSSO Enterprise console.

IDPAuthnContextMapper

The IDPAuthnContextMapper is configured for the identity provider and maps incoming authentication requests from the service provider to a OpenSSO Enterprise authentication scheme (user, role, module, level or service-based authentication), returning a response containing the authentication status to the service provider. The following attributes in the identity provider extended metadata are used by the IDPAuthnContextMapper:

SPAuthnContextMapper

The SPAuthnContextMapper is configured for the service provider and maps the parameters in incoming HTTP requests to an authentication context. It creates a <RequestedAuthnContext> element based on the query parameters and attributes configured in the extended metadata of the service provider. The <RequestedAuthnContext> element is then included in the <AuthnRequest> element sent from the service provider to the identity provider for authentication. The SPAuthnContextMapper also maps the authentication context on the identity provider side to the authentication level set as a property of the user's single sign-on token. The following query parameters can be set in the URL when accessing spSSOInit.jsp:

An example URL might be http://SP_host:SP_port/uri/spSSOInit.jsp?metaAlias=SP_MetaAlias&idpEntityID=IDP_EntityID&AuthnContextClassRef=PasswordProtectedTransport&AuthLevel=4&AuthComparision=minimum

The following attributes in the service provider extended metadata are used by the SPAuthnContextMapper:

Assertion Query/Request Mappers

The Assertion Query/Request profile specifies a means for requesting existing assertions using a unique identifier. The requester initiates the profile by sending an assertion request, referenced by an identifier, to a SAML v2 authority. The SAML v2 authority processes the request, checks the assertion cache for the identifier, and issues a response to the requester. An assertion mapper is used by he SAML v2 authority to process assertion ID requests. The com.sun.identity.saml2.plugins.AssertionIDRequestMapper class is the default implementation for the com.sun.identity.saml2.plugins.AssertionIDRequestMapper SPI. The SPI is used to validate the assertion request on the server side. The Assertion will be returned to the client only after the validation passed.

To define a customized mapper, change the value of the assertionIDRequestMapper property in the extended metadata of the provider acting as SAML v2 attribute authority or authentication authority. To send a request for an assertion from a provider, use either of the methods of com.sun.identity.saml2.profile.AssertionIDRequestUtil as below.


public static Response sendAssertionIDRequest(
AssertionIDRequest assertionIDRequest,
String samlAuthorityEntityID,
String role,
String realm,
String binding)
throws SAML2Exception;

public static Assertion sendAssertionIDRequestURI(
String assertionID,
String samlAuthorityEntityID,
String role,
String realm)
throws SAML2Exception;

To construct an assertion request object, use com.sun.identity.saml2.assertion.* and com.sun.identity.saml2.protocol.*.

Attribute Authority Mappers

The Assertion Query/Request profile specifies a means for requesting attributes (and the corresponding values) from a specific identity profile. A successful response is the return of an assertion containing the requested information. The identity provider acting as the attribute authority uses the com.sun.identity.saml2.plugins.AttributeAuthorityMapper to process queries. This default implementation uses the attribute map table configured in the identity provider's extended metadata; this table maps the requested SAML v2 attributes to the user profile attributes in the identity data store. (If an attribute map is not configured, no attributes will be returned.)

To set OpenSSO Enterprise to use a customized attribute mapper implementation, modify the values of the default_attributeAuthorityMapper and the x509Subject_attributeAuthorityMapper properties in the extended metadata of the provider defined as the attribute authority. The default_attributeAuthorityMapper value is used for a standard attribute queries and the x509Subject_attributeAuthorityMapper value is used for attribute queries with an X509 subject, mapping the X509 subject to a user by searching the identity data store for a specified attribute. (The specified attribute is defined as the value of the x509SubjectDataStoreAttrName property in the identity provider extended metadata of the attribute authority.) If the user has the specified attribute and the attribute's value is the same as that of the X509 subject in the attribute query, the user will be used.

Only SOAP binding is supported and signing is required so make sure the Signing Certificate Alias attribute of the providers acting as the attribute requester and the attribute authority is configured. To send an attribute query from the requester use the method of com.sun.identity.saml2.profile.AttributeQueryUtil as follows.


public static Response sendAttributeQuery(
AttributeQuery attrQuery,
String attrAuthorityEntityID,
String realm,
String attrQueryProfile,
String attrProfile,
String binding)
throws SAML2Exception;

To construct an attribute query object, use com.sun.identity.saml2.assertion.* and com.sun.identity.saml2.protocol.*.

Service Provider Adapter

A service provider adapter allows the developer to plug-in application specific logic before and/or after single sign-on, single logout, termination and new name identifier process. The SAML2ServiceProviderAdapter abstract class provides methods that could be extended to perform user specific logics during SAML v2 protocol processing on the Service Provider side. The implementation class could be configured on a per service provider basis in the extended metadata configuration.


Note –

A singleton instance of this SAML2ServiceProviderAdapter class will be used per service provider during runtime, so make sure implementation of the methods are thread safe.


JavaServer Pages

JavaServer Pages (JSP) are HTML files that contain additional code to generate dynamic content. More specifically, they contain HTML code to display static text and graphics, as well as application code to generate information. When the page is displayed in a web browser, it will contain both the static HTML content and dynamic content retrieved via the application code. The SAML v2 framework contains JSP that can initiate SAML v2 interactions. After installation, these pages can be accessed using the following URL format:

http(s)://host:port/uri/saml2/jsp/jsp-page-name?metaAlias=xxx&...

The JSP are collected in the /path-to-context-root/uri/saml2/jsp directory. The following sections contain descriptions of, and uses for, the different JSP.


Caution – Caution –

The following JSP used for the Virtual Federation Proxy cannot be modified:


Default Display Page

default.jsp is the default display page for the SAML v2 framework. After a successful SAML v2 operation (single sign-on, single logout, or federation termination), a page is displayed. This page, generally the originally requested resource, is specified in the initiating request using the <RelayState> element. If a <RelayState> element is not specified, the value of the <defaultRelayState> property in the extended metadata configuration is displayed. If a <defaultRelayState> is not specified, this default.jsp is used. default.jsp can take in a message to display, for example, upon a successful authentication. The page can also be modified to add additional functionality.


Caution – Caution –

When the value of <RelayState> or <defaultRelayState> contains special characters (such as &), it must be URL-encoded.


Export Metadata Page

This page is used to export standard entity metadata. The supported query parameters are:

If no query parameter is specified, the page will attempt to export metadata in the following order:

  1. The first hosted service provider under the root realm.

  2. The first hosted identity provider under root realm.

  3. If there is none of the above, an error message will be displayed.

Fedlet Pages

fedletSSOInit.jsp initiates single sign-on at the Fedlet side. (It is not designed to be used by a full service provider.) A list of query parameters for use with this page are defined in the page itself. fedletSampleApp.jsp is the sample page and should not be modified.

fedletSSOInit.jsp initiates single sign-on at the Fedlet side (note:).

Assertion Consumer Page

The spAssertionConsumer.jsp processes the responses that a service provider receives from an identity provider. When a service provider wants to authenticate a user, it sends an authentication request to an identity provider. The AuthnRequest asks that the identity provider return a Response containing one or more assertions. The spAssertionConsumer.jsp receives and parses the Response (or an artifact representing it). The endpoint for this JSP is protocol://host:port/service-deploy-uri/Consumer. Some ways in which the spAssertionConsumer.jsp can be customized include:

Single Sign-on Pages

The single sign-on JSP are used to initiate single sign-on and, parse authentication requests, and generate responses. These include:

idpSSOFederate.jsp

idpSSOFederate.jsp works on the identity provider side to receive and parse authentication requests from the service provider and generate a Response containing an assertion. The endpoint for this JSP is protocol://host:port/service-deploy-uri/idpSSOFederate. idpSSOFederate.jsp takes the following parameters:

idpSSOInit.jsp

idpSSOInit.jsp initiates single sign-on from the identity provider side (also referred to as unsolicited response). For example, a user requests access to a resource. On receiving this request for access, idpSSOInit.jsp looks for a cached assertion which, if present, is sent to the service provider in an unsolicited <Response>. If no assertion is found, idpSSOInit.jsp verifies that the following required parameters are defined:

If defined, the unsolicited Response is created and sent to the service provider. If not, an error is returned. The endpoint for this JSP is protocol://host:port/service-deploy-uri/idpssoinit. The following optional parameters can also be passed to idpSSOInit.jsp:

spSSOInit.jsp

spSSOInit.jsp is used to initiate single sign-on from the service provider side. On receiving a request for access, spSSOInit.jsp verifies that the following required parameters are defined:

If defined, the Request is created and sent to the identity provider. If not, an error is returned. The endpoint for this JSP is protocol://host:port/service-deploy-uri/spssoinit. The following optional parameters can also be passed to spSSOInit.jsp:

To pass parameters to specify RequestedAuthnContext use:

  1. AuthLevel

  2. AuthnContextClassRef

  3. sunamcompositeadvice

Name Identifier Pages

The various ManageNameID (MNI) JSP provide a way to change account identifiers or terminate mappings between identity provider accounts and service provider accounts. For example, after establishing a name identifier for use when referring to a principal, the identity provider may want to change its value and/or format. Additionally, an identity provider might want to indicate that a name identifier will no longer be used to refer to the principal. The identity provider will notify service providers of the change by sending them a ManageNameIDRequest. A service provider also uses this message type to register or change the SPProvidedID value (included when the underlying name identifier is used to communicate with it) or to terminate the use of a name identifier between itself and the identity provider.

idpMNIPOST.jsp

idpMNIPOST.jsp processes the ManageNameIDRequest from an identity provider using HTTP Redirect binding. There are no required parameters.

idpMNIRequestInit.jsp

idpMNIRequestInit.jsp initiates the ManageNameIDRequest at the identity provider by user request. The endpoint for this JSP is protocol://host:port/service-deploy-uri/IDPMniInit. It takes the following required parameters:

Some of the other optional parameters are :

idpMNIRedirect.jsp

idpMNIRedirect.jsp processes the ManageNameIDRequest and the ManageNameIDResponse received from the service provider using HTTP-Redirect. The endpoint for this JSP is protocol://host:port/service-deploy-uri/IDPMniRedirect. It takes the following required parameters:

Optionally, it can also take the RelayState parameter which specifies the target URL of the request.

spMNIPOST.jsp

spMNIPOST.jsp processes the ManageNameIDRequest from a service provider using HTTP Redirect binding. There are no required parameters.

spMNIRequestInit.jsp

spMNIRequestInit.jsp initiates the ManageNameIDRequest at the service provider by user request. The endpoint for this JSP is protocol://host:port/service-deploy-uri/SPMniInit. It takes the following required parameters:

Some of the other optional parameters are :

spMNIRedirect.jsp

spMNIRedirect.jsp processes the ManageNameIDRequest and the <ManageNameIDResponse> received from the identity provider using HTTP-Redirect. The endpoint for this JSP is protocol://host:port/service-deploy-uri/SPMniRedirect. It takes the following required parameters:

Optionally, it can also take the RelayState parameter which specifies the target URL of the request.

Single Logout Pages

The single logout JSP provides the means by which all sessions authenticated by a particular identity provider are near-simultaneously terminated. The single logout protocol is used either when a user logs out from a participant service provider or when the principal logs out directly from the identity provider.

idpSingleLogoutPOST.jsp

idpSingleLogoutPOST.jsp can do either of the following:

There are no required parameters.

idpSingleLogoutInit.jsp

idpSingleLogoutInit.jsp initiates a LogoutRequest at the identity provider by user request. The endpoint for this JSP is protocol://host:port/service-deploy-uri/IDPSloInit. There are no required parameters. Optional parameters include:

idpSingleLogoutRedirect.jsp

idpSingleLogoutRedirect.jsp processes the LogoutRequest and the LogoutResponse received from the service provider using HTTP-Redirect. The endpoint for this JSP is protocol://host:port/service-deploy-uri/IDPSloRedirect. It takes the following required parameters:

Optionally, it can also take the RelayState parameter which specifies the target URL of the request.

spSingleLogoutPOST.jsp

spSingleLogoutPOST.jsp can do either of the following:

Required parameters for the first option are RelayState (the target URL for a successful single logout) and SAMLRequest (the Logout Request). For the second option it is SAMLResponse (the Logout Response).

spSingleLogoutInit.jsp

spSingleLogoutInit.jsp initiates a LogoutRequest at the identity provider by user request. The endpoint for this JSP is protocol://host:port/service-deploy-uri/SPSloInit. There are no required parameters. Optional parameters include:

spSingleLogoutRedirect.jsp

spSingleLogoutRedirect.jsp processes the LogoutRequest and the LogoutResponse received from the identity provider using HTTP-Redirect. The endpoint for this JSP is protocol://host:port/service-deploy-uri/SPSloRedirect. It takes the following required parameters:

Optionally, it can also take the RelayState parameter which specifies the target URL of the request.

SAML v2 Samples

The following SAML v2 samples can be used for testing purposes.