Chapter 8 Constructing SAML Messages

Sun OpenSSO Enterprise has implemented two versions of the Security Assertion Markup Language (SAML) in OpenSSO Enterprise. This chapter contains information on these implementations.

• SAML v2

• Using SAML v2 for Virtual Federation Proxy

• SAML v1.x

SAML v2

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

• Using the SAML v2 SDK

• Service Provider Interfaces

• JavaServer Pages

• SAML v2 Samples

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

• For information on the packages in the SDK, see Exploring the SAML v2 Packages.

• For ways to set a customized implementation, see Setting a Customized Class.

Exploring the SAML v2 Packages

The SAML v2 SDK includes the following packages:

• com.sun.identity.saml2.assertion Package

• com.sun.identity.saml2.common Package

• com.sun.identity.saml2.plugins Package

• com.sun.identity.saml2.protocol Package

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:

• Account Mappers

• Attribute Mappers

• Authentication Context Mappers

• Assertion Query/Request Mappers

• Attribute Authority Mappers

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.

• IDPAccountMapper

• SPAccountMapper

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:

• IDPAttributeMapper

• SPAttributeMapper

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.

*=* 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:

• IDPAuthnContextMapper

• SPAuthnContextMapper

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:

• The idpAuthncontextMapper property specifies the mapper implementation.

• The idpAuthncontextClassrefMapping property specifies the mapping between a standard SAMLv2 authentication context class reference and an OpenSSO Enterprise authentication scheme. It takes a value in the following format:

  authnContextClassRef | authlevel | authnType=authnValue | authnType=authnValue | ... [|default]

  For example, urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|3|module=LDAP|default maps the SAMLv2 PasswordProtectedTransport class reference to the OpenSSO Enterprise LDAP authentication module.

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:

• AuthnContextClassRef or AuthnContextDeclRef: These properties specify one or more URI references identifying the provider's supported authentication context classes. If a value is not specified, the default is urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.

• AuthLevel: This parameter specifies the authentication level of the authentication context being used for authentication.

• AuthComparison: This parameter specifies the method of comparison used to evaluate the requested context classes or statements. Accepted values include:

  • exact where the authentication context statement in the assertion must be the exact match of, at least, one of the authentication contexts specified.

  • minimum where the authentication context statement in the assertion must be, at least, as strong (as deemed by the identity provider) one of the authentication contexts specified.

  • maximum where the authentication context statement in the assertion must be no stronger than any of the authentication contexts specified.

  • better where the authentication context statement in the assertion must be stronger than any of the authentication contexts specified.

  If the element is not specified, the default value is exact.

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:

• The spAuthncontextMapper property specifies the name of the service provider mapper implementation.

• The spAuthncontextClassrefMapping property specifies the map of authentication context class reference and authentication level in the following format:

  authnContextClassRef | authlevel [| default]

• The spAuthncontextComparisonType property is optional and specifies the method of comparison used to evaluate the requested context classes or statements. Accepted values include:

  • exact where the authentication context statement in the assertion must be the exact match of, at least, one of the authentication contexts specified.

  • minimum where the authentication context statement in the assertion must be, at least, as strong (as deemed by the identity provider) one of the authentication contexts specified.

  • maximum where the authentication context statement in the assertion must be no stronger than any of the authentication contexts specified.

  • better where the authentication context statement in the assertion must be stronger than any of the authentication contexts specified.

  If the element is not specified, the default value is exact.

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.

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.

• Default Display Page

• Export Metadata Page

• Fedlet Pages

• Assertion Consumer Page

• Single Sign-on Pages

• Name Identifier Pages

• Single Logout Pages

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

• SA_IDP.jsp

• SA_SP.jsp

• saeerror.jsp

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.

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:

• The role of the entity defined as sp, idp or any.

• The realm to which the entity belongs.

• The identifier of the entity to be exported.

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:

• The localLoginUrl parameter in the spAssertionConsumer.jsp retrieves the value of the localAuthUrl property in the service provider's extended metadata configuration. The value of localAuthUrl points to the local login page on the service provider side. If localAuthUrl is not defined, the login URL is calculated using the Assertion Consumer Service URL defined in the service provider's standard metadata configuration. Changing the localLoginUrl parameter value in spAssertionConsumer.jsp is another way to define the service provider's local login URL.

• After a successful single sign-on and before the final protected resource (defined in the <RelayState> element) is accessed, the user may be directed to an intermediate URL, if one is configured as the value of the intermediateUrl property in the service provider's extended metadata configuration file. For example, this intermediate URL might be a successful account creation page after the auto-creation of a user account. The redirectUrl in spAssertionConsumer.jsp can be modified to override the intermediateUrl value.

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

