test

Sun OpenSSO Enterprise 8.0 Developer's Guide

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.