Service Provider Interfaces

The com.sun.identity.saml2.plugins package provides pluggable interfaces to implement SAML v2 functionality into your 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

For more information, see the Sun Java System SAMLv2 Plug-in for Federation Services Java API Reference.

You can also extract and view the SAML v2 Plug-in for Federation Services Java API Reference internally. Change to the /AccessManager-base/product-directory/saml2/docs directory on Access Manager or the /FederationManager-base/SUNWam/saml2/docs directory on Federation Manager and extract saml2_public_javadocs.jar to your web container. The Java API Reference can then be viewed using a web browser.

Account Mappers

An account mapper is used to associate a local user account with a remote user account based on a specified attribute. A default account mapper has been developed for both sides of the SAML v2 interaction, service providers and identity providers.

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, com.sun.identity.saml2.plugins.DefaultIDPAccountMapper, maps the accounts based on the persistent NameID attribute.

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

• To Set Up Attribute Mappers

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.

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.

To Set Up Attribute Mappers

This procedure will pass the mail and employeeNumber attributes from the identity provider to the service provider.

1. Export the identity provider's current extended metadata configuration to a file.

   saml2meta [-i staging-directory] export -u amadmin -w password -e IDP-entityID -x IDP-extended-XML-file-name

2. Edit the attributeMap attribute in the exported extended metadata configuration file to include the user attributes the identity provider will pass to the service provider.

   attributeMap defines the mapping between the provider that this metadata is configuring and the remote provider. This attribute takes a value of autofedAttribute-value=remote-provider-attribute. For example,

   <Attribute name="attributeMap">
   <Value>mail=mail</Value>
   <Value>employeeNumber=employeeNumber</Value>
   </Attribute>

3. Remove the identity provider's current extended metadata configuration.

   saml2meta [-i staging-directory] delete -u amadmin -w password -e IDP-entityID -c

4. Import the identity provider's modified extended metadata configuration file.

   saml2meta [-i staging-directory] import -u amadmin -w password -x IDP-extended-XML-file-name

5. Restart the web container.

6. Repeat the above steps for the service provider's extended metadata configuration file.

7. To test, invoke single sign-on from the service provider.

   The assertion contains an AttributeStatement with the mail and employeeNumber attributes which will be set in the single sign-on token.

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 mappers pair a standard SAMLv2 authentication context class reference (PasswordProtectedTransport, for example) to an Access Manager authentication scheme (module=LDAP, for example) on the identity provider side and set 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://AM_host:AM_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

The procedure for configuring mappings is in the following section:

• To Configure Mappings

IDPAuthnContextMapper

The IDPAuthnContextMapper is configured for the identity provider and maps incoming authentication requests from the service provider to an Access Manager 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 Access Manager authentication scheme. It takes a value in the following format:

  authnContextClassRef | authnType=authnValue | authnType=anthnValue | ...

  For example, urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|module=LDAP maps the SAMLv2 PasswordProtectedTransport class reference to the Access Manager 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 sections describe the parameters and attributes:

• SPAuthnContextMapper Parameters

• SPAuthnContextMapper Attributes

SPAuthnContextMapper Parameters

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

SPAuthnContextMapper Attributes

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.

To Configure Mappings

The following procedure assumes you are mapping urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport to authentication level 4 on the service provider and use the LDAP authentication module for authentication on the identity provider.

1. Set the mapping for the spAuthncontextClassrefMapping property in the current extended service provider metadata.

   For example, PasswordProtectedTransport|4

2. Reload the modified metadata using saml2meta.

   See The saml2meta Command-line Reference.

3. Set the mapping for the idpAuthncontextClassrefMapping property in the current extended identity provider metadata.

   For example, urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|module=LDAP

4. Reload the modified metadata using saml2meta.

   See The saml2meta Command-line Reference.

5. Access the single sign-on initialization page using the following URL:

   http://AM_host:AM_port/uri/spSSOinit.jsp?metaAlias=/sp&idpEntityID=idp.sun.com&AuthnContextClassRef=PasswordProtectedTransport