• idpSSOInit.jsp

• spSSOInit.jsp

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:

• SAMLRequest: This required parameter takes as a value the XML blob that contains the AuthnRequest.

• metaAlias: This optional parameter takes as a value the metaAlias set in the identity provider's extended metadata configuration file.

• RelayState: This optional parameter takes as a value the target URL of the request.

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:

• metaAlias: This parameter takes as a value the metaAlias set in the identity provider's extended metadata configuration file. If the metaAlias attribute is not present, an error is returned.

• spEntityID: The entity identifier of the service provider to which the response is sent.

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:

• RelayState: The target URL of the request.

• NameIDFormat: The currently supported name identifier formats: persistent or transient.

• binding: A URI suffix identifying the protocol binding to use when sending the Response. The supported values are:

  • HTTP-Artifact

  • HTTP-POST

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:

• metaAlias: This parameter takes as a value the metaAlias set in the identity provider's extended metadata configuration file. If the metaAlias attribute is not present, an error is returned.

• idpEntityID: The entity identifier of the identity provider to which the request is sent. If idpEntityID is not provided, the request is redirected to the SAML v2 IDP Discovery Service to get the user's preferred identity provider. In the event that more then one identity provider is returned, the last one in the list is chosen. If idpEntityID cannot be retrieved using either of these methods, an error is returned.

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:

• RelayState: The target URL of the request.

• NameIDFormat: The currently supported name identifier formats: persistent or transient.

• binding: A URI suffix identifying the protocol binding to use when sending the Response. The supported values are:

  • HTTP-Artifact

  • HTTP-POST

• AssertionConsumerServiceIndex: An integer identifying the location to which the Response message should be returned to the requester. requester. It applies to profiles in which the requester is different from the presenter, such as the Web Browser SSO profile.

• AttributeConsumingServiceIndex: An integer indirectly specifying information (associated with the requester) describing the SAML attributes the requester desires or requires to be supplied.

• isPassive: Takes a value of true or false with true indicating the identity provider should authenticate passively.

• ForceAuthN: Takes a value of true indicating that the identity provider must force authentication or false indicating that the identity provider can reuse existing security contexts.

• AllowCreate: Takes a value of true indicating that the identity provider is allowed to created a new identifier for the principal if it does not exist or false.

• Destination: A URI indicating the address to which the request has been sent.

• AuthnContextClassRef: Specifies a URI reference identifying an authentication context class that describes the declaration that follows. Multiple references can be pipe-separated.

• AuthnContextDeclRef: Specifies a URI reference to an authentication context declaration. Multiple references can be pipe-separated.

• AuthComparison: The comparison method used to evaluate the requested context classes or statements. Accepted values include: minimum, maximum or better.

• Consent: Indicates whether or not (and under what conditions) consent has been obtained from a principal in the sending of this request.

  ---

  Note –

  Consent is not supported in this release.

  ---

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

• idpMNIRequestInit.jsp

• idpMNIRedirect.jsp

• spMNIPOST.jsp

• spMNIRequestInit.jsp

• spMNIRedirect.jsp

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:

• metaAlias: The value of the metaAlias property set in the identity provider's extended metadata configuration file. If the metaAlias attribute is not present, an error is returned.

• spEntityID: The entity identifier of the service provider to which the response is sent.

• requestType: The type of ManageNameIDRequest. Accepted values include Terminate and NewID.

Some of the other optional parameters are :

• binding: A URI specifying the protocol binding to use for the <Request>. The supported values are:

  • urn:oasis:names:tc:SAML:2.0:bindings:SOAP

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

• RelayState: The target URL of the request

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:

• SAMLRequest: The ManageNameIDRequest from the service provider.

• SAMLResponse: The ManageNameIDResponse from the service provider.

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:

• metaAlias: This parameter takes as a value the metaAlias set in the identity provider's extended metadata configuration file. If the metaAlias attribute is not present, an error is returned.

• idpEntityID: The entity identifier of the identity provider to which the request is sent.

• requestType: The type of ManageNameIDRequest. Accepted values include Terminate and NewID.

Some of the other optional parameters are :

• binding: A URI specifying the protocol binding to use for the Request. The supported values are:

  • urn:oasis:names:tc:SAML:2.0:bindings:SOAP

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

• RelayState: The target URL of the request.

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:

• SAMLRequest: The ManageNameIDRequest from the identity provider.

