test

Sun Java System SAML v2 Plug-in for Federation Services User's Guide

Chapter 5 Developer Tools

The SAML v2 Plug-in for Federation Services can be installed in an instance of Access Manager or Federation Manager, and integrated with your application to implement the SAML v2 profiles. After installation, included service provider interfaces (SPI) and JavaServer Pages™ (JSP™) can be used for customization. Alternately, the SAML v2 Plug-in for Federation Services software development kit (SDK) itself can be deployed inside your application to implement proprietary SAML v2 profiles.

This chapter covers the following topics:

The SAML v2 Plug-in for Federation Services SDK

The SAML v2 Plug-in for Federation Services provides application programming interfaces (API) that can be used to construct and process assertions, requests, and responses. The SAML v2 Plug-in for Federation Services SDK is designed to be pluggable although it can also be run as a standalone application (outside of an instance of Access Manager or Federation Manager).

The SDK Packages

The SAML v2 Plug-in for Federation Services SDK includes the following packages:

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

Note –

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.

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.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 could set a customized implementation class:

  1. Add a mapping property to AMConfig.properties in the format:

    com.sun.identity.saml2.sdk.mapping.interface-name=new-class-name

    For example, to define a customized Assertion interface, you would add:


    com.sun.identity.saml2.sdk.mapping.Assertion=
 com.ourcompany.saml2.AssertionImpl
    Note –

    AMConfig.properties is located in the /etc/opt/product-directory/config directory in Access Manager and in the /staging-directory/web-src/WEB-INF/classes directory in Federation Manager.

  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

ProcedureTo Install the SAML v2 Plug-in for Federation Services SDK

Before You Begin

If installing the SDK on a Linux system, you must have the Red Hat Package Manager (RPM) installed.

  1. Log in as root.

  2. Create a new directory.


    # mkdir saml2bits


    # cd saml2bits

  3. Download the file-name.tar.gz file into the new directory.

    See the Sun Java System SAML v2 Plug-in for Federation Services Release Notes for the download URL.

  4. Unpack the product binaries by typing:


    # gunzip —dc file-name.tar.gz | tar -xvof -

    where file-name.tar.gz is the name of the downloaded file.

  5. Add the SAML v2 packages as follows:


    # pkgadd -d . SUNWsaml2

    By default, the packages will be installed in /AccessManager-base/product-directory/saml2 or /FederationManager-base/SUNWam/saml2.

  6. Add the following to the classpath of your application:

    • For Access Manager 7 2005Q4:

      • /opt/product-directory/saml2/lib/saml2.jar

      • /opt/product-directory/saml2/locale

    • For Federation Manager 7 2005Q4:

      • /opt/SUNWam/saml2/lib/saml2.jar

      • /opt/SUNWam/saml2/locale

  7. Get the supporting JAR and locale files using the applicable procedure:

    • For Access Manager 7 2005Q4:

      1. cd /AccessManager-base/product-directory

      2. Run the following command:


        # make -f Makefile.clientsdk

      3. Add the following to the classpath of your application:

        • AccessManager-base/product-directory/clientsdk-webapps/WEB-INF/lib/ amclientsdk.jar

        • AccessManager-base/product-directory/clientsdk-webapps/WEB-INF/classes

    • For Federation Manager 7 2005Q4:

      Add the following to the classpath of your application:

      1. FederationManager-base/SUNWam/fm/web-src/WEB-INF/lib/am_services.jar

      2. FederationManager-base/SUNWam/fm/web-src/WEB-INF/lib/am_sdk.jar

      3. FederationManager-base/SUNWam/fm/web-src/WEB-INF/classes

  8. Restart your application.

    You should now be able to process SAML v2 XML messages using the methods in the AssertionFactory and ProtocolFactory.

Next Steps

For details regarding the SAML v2 SDK classes, see the Sun Java System SAMLv2 Plug-in for Federation Services Java API Reference.

Note –

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.

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:

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

Note –

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

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.

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

The procedure for configuring mappings is in the following section:

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:

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

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

SPAuthnContextMapper Attributes

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

ProcedureTo 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

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 Plug-in for Federation Services 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 /AccessManager-base/product-directory/saml2/config/jsp directory or the /FederationManager-base/SUNWam/saml2/config/jsp directory. The following sections contain descriptions of, and uses for, the JSP.

Caution – Caution –

The following JSP cannot be modified:

Default Display Page

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

Caution – Caution –

When the value of <RelayState> or <defaultRelayState> contains special characters (such as &), it must be URL-encoded. For more information, see Service Provider Extended Metadata Properties.

Assertion Consumer Page

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

Single Sign-on Pages

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

idpSSOFederate.jsp

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

idpSSOInit.jsp

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

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

spSSOInit.jsp

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

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

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.

idpMNIRequestInit.jsp

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

Some of the other optional parameters are :

idpMNIRedirect.jsp

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

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

spMNIRequestInit.jsp

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

Some of the other optional parameters are :

spMNIRedirect.jsp

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

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

Single Logout JavaServer 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.

idpSingleLogoutInit.jsp

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

idpSingleLogoutRedirect.jsp

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

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

spSingleLogoutInit.jsp

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

spSingleLogoutRedirect.jsp

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

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