• SAMLResponse: The ManageNameIDResponse from the identity provider.

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

• idpSingleLogoutInit.jsp

• idpSingleLogoutRedirect.jsp

• spSingleLogoutPOST.jsp

• spSingleLogoutInit.jsp

• spSingleLogoutRedirect.jsp

idpSingleLogoutPOST.jsp

idpSingleLogoutPOST.jsp can do either of the following:

• Receives a Logout Request from an identity provider and sends a Logout Response to a service provider.

• Receives a Logout Response from the service provider.

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:

• RelayState: The target URL after single logout.

• binding: A URI specifying the protocol binding to use for the <Request>. The supported values are:

  • urn:oasis:names:tc:SAML:2.0:bindings:SOAP

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

• Destination: A URI indicating the address to which the request has been sent.

• Consent: Indicates whether or not (and under what conditions) consent has been obtained from a principal in the sending of this request.

  ---

  Note –

  Consent is not supported in this release.

  ---

• Extension: Specifies permitted extensions as a list of string objects.

  ---

  Note –

  Extension is not supported in this release.

  ---

• logoutAll: Specifies that the identity provider send log out requests to all service providers without a session index. It will logout all sessions belonging to the user.

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:

• SAMLRequest: The LogoutRequest from the service provider.

• SAMLResponse: The LogoutResponse from the service provider.

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:

• Receives a Logout Request from a service provider and sends a Logout Response to an identity provider.

• Receives a Logout Response from the identity provider.

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:

• RelayState: The target URL after single logout.

• binding: A URI specifying the protocol binding to use for the <Request>. The supported values are:

  • urn:oasis:names:tc:SAML:2.0:bindings:SOAP

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

• Destination: A URI indicating the address to which the request has been sent.

• Consent: Indicates whether or not (and under what conditions) consent has been obtained from a principal in the sending of this request.

  ---

  Note –

  Consent is not supported in this release.

  ---

• Extension: Specifies permitted extensions as a list of string objects.

  ---

  Note –

  Extension is not supported in this release.

  ---

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:

• SAMLRequest: The LogoutRequest from the identity provider.

• SAMLResponse: The LogoutResponse from the identity provider.

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.

• useCasedemo is a sample that illustrates the following SAML v2 use cases.

  • IDP initiated Single Sign On

  • SP initiated Single Sign On

  • IDP initiated Single Log out

  • SP initiated Single Log out

  • IDP initiated Federation

  • SP initiated Federation

  • IDP initiated Federation Termination

  • SP initiated Federation Termination

• sae is a sample that illustrates the general use cases of the Virtual Federation Proxy (also referred to as Secure Attribute Exchange). See Using SAML v2 for Virtual Federation Proxy for more information.

Using SAML v2 for 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, Virtual Federation Proxy (VFP) provides a secure gateway that enables legacy applications to communicate user attributes used for authentication without having to deal specifically with federation protocols and processing. A VFP interaction allows:

• Identity provider applications to push user authentication, profile and transaction information to a local instance of OpenSSO Enterprise. OpenSSO Enterprise 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.

The scope of the implementation of VFP is currently limited to SAML v2 based single sign-on. It uses the SAMLv2-based protocols (based on the HTTP GET and POST methods as well as URL redirects) to transfer identity data between the communicating entities. The client API (which includes Java and .NET interfaces) run independently of OpenSSO Enterprise and are used to enable existing applications, allowing them to handle SAML v2 interactions.

VFP functionality can be found in three places:

• deployable-war/opensso.war on the OpenSSO Enterprise side.

• libraries/dll/openssosae.dll for client applications using the OpenSSO Enterprise NET API.

• libraries/jars/openssoclientsdk.jar for client applications using the OpenSSO Enterprise Java API.

The following sections contain more information on Virtual Federation Proxy.

• How Virtual Federation Proxy Works

• Use Cases

• Securing Virtual Federation Proxy

• Preparing to Use Virtual Federation Proxy

• Configuring for Virtual Federation Proxy

• Using the Secure Attribute Exchange Sample

How Virtual Federation Proxy Works

The components of a secure attribute exchange are listed and illustrated below.

• Legacy identity provider application (blue IDP)

• Service provider application (blue SP)

• Independent instances of OpenSSO on both the identity provider and the service provider sides (green)

• A user agent

Figure 8–1 A Secure Attribute Exchange Using SAML v2

The following graphic illustrates the process behind a secure attribute exchange interaction. Details are below the illustration.

1. A user authenticates.

   This may be done by the identity provider application or it may be delegated to an authentication authority.

2. The authenticated user uses the identity provider application and, at some point, accesses a link representing a service provided by an application in a different domain.

3. The identity provider application assembles the appropriate user attributes (authentication and user profile data), encodes and signs it using the API, and posts the secure data to the local instance of OpenSSO Enterprise.

   The com.sun.identity.sae.api.SecureAttrs class is provided by OpenSSO Enterprise and carries the user identifier and the service provider destination.

4. The SAE authentication module on the instance of OpenSSO Enterprise local to the identity provider verifies the authenticity of the attributes also using the SAE API, and initiates the appropriate SAML v2 single sign-on protocol to send the attributes to the instance of OpenSSO Enterprise local to the service provider being accessed.

5. The instance of OpenSSO Enterprise local to the service provider secures the user attributes, and sends them to the service provider application.

   The service provider application uses interfaces supplied by OpenSSO Enterprise to verify the authenticity of the attributes.

6. The service provider application provides or denies the service to the user based on the attributes received.

It is not mandatory for the service provider end of the process to implement VFP. Since the attributes are carried in a SAML v2 assertion, the service provider could choose another way to invoke the requested application. For example, the service provider can use standard SAML v2 protocols to invoke a SAML v2-compliant service provider that does not implement SAE. The RelayState element as defined in the SAML v2 specification can be used to redirect to the local service provider application.

Use Cases

The following sections contain information on applicable use cases for SAE.

• Authentication at Identity Provider

• Secure Attribute Exchange at Identity Provider

• Secure Attribute Exchange at Service Provider

• Global Single Logout

Authentication at Identity Provider

When a user is already authenticated in 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 VFP to transfer the user's authentication information to the local instance of OpenSSO Enterprise in order to create a session.

Secure Attribute Exchange 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.

Secure Attribute Exchange 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 single sign-on URL as a part of the request. The identity provider instance of OpenSSO Enterprise then initiates SAML v2 single sign-on 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, single sign-on 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 executes SAML v2 single log out by invoking a provided OpenSSO Enterprise URL. The identity provider terminates the session on both provider instances of OpenSSO Enterprise.

An identity provider side application can initiate single logout by sending sun.cmd=logout attributes via an SAE 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.

Securing Virtual Federation Proxy

VFP provides two ways to secure identity attributes between an instance of OpenSSO Enterprise and an application:

• Symmetric involves the use of a shared secret key known only to the participants in the communication. The key is agreed upon beforehand and will be used to encrypt and decrypt the message.

• Asymmetric uses two separate keys for encryption and the corresponding decryption - one public and one private. The information is encrypted with a public key known to all and decrypted, by the recipient only, using a private key to which no one else has access. This process is known as a public key infrastructure. On the identity provider side, the public key must be added to the OpenSSO Enterprise keystore. The private key must be stored in a protected keystore (such as a Hardware Security Module) for access by the identity provider application. On the service provider side, the private key must be added to the OpenSSO Enterprise keystore, and the public key stored in a keystore, local to the service provider application.

Both mechanisms result in an encrypted string (referred to as a cryptostring) generated for the asserted attributes. The symmetric cryptostring is a SHA-1 hash of the attributes. The asymmetric cryptostring is a digital signature of the attributes.

As each pairing of application to OpenSSO Enterprise instance is independent, different applications involved can use different security methods.

Preparing to Use Virtual Federation Proxy

Before configuring and using the VFP, you will need to make some decisions regarding security, applicable keys, and applications. This section lists what you will need to do before configuring for VFP.

Because OpenSSO Enterprise currently uses SAML v2 for its implementation of SAE, you should familiarize yourself with SAML v2 concepts by running the useCaseDemo SAML v2 sample included with OpenSSO Enterprise.

1. Establish trust between the application(s) and the instance of OpenSSO Enterprise on the identity provider side.

   Decide the application(s) on the identity provider side that will use SAE to push identity attributes to the local instance of OpenSSO Enterprise. You will need values for the following:

   Application Name

   This is used for easy identification and can be any string. Use of the application's URL is recommended.

   CryptoType

   Can be Symmetric or Asymmetric.

   Shared Secret or Private and Public Keys

   You need the shared secret if using Symmetric, and the private and public keys if using Asymmetric.

   ---

   Tip –

   Multiple applications can share the same application name only if they also share the same shared secret or key.

   ---

2. Establish trust between the application(s) and the instance of OpenSSO Enterprise on the service provider side.

   Decide the applications on the service provider side that will receive the identity attributes from the local instance of OpenSSO Enterprise using SAE. You will need the following:

   Application Name

   This is used for easy identification and can be any string. Use of the application's URL is recommended because the default implementation of the SAE on the service provider side uses a prefix string match from the requested application URL to determine the parameters used to secure the communication.

   CryptoType

   Can be Symmetric or Asymmetric.

   Shared Secret or Private and Public Keys

   You need the shared secret if using Symmetric, and the private and public keys if using Asymmetric. If Asymmetric is chosen, use the same keys defined when the SAML v2 service provider was configured as an OpenSSO Enterprise service provider. You can find these keys in the service provider's metadata.

   ---

   Tip –

   Multiple applications can share the same application name only if they also share the same shared secret or key.

   ---

3. OPTIONAL: The following steps are specific to using SAML v2 and auto-federation.

   1. Decide which identity attributes you want transferred as part of the SAML v2 single sign-on interaction.

      We choose the branch and mail attributes.

      ---

      Caution –

      If any attribute needs to be supplied from a local user data store, you must first populate the data store.

      ---

   2. Decide which attribute will be used to identify the user on the service provider side.

      In this instance, we choose the branch attribute for user identification.

      ---

      Note –

      The attribute may be one transferred in the SAML v2 assertion or it can be configured statically at the service provider.

      ---

4. Decide which URL on the service provider side will be responsible for handling logout requests from the identity provider.

   The URL will be responsible for terminating the local session state. Only one is allowed per logical service provider configured on the service provider side.

Configuring for Virtual Federation Proxy

Configuring for VFP communication involves modifications on two different installations of OpenSSO Enterprise: one that is local to the identity provider and one that is local to the service provider. The following sections assume that you have downloaded the OpenSSO Enterprise bits and deployed the application to a supported web container. You should also be ready to configure a SAML v2 provider by executing the included SAML v2 sample, by running one of the Common Tasks using the Administration Console, or by importing provider metadata using the Administration Console or ssoadm command line interface. The following procedures contain more information.

• Configure the Instance of OpenSSO Enterprise Local to the Identity Provider

• Configure the Instance of OpenSSO Enterprise Local to the Service Provider

• Configure the Instance of OpenSSO Enterprise Local to the Identity Provider for the Remote Service Provider

• Configure the Instance of OpenSSO Enterprise Local to the Service Provider for the Remote Identity Provider

Configure the Instance of OpenSSO Enterprise Local to the Identity Provider

The following procedure illustrates how to configure the instance of OpenSSO Enterprise local to the identity provider.

1. Update the identity provider standard metadata.

   • If you have existing identity provider standard metadata, export it using ssoadm and make your modifications. After updating, delete the original file and reload the modified metadata using ssoadm.

   • If you have not yet configured identity provider standard metadata, use ssoadm to generate an identity provider metadata template. After updating the template, import the modified metadata also using ssoadm.

2. Set up the keystore.

   If using the asymmetric cryptotype, add the public and private keys to the application's keystore. Additionally, populate the identity provider's keystore with the application's public key.

3. Update the identity provider configuration.

   1. Setup the application's security configuration as symmetric or asymmetric by defining the Per Application Security Configuration attribute under the Advanced tab of the identity provider configuration.

      ---

      Note –

      Use ampassword to encrypt the shared secret used for a symmetric configuration.

      ---

   2. OPTIONAL: Modify the IDP URL attribute (if you want to use an alternative or custom SAE landing URL) under the local identity provider's Advanced tab with a value specific to your identity provider instance of OpenSSO Enterprise.

Configure the Instance of OpenSSO Enterprise Local to the Service Provider

The following procedure shows how to configure the instance of OpenSSO Enterprise local to the service provider.

1. Update the service provider standard metadata.

   • If you have existing service provider standard metadata, export it using ssoadm and make your modifications. After updating, delete the original file and reload the modified metadata also using ssoadm.

   • If you have not yet configured service provider standard metadata, use ssoadm to generate a service provider metadata template. After updating the template, import the modified metadata also using ssoadm.

2. Set up the keystore.

   If using the asymmetric cryptotype, add the public and private keys to the application's keystore. Additionally, populate the identity provider's keystore with the application's public key.

3. Update the service provider extended metadata.

   1. Enable auto-federation and specify the attribute that will identify the user's identity under the Assertion Processing tab of the service provider configuration.

   2. Specify attributes from the incoming SAML v2 assertion to be used to populate the local OpenSSO Enterprise session under the Assertion Processing tab of the service provider configuration.

   3. Setup the application's security configuration as symmetric or asymmetric by defining the Per Application Security Configuration attribute under the Advanced tab of the service provider configuration.

      ---

      Note –

      Use ampassword to encrypt the shared secret used for a symmetric configuration.

      ---

   4. OPTIONAL: Modify the SP URL attribute ( if you want to use an alternative or custom SAE landing URL) under the local service provider's Advanced tab with a value specific to your identity provider instance of OpenSSO Enterprise.

   5. Configure the value of the SP Logout URL attribute. The value of this attribute is the URL that will receive global logout requests

      ---

      Note –

      The configured URL must have a defined symmetric or asymmetric CryptoType with corresponding shared secret and certificates established.

      ---

Configure the Instance of OpenSSO Enterprise Local to the Identity Provider for the Remote Service Provider

Both the standard and extended metadata retrieved from the remote service provider will be imported to the instance of OpenSSO Enterprise local to the identity provider.

1. Get both the remote service provider standard metadata and the remote service provider extended metadata used in Configure the Instance of OpenSSO Local to the Service Provider.

2. Modify the remote service provider extended metadata as follows:

   • Remove all shared secrets defined in the actual provider metadata file.

   • Set the hosted attribute to 0 (false) as in <EntityConfig .. hosted="0" ....>. This defines the entity as remote and can only be done using the actual provider metadata file.

   • Remove the value for the SP Logout URL attribute under the Advanced tab of the service provider configuration.

   • Add the following attribute and values to the Attribute Map attribute under the Assertion Processing tab.

     mail=mail
     branch=branch

3. Import both metadata files to the instance of OpenSSO Enterprise local to the identity provider.

   Use ssoadm the command line interface.

Configure the Instance of OpenSSO Enterprise Local to the Service Provider for the Remote Identity Provider

If the SAMLv2 sample has been executed on the instance of OpenSSO Enterprise local to the service provider, nothing else needs to be done. If metadata has been manually configured on the instance of OpenSSO Enterprise local to the service provider, do the following procedure.

1. Get the remote identity provider metadata for import to the instance of OpenSSO Enterprise local to the service provider.

   The standard metadata is the same as the one used in Configure the Instance of OpenSSO Enterprise Local to the Identity Provider.

2. Import the standard metadata to the instance of OpenSSO Enterprise local to the service provider using ssoadm.

3. Add the identity provider to the service provider's configured circle of trust.

   ---

   Note –

   If using a flat file for a datastore, both the instance of OpenSSO Enterprise at the service provider and the instance at the identity provider must be restarted.

   ---

Using the Secure Attribute Exchange Sample

OpenSSO Enterprise includes a sample that can be run for testing your configurations. It is located in container_context_root/opensso/samples/saml2/sae. In the sample, auto-federation and transient name identifier, two features of SAML v2, are used. If there are no actual users on either the identity provider side or the service provider side, you need to use the following procedure to change the authentication framework to ignore user profiles for these two features to work correctly.

1. Login to OpenSSO Enterprise administration console as administrator.

   By default, this is amadmin.

2. Click the name of the realm you are modifying.

3. Click the Authentication tab.

4. Click Advanced Properties.

5. Select the Ignore Profile radio button under User Profile.

6. Click Save.

7. Log out of the console.

SAML v1.x

OpenSSO Enterprise contains SAML v1.x API collected in several Java packages. Administrators can use these packages to integrate the SAML v1.x functionality using XML messages into their applications and services. The API support all types of assertions and operate with OpenSSO Enterprise authorities to process external SAML v1.x requests and generate SAML v1.x responses. The packages include the following:

• com.sun.identity.saml Package

• com.sun.identity.saml.assertion Package

• com.sun.identity.saml.common Package

• com.sun.identity.saml.plugins Package

• com.sun.identity.saml.protocol Package

For more detailed information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

com.sun.identity.saml Package

This package contains the following classes.

• AssertionManager Class

• SAMLClient Class

AssertionManager Class

The AssertionManager class provides interfaces and methods to create and get assertions, authentication assertions, and assertion artifacts. This class is the connection between the SAML specification and OpenSSO Enterprise. Some of the methods include the following:

• createAssertion creates an assertion with an authentication statement based on an OpenSSO Enterprise SSO Token ID.

• createAssertionArtifact creates an artifact that references an assertion based on an OpenSSO Enterprise SSO Token ID.

• getAssertion returns an assertion based on the given parameter (given artifact, assertion ID, or query).

SAMLClient Class

The SAMLClient class provides methods to execute either the Web Browser Artifact Profile or the Web Browser POST Profile from within an application as opposed to a web browser. Its methods include the following:

• getAssertionByArtifact returns an assertion for a corresponding artifact.

• doWebPOST executes the Web Browser POST Profile.

• doWebArtifact executes the Web Browser Artifact Profile.

com.sun.identity.saml.assertion Package

This package contains the classes needed to create, manage, and integrate an XML assertion into an application. The following code example illustrates how to use the Attribute class and getAttributeValue method to retrieve the value of an attribute. From an assertion, call the getStatement() method to retrieve a set of statements. If a statement is an attribute statement, call the getAttribute() method to get a list of attributes. From there, call getAttributeValue() to retrieve the attribute value.

Example 8–1 Sample Code to Obtain an Attribute Value

// get statement in the assertion
Set set = assertion.getStatement();
//assume there is one AttributeStatement
//should check null& instanceof
AttributeStatement statement = (AttributeStatement) set.iterator().next();
List attributes = statement.getAttribute();
// assume there is at least one Attribute
Attribute attribute = (Attribute) attributes.get(0);
List values = attribute.getAttributeValue();

com.sun.identity.saml.common Package

This package defines classes common to all SAML elements, including site ID, issuer name, and server host. The package also contains all SAML-related exceptions.

com.sun.identity.saml.plugins Package

The SAML v1.x framework provides service provider interfaces (SPIs), three of which have default implementations. The default implementations of these SPIs can be altered, or brand new ones written, based on the specifications of a particular customized service. The implementations are then used to integrate SAML into the custom service. Currently, the package includes the following.

• ActionMapper Interface

• AttributeMapper Interface

• NameIdentifierMapper Interface

• PartnerAccountMapper Interface

• PartnerSiteAttributeMapper Interface

ActionMapper Interface

ActionMapper is an interface used to obtain single sign-on information and to map partner actions to OpenSSO Enterprise authorization decisions. A default action mapper is provided if no other implementation is defined.

AttributeMapper Interface

AttributeMapper is an interface used in conjunction with an AttributeQuery class. When a site receives an attribute query, this mapper obtains the SSOToken or an assertion (containing an authentication statement) from the query. The retrieved information is used to convert the attributes in the query to the corresponding OpenSSO Enterprise attributes. A default attribute mapper is provided if no other implementation is defined.

NameIdentifierMapper Interface

NameIdentifierMapper is an interface that can be implemented by a site to map a user account to a name identifier in the subject of a SAML assertion. The implementation class is specified when configuring the site's Trusted Partners.

PartnerAccountMapper Interface

The AccountMapper interface has been deprecated. Use the PartnerAccountMapper interface.

The PartnerAccountMapper interface needs to be implemented by each partner site. The implemented class maps the partner site's user accounts to user accounts configured in OpenSSO Enterprise for purposes of single sign-on. For example, if single sign-on is configured from site A to site B, a site-specific account mapper can be developed and defined in the Trusted Partners sub-attribute of site B's Trusted Partners profile. When site B processes the assertion received, it locates the corresponding account mapper by retrieving the source ID of the originating site. The PartnerAccountMapper takes the whole assertion as a parameter, enabling the partner to define user account mapping based on attributes inside the assertion. The default implementation is com.sun.identity.saml.plugin.DefaultAccountMapper. If a site-specific account mapper is not configured, this default mapper is used.

Turning on the Debug Service in the OpenSSO Enterprise configuration data store logs additional information about the account mapper, for example, the user name and organization to which the mapper has been mapped.

PartnerSiteAttributeMapper Interface

The SiteAttributeMapper interface has been deprecated. Use the PartnerSiteAttributeMapper interface.

The PartnerSiteAttributeMapper interface needs to be implemented by each partner site. The implemented class defines a list of attributes to be returned as elements of the AttributeStatements in an authentication assertion. By default, when OpenSSO Enterprise creates an assertion and no mapper is specified, the authentication assertion only contains authentication statements. If a partner site wants to include attribute statements, it needs to implement this mapper which would be used to obtain attributes, create the attribute statement, and insert the statement inside the assertion. To set up a PartnerSiteAttributeMapper do the following:

1. Implement a customized class based on the PartnerSiteAttributeMapper interface.

   This class will include user attributes in the SAML authentication assertion.

2. Log in to the OpenSSO Enterprise console to configure the class in the Site Attribute Mapper attribute of the Trusted Partner configuration.

com.sun.identity.saml.protocol Package

This package contains classes that parse the request and response XML messages used to exchange assertions and their authentication, attribute, or authorization information.

• AuthenticationQuery Class

• AttributeQuery Class

• AuthorizationDecisionQuery Class

AuthenticationQuery Class

The AuthenticationQuery class represents a query for an authentication assertion. When an identity attempts to access a trusted partner web site, a SAML 1.x request with an AuthenticationQuery inside is directed to the authority site.

The Subject of the AuthenticationQuery must contain a SubjectConfirmation element. In this element, ConfirmationMethod needs to be set to urn:com:sun:identity, and SubjectConfirmationData needs to be set to the SSOToken ID of the Subject. If the Subject contains a NameIdentifier, the value of the NameIdentifier should be the same as the one in the SSOToken.

AttributeQuery Class

The AttributeQuery class represents a query for an identity’s attributes. When an identity attempts to access a trusted partner web site, a SAML 1.x request with an AttributeQuery is directed to the authority site.

You can develop an attribute mapper to obtain an SSOToken, or an assertion that contains an AuthenticationStatement from the query. If no attribute mapper for the querying site is defined, the DefaultAttributeMapper will be used. To use the DefaultAttributeMapper, the query should have either the SSOToken or an assertion that contains an AuthenticationStatement in the SubjectConfirmationData element. If an SSOToken is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If an assertion is used, the assertion should be issued by the OpenSSO Enterprise instance processing the query or a server that is trusted by the OpenSSO Enterprise instance processing the query.

In the DefaultAttributeMapper, a subject’s attributes can be queried using another subject’s SSOToken if the SSOToken has the privilege to retrieve the attributes.

For a query using the DefaultAttributeMapper, any matching attributes found will be returned. If no AttributeDesignator is specified in the AttributeQuery, all attributes from the services defined under the userServiceNameList in amSAML.properties will be returned. The value of the userServiceNameList property is user service names separated by a comma.

AuthorizationDecisionQuery Class

The AuthorizationDecisionQuery class represents a query about a principal’s authority to access protected resources. When an identity attempts to access a trusted partner web site, a SAML request with an AuthorizationDecisionQuery is directed to the authority site.

You can develop an ActionMapper to obtain the SSOToken ID and retrieve the authentication decisions for the actions defined in the query. If no ActionMapper for the querying site is defined, the DefaultActionMapper will be used. To use the DefaultActionMapper, the query should have the SSOToken ID in the SubjectConfirmationData element of the Subject. If the SSOToken ID is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If a NameIdentifier is present, the information in the SSOToken must be the same as the information in the NameIdentifier.

When using web agents, the DefaultActionMapper handles actions in the namespace urn:oasis:names:tc:SAML:1.0:ghpp only. Web agents serve the policy decisions for this action namespace.

The authentication information can also be passed through the Evidence element in the query. Evidence can contain an AssertionIDReference, an assertion containing an AuthenticationStatement issued by the OpenSSO Enterprise instance processing the query, or an assertion issued by a server that is trusted by the OpenSSO Enterprise instance processing the query. The Subject in the AuthenticationStatement of the Evidence element should be the same as the one in the query.

Policy conditions can be passed through AttributeStatements of assertion(s) inside the Evidence of a query. If the value of an attribute contains a TEXT node only, the condition is set as attributeName=attributeValueString. Otherwise, the condition is set as attributename=attributeValueElement.

The following example illustrates one of many ways to form an authorization decision query that will return a decision.

Example 8–2 AuthorizationDecisionQuery Code Sample

        // testing getAssertion(authZQuery): no SC, with ni, with
        // evidence(AssertionIDRef, authN, for this ni):
            String nameQualifier = "dc=iplanet,dc=com";
            String pName = "uid=amadmin,ou=people,dc=iplanet,dc=com";
            NameIdentifier ni = new NameIdentifier(pName, nameQualifier);
            Subject subject = new Subject(ni);
            String actionNamespace = "urn:test";
            // policy should be added to this resource with these
            // actions for the subject
            Action action1 = new Action(actionNamespace, "GET");
            Action action2 = new Action(actionNamespace, "POST");
            List actions = new ArrayList();
            actions.add(action1);
            actions.add(action2);
            String resource = "http://www.sun.com:80";
            eviSet = new HashSet();
            // this assertion should contain authentication assertion for
            // this subject and should be created by a trusted server
            eviSet.add(eviAssertionIDRef3);
            evidence = new Evidence(eviSet);
            authzQuery = new AuthorizationDecisionQuery(eviSubject1, actions,
                                evidence, resource);
            try {
                assertion = am.getAssertion(authzQuery, destID);
            } catch (SAMLException e) {
                out.println("--failed. Exception:" + e);
            }