Chapter 11. Managing SAML 2.0 Federation

Table of Contents
11.1. About SAML 2.0 SSO & Federation
11.2. Setting Up SAML 2.0 SSO
11.3. Configuring Identity Providers
11.4. Configuring Service Providers
11.5. Configuring Circles of Trust
11.6. Configuring Providers for Failover
11.7. Configuring Google Apps as a Remote Service Provider
11.8. Configuring Salesforce CRM as a Remote Service Provider
11.9. Using SAML 2.0 Single Sign-On & Single Logout
11.10. Configuring OpenAM For the ECP Profile
11.11. Managing Federated Accounts
11.12. Using SAML 2.0 Artifacts
11.13. SAML 2.0 & Policy Agents

This chapter addresses how to set up and manage SAML 2.0 SSO for single sign on and single log out across resources belonging to organizations participating in a circle of trust.

11.1. About SAML 2.0 SSO & Federation

SAML 2.0 SSO is part of federated access management. Federation lets access management cross organizational boundaries. Federation helps organizations share identities and services without giving away their identity information, or the services they provide.

To bridge heterogeneous systems, federation requires interoperability, and thus depends on standards for orchestrating interaction and exchanging information between providers. OpenAM federation relies on standards such as Security Assertion Markup Language (SAML) 2.0. SAML 2.0 describes the messages, how they are relayed, how they are exchanged, and common use cases.

To achieve SAML 2.0 SSO, OpenAM separates identity providers from service providers, lets you include them them in a circle of trust, and has you configure how the providers in the circle of trust interact.

  • An identity provider stores and serves identity profiles, and handles authentication.

  • A service provider offers services that access protected resources, and handles authorization.

  • A circle of trust groups at least one identity provider and at least one service provider who agree to share authentication information, with assertions about authenticated users that let service providers make authorization decisions.

    Providers in a circle of trust share metadata, configuration information that federation partners require to access each others' services.

  • SAML 2.0 SSO maps attributes from accounts at the identity provider to attributes on accounts at the service provider. The identity provider makes assertions to the service provider, for example to attest that a user has authenticated with the identity provider. The service provider then consumes assertions from the identity provider to make authorization decisions, for example to let an authenticated user complete a purchase that gets charged to the user's account at the identity provider.

In federation deployments where not all providers support SAML 2.0, OpenAM can act as a multi-protocol hub, translating for providers who rely on other and older standards such as SAML 1.x, Liberty Alliance Project frameworks, and WS-Federation (for integration with Active Directory Federation Services, for example).

11.2. Setting Up SAML 2.0 SSO

Before you set up SAML 2.0 SSO in OpenAM, you must:

  • Know which providers participate in the circle of trust.

  • Know how OpenAM installations act as identity providers, or service providers.

  • Agree with other providers on a synchronized time service.

  • For identity information exchanged with other participants in a circle of trust, define how to map shared user attributes. Local user profile attribute names should map to user profile attribute names at other providers.

    For example, if you exchange user identifiers with your partners, and you call it uid whereas another partner calls it userid, then you map your uid to your partner's userid.

  • Import the keys used to sign assertions into the JKS key store in your OpenAM configuration directory. You can use the Java keytool command.

    The OpenAM configuration key store is located at the top level of the configuration directory, such as $HOME/openam/keystore.jks. The password, stored in $HOME/openam/.keypass, is changeit by default. Also by default the only key available is for a self-signed certificate (alias: test) installed with OpenAM.

During set up, you must share metadata for providers that you host with other providers in the circle of trust. You must also configure remote providers, connecting to other providers by importing their metadata.

In OpenAM terms, a hosted provider is one served by the current OpenAM server, whereas a remote provider is one hosted elsewhere.

Procedure 11.1. To Create a Hosted Identity Provider
  1. On the OpenAM console Common Tasks page, click Create Hosted Identity Provider.

  2. Unless you already have metadata for the provider, accept the Name for this identity provider in the field provided, or provide your own unique identifier.

    The default name is the URL to the current server which hosts the identity provider.

  3. Select the Signing Key you imported into the OpenAM key store.

  4. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

  5. For the attributes you share, map service provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

    The default IDP mapping implementation allows you to add static values in addition to values taken from the user profile. You add a static value by enclosing the profile attribute name in double quotes ("), as in the following examples.

    To add a static SAML attribute called partnerID with a value of staticPartnerIDValue, add partnerID as the Name in Assertion with "staticPartnerIDValue" as the Local Attribute Name.

    The default IDP attribute mapper also allows you to Base64 encode binary attributes when adding them to the SAML attributes. Add ;binary to the end of the attribute name, as in the following example:

    objectGUID=objectGUID;binary

    This maps the local binary attribute objectGUID to a SAML attribute called objectGUID that is Base64 encoded.

    The default IDP attribute mapper also supports NameFormatURI format as shown in the following example:

    urn:oasis:names:tc:SAML:2.0:attrname-format:uri|objectGUID=objectGUID;binary
  6. Click Configure to save your configuration.

  7. Export the XML-based metadata from your provider to share with other providers in your circle of trust.

    $ curl \
     --output metadata.xml \
     "http://www.idp.example:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=\
    http://www.idp.example:8080/openam&realm=/realm-name"
        

    When you have configured only the top-level realm, /, you can omit the query string.

    Alternatively, provide the URL, to other providers so they can load the metadata.

Procedure 11.2. To Create a Hosted Service Provider
  1. On the OpenAM console Common Tasks page, click Create Hosted Service Provider.

  2. Unless you already have metadata for the provider, accept the Name for this service provider in the field provided, or provide your own unique identifier.

    The default name is the URL to the current server which hosts the service provider.

  3. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

  4. If the identity provider has not already mapped the attributes you share, map identity provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

  5. Click Configure to save your configuration.

  6. Export the XML-based metadata from your provider to share with other providers in your circle of trust.

    $ curl \
     --output metadata.xml \
     "http://www.sp.example:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=\
    http://www.sp.example:8080/openam&realm=/realm-name"
        

    When you have configured only the top-level realm, /, you can omit the query string.

    Alternatively, provide the URL, to other providers so they can load the metadata.

Procedure 11.3. To Create a Remote Identity Provider
  1. Obtain the identity provider metadata, or the URL where you can obtain it.

  2. On the OpenAM console Common Tasks page, click Register Remote Identity Provider.

  3. Provide the identity provider metadata or link to obtain metadata.

  4. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

  5. Click Configure to save your configuration.

Procedure 11.4. To Create a Remote Service Provider
  1. Obtain the service provider metadata, or the URL where you can obtain it.

  2. On the OpenAM console Common Tasks page, click Register Remote Service Provider.

  3. Provide the identity provider metadata or link to obtain metadata.

  4. If the identity provider has not already mapped the attributes you share, map identity provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

  5. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

  6. Click Configure to save your configuration.

Procedure 11.5. To Create a Fedlet for Service Providers

When your organization acts as the identity provider, and you want quickly to enable service providers to federate their services with yours, you can provide them with a fedlet. A fedlet is a small Java or .NET web application that can act as a service provider for a specific identity provider without requiring that you install all of OpenAM.

Fedlets support the following SAML 2.0 features.

Table 11.1. Fedlet Support for SAML 2.0 Features
SAML 2.0 FeatureJava Fedlet.NET Fedlet
IDP & SP-initiated Single Sign-On (HTTP Artifact)SupportedSupported
IDP & SP-initiated Single Sign-On (HTTP POST)SupportedSupported
IDP & SP-initiated Single Logout (HTTP POST)SupportedSupported
IDP & SP-initiated Single Logout (HTTP Redirect)SupportedSupported
Sign Requests & ResponsesSupportedSupported
Encrypt Assertion, Attribute, & NameID ElementsSupportedSupported
Export SP MetadataSupportedSupported
Attribute QueriesSupportedSupported
XACML RequestsSupportedNot supported
Multiple IDPsSupportedSupported
External IDP Discovery ServiceSupportedSupported
Bundled IDP Reader Service for DiscoverySupportedNot supported

For more information on using fedlets, see Using Fedlets in Java Web Applications and Using Fedlets in .NET Applications in the Developer's Guide.

The following procedure describes how to create a Java Fedlet.

  1. If you have not done so already, set up your identity provider.

  2. Enter the URL where the service provider will deploy the fedlet you create, and name the fedlet. If you create multiple fedlets, use the URL as a unique name that shows who has deployed the fedlet.

  3. For the attributes you share, map service provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

  4. Click Create to generate the Fedlet.zip file under the OpenAM configuration directory, such as $HOME/openam/myfedlets/httpwwwexamplecom80myapp/Fedlet.zip.

  5. Give the Fedlet.zip file to the service provider for deployment.

11.2.1. Deploying the Identity Provider Discovery Service

When your circle of trust includes multiple identity providers, then service providers must discover which identity provider corresponds to a request. You can deploy the identity provider discovery service for this purpose as a separate web application.

Browsers only send cookies for the originating domain. Therefore when a browser accesses the service provider in the www.sp.example domain, the service provider has no way of knowing whether the user has perhaps already authenticated at www.this-idp.example or at www.that-idp.example. The providers therefore host an identity provider discovery service in a common domain, such as www.disco.example, and use that service to discover where the user logged in. The identity provider discover service essentially writes and reads cookies from the common domain. The providers configure their circle of trust to use the identity provider discovery service as part of SAML 2.0 federation.

Deploying the identity provider discovery service involves the following stages.

  1. Deploy the .war file into your web application container.

  2. Configure the discovery service.

  3. Add the identity provider discovery service endpoints for writing cookies to and reading cookies from the common domain to the circle of trust configurations for the providers.

  4. Share metadata between identity providers and the service provider.

Procedure 11.6. To Deploy the Discovery Service on Tomcat

How you deploy the discovery service .war file depends on your web application container. The procedure in this section shows how to deploy on Apache Tomcat.

  1. Copy the IDPDiscovery-12.0.0-SNAPSHOT.war file to the webapps/ directory.

    $ cp ~/Downloads/openam/IDPDiscovery-12.0.0-SNAPSHOT.war \
     /path/to/tomcat/webapps/disco.war
         
  2. Access the configuration screen through your browser.

    In this example, Apache Tomcat listens for HTTP requests on www.disco.example:8080, and Tomcat has unpacked the application under /disco, so the URL is http://www.disco.example:8080/disco, which redirects to Configurator.jsp.

Procedure 11.7. To Configure the Discovery Service
  1. Configure the identity provider discovery service.

    Completed discovery service configuration screen

    Hints for discovery service configuration parameters follow.

    Debug Directory

    The discovery service logs to flat files in this directory.

    Debug Level

    Default is error. Other options include error, warning, message, and off.

    Set this to message in order to see the service working when you run your initial tests.

    Cookie Type

    Set to PERSISTENT if you have configured OpenAM to use persistent cookies, meaning single sign on cookies that can continue to be valid after the browser is closed.

    Cookie Domain

    The cookie domain is the common cookie domain used in your circle of trust for identity provider discovery, in this case .disco.example.

    Secure Cookie

    Set this to true if clients should only return cookies when a secure connection is used.

    Encode Cookie

    Leave this true unless your OpenAM installation requires that you do not encode cookies. Normally cookies are encoded such that cookies remain valid in HTTP.

    HTTP-Only Cookie

    Set to true to use HTTPOnly cookies if needed to help prevent third-party programs and scripts from accessing the cookies.

  2. Restrict permissions to the discovery service configuration file in $HOME/libIDPDiscoveryConfig.properties, where $HOME corresponds to the user who runs the web container where you deployed the service.

Procedure 11.8. To Add the Discovery Service to Your Circles of Trust

Each provider has a circle of trust including itself. You configure each of these circles of trust to use the identity provider discovery service as described in the following steps.

  1. On the service provider console, login as OpenAM Administrator.

  2. On the service provider console, under Federation > Circle of Trust > Circle of Trust Name add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and Save your work.

    In this example, the writer URL is http://www.disco.example:8080/disco/saml2writer, and the reader URL is http://www.disco.example:8080/disco/saml2reader.

  3. On each identity provider console, login as OpenAM Administrator.

  4. On the identity provider console, under Federation > Circle of Trust Configuration > Circle of Trust Name also add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and Save your work.

Procedure 11.9. To Share Identity & Service Provider Metadata

Before performing these steps, install the administration tools for each provider as described in To Set Up Administration Tools. The administration tools include the ssoadm tool that you need to export metadata.

  1. On each identity provider console, register the service provider as a remote service provider adding to the circle of trust you configured to use the identity provider discovery service.

    The URL to the service provider metadata is something like http://www.sp.example:8080/openam/saml2/jsp/exportmetadata.jsp.

  2. Obtain metadata for each identity provider.

    $ ssh www.this-idp.example
    $ cd /path/to/openam-tools/admin/openam/bin
    $ ./ssoadm \
     create-metadata-templ \
     --entityid "http://www.this-idp.example:8080/openam" \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --identityprovider /idp \
     --meta-data-file this-standard.xml \
     --extended-data-file this-extended.xml
    Hosted entity configuration was written to this-extended.xml.
    Hosted entity descriptor was written to this-standard.xml.
    
    $ ssh www.that-idp.example
    $ cd /path/to/openam-tools/admin/openam/bin
    $ ./ssoadm \
     create-metadata-templ \
     --entityid "http://www.that-idp.example:8080/openam" \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --identityprovider /idp \
     --meta-data-file that-standard.xml \
     --extended-data-file that-extended.xml
    
    Hosted entity configuration was written to that-extended.xml.
    Hosted entity descriptor was written to that-standard.xml.
         
  3. For each identity provider extended metadata file, change the value of the hosted attribute to 0, meaning the identity provider is remote.

  4. On the service provider, add the identity providers to the circle of trust using the identity provider metadata.

    $ ssh www.sp.example
    $ cd /path/to/openam-tools/admin/openam/bin
    $ ./ssoadm \
     import-entity \
     --cot discocot \
     --meta-data-file ~/Downloads/this-standard.xml \
     --extended-data-file ~/Downloads/this-extended.xml \
     --adminid amadmin \
     --password-file /tmp/pwd.txt
    
    Import file, /Users/mark/Downloads/this-standard.xml.
    Import file, /Users/mark/Downloads/this-extended.xml.
    $ ./ssoadm \
     import-entity \
     --cot discocot \
     --meta-data-file ~/Downloads/that-standard.xml \
     --extended-data-file ~/Downloads/that-extended.xml \
     --adminid amadmin \
     --password-file /tmp/pwd.txt
    
    Import file, /Users/mark/Downloads/that-standard.xml.
    Import file, /Users/mark/Downloads/that-extended.xml.
         
  5. Test your work by using the Federation Connectivity Test that you start from the service provider console under Common Tasks > Test Federation Connectivity.

    When the test is done, you can see messages from the CookieWriterServlet in the libIDPDiscovery log file where you set up logging when you configured the identity provider discovery service, such as /tmp/debug/libIDPDiscovery. Output generated during a test follows, with some lines folded to fit on the printed page.

    08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieUtils.init : idpDiscoveryOnlyWar=true
    08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet Initializing...
    08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Preferred Cookie Name is _saml_idp
    08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: URL Scheme is null, set to https.
    08/08/2012 11:43:38:341 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Preferred IDP Cookie Not found
    08/08/2012 11:43:38:342 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Cookie Type is PERSISTENT
    08/08/2012 11:43:38:342 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Cookie value is
     aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=
    08/08/2012 11:43:38:342 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Preferred Cookie Name _saml_idp
    08/08/2012 11:43:38:343 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Redirect to
     http://www.that-idp.example:8080/openam/SSORedirect/metaAlias/idp?resInfoID=
     s28bc4db004f1365d78d07d69846c54a3c850fe801
    08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Preferred Cookie Name is _saml_idp
    08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieUtils:cookieValue=aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=,
     result=aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=
    08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Cookie Type is PERSISTENT
    08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Cookie value is
     aHR0cDovL3d3dy50aGF0LWlkcC5jb206ODA4MC9vcGVuYW0=
    08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Preferred Cookie Name _saml_idp
    08/08/2012 11:43:46:957 AM CEST: Thread[http-bio-8080-exec-4,5,main]
    CookieWriterServlet.doGetPost: Redirect to
     http://www.that-idp.example:8080/openam/SSORedirect/metaAlias/idp?resInfoID=
     s2ce9c465cf39c96f31e1dcf009cf9943695d82901
         

11.3. Configuring Identity Providers

Once you have set up an identity provider, you can configure it through the OpenAM console under Federation > Entity Providers > Provider Name.

11.3.1. Hints for Assertion Content

Use the following hints to adjust settings on the Assertion Content tab page.

Signing and Encryption
Request/Response Signing

Specifies what parts of messages the identity provider requires the service provider to sign digitally.

Encryption

When selected, the service provider must encrypt NameID elements.

Certificate Aliases

Specifies aliases for certificates in the OpenAM key store that are used to handle digital signatures, and to handle encrypted messages.

Specify a Key Pass if the private key password is different from the key store password, which is stored encrypted in the .keypass file for the server. For instructions on working with key pairs, also see To Change the Signing Key for Federation.

NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign on. If no name identifier is specified when initiating single sign on, then the identity provider uses the first one in the list.

NameID Value List

Maps name identifier formats to user profile attributes. The persistent and transient name identifiers need not be mapped.

Authentication Context
Mapper

Specifies a class that implements the IDPAuthnContextMapper interface and sets up the authentication context.

Default Authentication Context

Specifies the authentication context used if no authentication context specified in the request.

Supported Contexts

Specifies the supported authentication contexts, where the Key and Value can specify a corresponding OpenAM authentication method, and the Level corresponds to an authentication module authentication level.

Assertion Time
Not-Before Time Skew

Grace period in seconds for the NotBefore time in assertions.

Effective Time

Validity in seconds of an assertion.

Basic Authentication
Enabled, User Name, Password

When enabled, authenticate with the specified user name and password at SOAP end points.

Assertion Cache
Enabled

When enabled, cache assertions.

11.3.2. Hints for Assertion Processing

Use the following hints to adjust settings on the Assertion Processing tab page.

Attribute Mapper
Attribute Mapper

Specifies a class that implements the attribute mapping.

The default implementation attempts to retrieve the mapped attribute values from the user profile first. If the attribute values are not present in the user's profile, then it attempts to retrieve them from the user's session.

Default: com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper

Attribute Map

Maps SAML attributes to user profile attributes.

The user profile attributes used here must both be allowed in user profiles, and also be specified for the identity repository. See the Developer's Guide chapter, Customizing Profile Attributes, for instructions on allowing additional attributes in user profiles.

To specify the list of profile attributes for an LDAP identity repository, login to OpenAM Console as administrator and browse to Access Control > Realm Name > Data Stores, and click the data store name to open the configuration page. Scroll down to User Configuration, and edit the LDAP User Attributes list, and then click Save to keep your work.

The default IDP mapping implementation allows you to add static values in addition to values taken from the user profile. You add a static value by enclosing the profile attribute name in double quotes ("), as in the following examples.

To add a static SAML attribute called nameID with a value of staticNameIDValue with a name format of urn:oasis:names:tc:SAML:2.0:attrname-format:uri, add the following mapping.

urn:oasis:names:tc:SAML:2.0:attrname-format:uri|nameID="staticNameIDValue"
Account Mapper
Account Mapper

Specifies a class that implements AccountMapper to map remote users to local user profiles.

Local Configuration
Auth URL

URL where users are redirected to authenticate.

Reverse Proxy URL

When a reverse proxy is used for SAML endpoints, it is specified here.

External Application Logout URL

URL to which to send an HTTP POST including all cookies when receiving a logout request. To add a user session property as a POST parameter, include it in the URL query string as a appsessionproperty parameter.

11.3.3. Hints for Services

Use the following hints to adjust settings on the Services tab page.

MetaAlias
MetaAlias

Used to locate the providers entity identifier, specified as [/realm-name]*/provider-name, where neither realm-name nor provider-name can contain slash characters (/). For example: /realm/sub-realm/idp.

IDP Service Attributes
Artifact Resolution Service

Specifies the end point to handle artifact resolution. The Index is a unique number identifier for the end point.

Single Logout Service

Specifies the end points to handle single logout, depending on the SAML binding selected.

Manage NameID Service

Specifies the end points to handle name identifiers, depending on the SAML binding selected.

Single SignOn Service

Specifies the end points to handle single sign on.

NameID Mapping
URL

Specifies the end point to handle name identifier mapping.

11.3.4. Hints for Advanced Settings

Use the following hints to adjust settings on the Advanced tab page.

SAE Configuration
IDP URL

Specifies the end point to handle Secure Attribute Exchange requests.

Application Security Configuration

Specifies how to handle encryption for Secure Attribute Exchange operations.

ECP Configuration
IDP Session Mapper

Specifies the class that finds a valid session from an HTTP servlet request to an identity provider with a SAML Enhanced Client or Proxy profile.

Session Synchronization
Enabled

When enabled, the identity provider notifies service providers to log the user out when a session expires.

IDP Finder Implementation
IDP Finder Implementation Class

Specifies a class that finds the preferred identity provider to handle a proxied authentication request.

IDP Finder JSP

Specifies a JSP that presents the list of identity providers to the user.

Enable Proxy IDP Finder For All SPs

When enabled, apply the finder for all remote service providers.

Relay State URL List
Relay State URL List

List of URLs to which to redirect users after the request has been handled. Used if not specified in the service provider extended metadata.

IDP Adapter
IDP Adapter Class

Specifies a class to invoke immediately before sending a SAML 2.0 response.

11.4. Configuring Service Providers

Once you have set up a service provider, you can configure it through the OpenAM console under Federation > Entity Providers > Provider Name.

11.4.1. Hints for Assertion Content

Use the following hints to adjust settings on the Assertion Content tab page.

Signing and Encryption
Request/Response Signing

Specifies what parts of messages the service provider requires the identity provider to sign digitally.

Encryption

The identity provider must encrypt selected elements.

Certificate Aliases

Specifies aliases for certificates in the OpenAM key store that are used to handle digital signatures, and to handle encrypted messages.

NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign on. If no name identifier is specified when initiating single sign on, then the service provider uses the first one in the list supported by the identity provider.

Disable Federation persistence if NameID Format is unspecified

When enabled, the NameID Format in the authentication response is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, and the Account Mapper has identified the local user, the service provider does not persist federation information in the user profile.

Authentication Context
Mapper

Specifies a class that implements the SPAuthnContextMapper interface and sets up the authentication context.

Default Authentication Context

Specifies the authentication context used if no authentication context specified in the request.

Supported Contexts

Specifies the supported authentication contexts. The Level corresponds to an authentication module authentication level.

Comparison Type

How the authentication context in the assertion response must compare to the supported contexts.

Assertion Time
Assertion Time Skew

Grace period in seconds for the NotBefore time in assertions.

Basic Authentication
Enabled, User Name, Password

When enabled, authenticate with the specified user name and password at SOAP end points.

11.4.2. Hints for Assertion Processing

Use the following hints to adjust settings on the Assertion Processing tab page.

Attribute Mapper
Attribute Mapper

Specifies a class that implements the attribute mapping.

Attribute Map

Maps SAML attributes to user profile attributes.

Auto Federation
Enabled

When enabled, automatically federate user's accounts at different providers based on the specified profile attribute.

Attribute

Specifies the user profile attribute to match accounts at different providers.

Account Mapper
Account Mapper

Specifies a class that implements AccountMapper to map remote users to local user profiles.

Use Name ID as User ID

When selected, fall back to using the name identifier from the assertion to find the user.

Artifact Message Encoding
Encoding

Specifies the message encoding format for artifacts.

Transient User
Transient User

Specifies the user profile to which to map all identity provider users when sending transient name identifiers.

URL
Local Authentication URL

Specifies the local login URL.

Intermediate URL

Specifies a URL to which the user is redirected after authentication but before the original URL requested.

External Application Logout URL

Specifies the URL to which to send an HTTP POST including all cookies when receiving a logout request. To add a user session property as a POST parameter, include it in the URL query string as a appsessionproperty parameter.

Default Relay State URL
Default Relay State URL

Specifies the URL to which to redirect users after the request has been handled. Used if not specified in the response.

Adapter
Adapter

Specifies a class that implements the FederationSPAdapter interface and performs application specific processing during the federation process.

Adapter Environment

Specifies environment variables passed to the adapter class.

11.4.3. Hints for Services

Use the following hints to adjust settings on the Services tab page.

MetaAlias
MetaAlias

Used to locate the providers entity identifier, specified as [/realm-name]*/provider-name, where neither realm-name nor provider-name can contain slash characters (/). For example: /realm/sub-realm/sp.

SP Service Attributes
Single Logout Service

Specifies the end points to handle single logout, depending on the SAML binding selected.

Manage NameID Service

Specifies the end points to handle name identifiers, depending on the SAML binding selected.

Assertion Consumer Service

Specifies the end points to consume assertions, with Index corresponding to the index of the URL in the standard metadata.

11.4.4. Hints for Advanced Settings

Use the following hints to adjust settings on the Advanced tab page.

SAE Configuration
SP URL

Specifies the end point to handle Secure Attribute Exchange requests.

SP Logout URL

Specifies the end point of the service provider that can handle global logout requests.

Application Security Configuration

Specifies how to handle encryption for Secure Attribute Exchange operations.

ECP Configuration
Request IDP List Finder Implementation

Specifies a class that returns a list of preferred identity providers trusted by the SAML Enhanced Client or Proxy profile.

Request IDP List Get Complete

Specifies a URI reference used to retrieve the complete identity provider list if the IDPList element is not complete.

Request IDP List

Specifies a list of identity providers for the SAML Enhanced Client or Proxy to contact, used by the default implementation of the IDP Finder.

IDP Proxy
IDP Proxy

When enabled, allow proxied authentication for this service provider.

Introduction

When enabled, use introductions to find the proxy identity provider.

Proxy Count

Specifies the maximum number of proxy identity providers.

IDP Proxy List

Specifies a list of URIs identifying preferred proxy identity providers.

Session Synchronization
Enabled

When enabled, the service provider notifies identity providers to log the user out when a session expires.

Relay State URL List
Relay State URL List

List of URLs to which to redirect users after the request has been handled. Used if not specified in the service provider extended metadata.

11.5. Configuring Circles of Trust

Once you have set up a circle of trust, you can configure it through the OpenAM console under Federation > Circle of Trust > Circle of Trust Name.

Name

String to refer to the circle of trust.

Description

Short description of the circle of trust.

IDFF Writer Service URL

Liberty Identity Federation Framework service that writes identity provider entity identifiers to Common Domain cookies after successful authentication, used in identity provider discovery. Example: http://www.disco.example:8080/openam/idffwriter.

IDFF Reader Service URL

Liberty Identity Federation Framework service that reads identity provider entity identifiers from Common Domain cookies, used in identity provider discovery. Example: http://www.disco.example:8080/openam/transfer.

SAML2 Writer Service URL

SAML 2.0 service that writes identity provider entity identifiers to Common Domain cookies after successful authentication, used in identity provider discovery. Example: http://www.disco.example:8080/openam/saml2writer.

SAML2 Reader Service URL

SAML 2.0 service that reads identity provider entity identifiers from Common Domain cookies, used in identity provider discovery. Example: http://www.disco.example:8080/openam/saml2reader.

Status

Whether this circle of trust is operational.

Realm

Name of the realm participating in this circle of trust.

Entity Providers

Known hosted and remote identity and service providers participating in this circle of trust.

11.6. Configuring Providers for Failover

OpenAM servers can function in a site configuration behind a load balancer, as described in the Installation Guide chapter, Setting Up OpenAM Session Failover.

When you set up the same SAML 2.0 Provider on multiple servers behind a load balancer, however, you must ensure the metadata points to the load balancer rather than the individual servers.

  1. Before configuring the provider, follow the instructions in the Installation Guide mentioned above, and make sure that failover works through the load balancer for normal OpenAM sessions.

  2. Configure the provider on one of the servers using the load balancer URL as the entity ID.

  3. Export the metadata and extended metadata for the provider. You can export metadata either by using the ssoadm command, or by using the ssoadm.jsp page in OpenAM console after setting ssoadm.disabled to false under Servers and Sites > Server Name > Advanced.

    With the ssoadm command, you can export the metadata as shown in the following example for an Identity Provider, where the entity ID is http://lb.example.com:80/openam.

    $ ssoadm \
     export-entity \
     --entityid "http://lb.example.com:80/openam" \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --meta-data-file idp.xml \
     --extended-data-file idp-extended.xml
        
  4. Edit both the metadata and the extended metadata, changing all URLs in both files to use the load balancer URL.

  5. Delete the provider configuration in OpenAM Console.

  6. Import the edited provider configuration in OpenAM Console.

  7. Enable SAMLv2 failover in OpenAM Console.

    Under Configuration > Global, click SAMLv2 Service Configuration.

    Select Enabled next to Enable SAMLv2 failover, and then click Save.

At this point failover is operational for the provider you configured.

11.7. Configuring Google Apps as a Remote Service Provider

OpenAM can serve as the identity provider when you use Google Apps as a service provider, allowing users to have single sign-on with their Google Apps account.

In order to use this service, you must have a Google Apps account for at least one of your domains, such as example.com.

Procedure 11.10. To Integrate With Google Apps
  1. If you have not yet done so, set up OpenAM as described in Procedure 11.1, “To Create a Hosted Identity Provider”, using a signing certificate that is needed by Google Apps.

    See the procedure To Change the Signing Key for Federation for details regarding the signing certificate.

  2. On the OpenAM console Common Tasks page, click Configure Google Apps.

  3. On the first Configure Google Apps for Single Sign-On page, add your domain name(s) such as example.com to the list, and then click Create.

  4. On the second Configure Google Apps for Single Sign-On page, save the OpenAM verification certificate to a text file, such as OpenAM.pem.

  5. Follow the instructions under To Enable Access to the Google Apps API before clicking Finish.

    1. Access the Google Apps administration page for the first of your domains in a new browser tab or window.

    2. Login as Google Apps administrator.

    3. Select Enable Single Sign-On.

    4. Copy the URLs from the OpenAM page into the Google Apps setup screen.

    5. Upload the certificate file you saved such as OpenAM.pem as the Google Apps Verification Certificate.

    6. Select Use a domain specific issuer.

    7. Save changes in Google Apps setup.

    8. Repeat the steps above for each domain you have configured.

    9. Click Finish to complete the process.

11.8. Configuring Salesforce CRM as a Remote Service Provider

OpenAM can serve as the identity provider when you use Salesforce CRM as a service provider, allowing users to have single sign-on with their Salesforce CRM account.

In order to use this service, you must have Salesforce CRM accounts for your organization.

Procedure 11.11. To Integrate With Salesforce CRM
  1. If you have not yet done so, set up OpenAM as described in Procedure 11.1, “To Create a Hosted Identity Provider”, using a signing certificate that is needed by Salesforce CRM.

    See the procedure To Change the Signing Key for Federation for details regarding the signing certificate.

  2. On the OpenAM console Common Tasks page, click Configure Salesforce CRM.

  3. Enter the EntityID for your Salesforce service provider.

    This ID is used as the persistent EntityDescriptor metadata element so that users can have multiple service provider instances. This field is used for the EntityDescriptor on the next page.

  4. On the first Salesforce CRM Single Sign-On Configuration page, configure attribute mapping to associate the appropriate attribute from Salesforce CRM with the user profile attribute on your IDP.

    For example, add a mapping for IDPEmail to mail, and then click Create. Make sure the attribute mapper is sending the correct attribute to be used for the federated identity.

  5. On the second Salesforce CRM Single Sign-On Configuration page, follow the instructions below before clicking Finish.

    1. In a new browser tab or window, login to Salesforce CRM with your administrator credentials.

      Create an administrator account if none exists, yet.

    2. If your users go directly to Salesforce to access services, then their single sign-on is SP-initiated from the Salesforce side. Salesforce provides a "My Domain" feature to facilitate SP-initiated single sign-on for desktop and device users.

      When you have completed configuring Salesforce as a service provider, users can then browse to your domain at Salesforce, such as https://openam.my.salesforce.com, and be redirected to OpenAM to authenticate before being redirected to Salesforce.

      1. Select Administration Setup > Company Profile > My Domain.

      2. Choose the domain name, and then register the domain.

      3. Wait until the domain is ready for testing to proceed.

    3. In Salesforce CRM, browse to Setup > Administration Setup > Security Controls > Single Sign-On Settings, and then click Edit for Single Sign-On Settings.

    4. Select SAML Enabled.

    5. Set the SAML Version to 2.0.

    6. Copy the issuer name from the OpenAM page to the Issuer field on the Salesforce CRM page.

    7. Copy or download the OpenAM verification certificate to a text file, such as OpenAMCert.pem or OpenAMCert.txt.

    8. Upload the certificate file as Identity Provider Certificate on the Salesforce CRM page.

    9. For SAML Identity Type in Salesforce CRM, choose Assertion contains the Federation ID from the User object.

    10. For SAML Identity Location in Salesforce CRM, choose Identity is in an Attribute element.

    11. If you require specific login or logout pages, enter them in the next two fields.

    12. Enter the URL of your page specific error page if you have a page where you would like users redirected to when they encounter an error.

    13. Copy the attribute name such as IDPEmail from the OpenAM page to the Attribute Name field on the Salesforce CRM page.

    14. Salesforce uses an unspecified nameid-format value; therefore, your IdP configuration in OpenAM should reflect this. In the NameID Value Map setting, enter the following NameID Format user attribute mapping, and then click Add.

      urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified=attribute
             

      Here the attribute is the attribute you copied in Step 5.m.

    15. Select the Entity ID corresponding to the "My Domain" that you set up.

    16. Save your work in Salesforce CRM.

    17. Salesforce CRM displays a Salesforce Login URL.

      Copy the Salesforce Login URL to the field provided on the OpenAM page.

    18. Salesforce CRM returns to the Single Sign-On Settings form.

    19. Click Download Metadata to download the Salesforce CRM SP metadata.

      After you complete the configuration, you must import the SP metadata you download in this step.

    20. In Salesforce CRM, browse to Administration Setup > Manage Users, and then click Users.

    21. Add users as necessary, making sure the attribute chosen as the Federation ID matches the local attribute you mapped to the remote attribute in the previous page in OpenAM.

    22. Click Finish to complete the process.

  6. After you finish, import the metadata for Salesforce CRM as SP.

    1. Browse in OpenAM console to the Federation tab.

    2. If the remote SP entity for Salesforce CRM is already in the Entity Providers list, delete the existing configuration.

    3. Click Import Entity..., and then use the Import Entity Provider page to import the Salesforce CRM metadata.

      • Update the Realm Name to the appropriate realm.

      • Select the location where the metadata file is.

      • Enter the path for the metadata file.

      • If you have an extended data file, select the location where the file is.

      • If you have an extended data file, enter the path for the metadata file.

    At this point, when a user browses to the Salesforce domain you set up, they should be redirected to OpenAM for authentication. Upon successful authentication, they should be logged in to Salesforce.

11.9. Using SAML 2.0 Single Sign-On & Single Logout

OpenAM SAML 2.0 Federation provides JSPs where you can direct users to do single sign-on (SSO) and single logout (SLO) across providers in a circle of trust. OpenAM has two JSPs for SSO and two JSPs for SLO, allowing you to initiate both processes either from the identity provider side, or from the service provider side.

SSO lets users sign in once and remain authenticated as they access services in the circle of trust.

SLO attempts to log a user out of all providers in the circle of trust.

The JSP pages are found under the context root where you deployed OpenAM, in saml2/jsp/.

spSSOInit.jsp

Used to initiate SSO from the service provider side, so call this on the service provider not the identity provider. This is also mapped to the endpoint spssoinit under the context root.

Examples: http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp, http://www.sp.example:8080/openam/spssoinit

idpSSOInit.jsp

Used to initiate SSO from the identity provider side, so call this on the identity provider not the service provider. This is also mapped to the endpoint idpssoinit under the context root.

Examples: http://www.idp.example:8080/openam/saml2/jsp/idpSSOInit.jsp, http://www.idp.example:8080/openam/idpssoinit

spSingleLogoutInit.jsp

Used to initiate SLO from the service provider side, so call this on the service provider not the identity provider.

Example: http://www.sp.example:8080/openam/saml2/jsp/spSingleLogoutInit.jsp, http://www.sp.example:8080/openam/SPSloInit

idpSingleLogoutInit.jsp

Used to initiate SLO from the identity provider side, so call this on the identity provider not the service provider.

Example: http://www.idp.example:8080/openam/saml2/jsp/idpSingleLogoutInit.jsp, http://www.idp.example:8080/openam/IDPSloInit

When you invoke these JSPs, there are several parameters to specify. Which parameters you can use depends on the JSP.

idpSSOInit.jsp Parameters
metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as metaAlias=/myRealm/idp. This parameter takes the format /realm-name/provider-name as described in MetaAlias. You do not repeat the slash for the top level realm, for example metaAlias=/idp.

spEntityID

(Required) Use this parameter to indicate the remote service provider. Make sure you URL encode the value. For example, specify spEntityID=http://www.sp.example:8080/openam as spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam.

affiliationID

(Optional) Use this parameter to specify a SAML affiliation identifier.

binding

(Optional) Use this parameter to indicate what binding to use for the operation. For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. In addition to binding=HTTP-POST, you can also use binding=HTTP-Artifact.

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier such as urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, or urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL encode the value. For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

RelayStateAlias

(Optional) Use this parameter to specify the parameter to use as the RelayState. For example, if your query string has target=http%3A%2F%2Fforgerock.com&RelayStateAlias=target, this is like setting RelayState=http%3A%2F%2Fforgerock.com.

spSSOInit.jsp Parameters
idpEntityID

(Required) Use this parameter to indicate the remote identity provider. Make sure you URL encode the value. For example, specify idpEntityID=http://www.idp.example:8080/openam as idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam.

metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as metaAlias=/myRealm/sp. This parameter takes the format /realm-name/provider-name as described in MetaAlias. You do not repeat the slash for the top level realm, metaAlias=/sp.

affiliationID

(Optional) Use this parameter to specify a SAML affiliation identifier.

AllowCreate

(Optional) Use this parameter to indicate whether the identity provider can create a new identifier for the principal if none exists (true) or not (false).

AssertionConsumerServiceIndex

(Optional) Use this parameter to specify an integer that indicates the location to which the Response message should be returned to the requester.

AuthComparison

(Optional) Use this parameter to specify a comparison method to evaluate the requested context classes or statements. OpenAM accepts the following values: better, exact, maximum, and minimum.

AuthnContextClassRef

(Optional) Use this parameter to specify authentication context class references. Separate multiple values with pipe characters (|).

AuthnContextDeclRef

(Optional) Use this parameter to specify authentication context declaration references. Separate multiple values with pipe characters (|).

AuthLevel

(Optional) Use this parameter to specify the authentication level of the authentication context that OpenAM should use to authenticate the user.

binding

(Optional) Use this parameter to indicate what binding to use for the operation. For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. In addition to binding=HTTP-POST, you can also use binding=HTTP-Artifact.

Destination

(Optional) Use this parameter to specify a URI Reference indicating the address to which the request is sent.

ForceAuthn

(Optional) Use this parameter to indicate whether the identity provider should force authentication (true) or can reuse existing security contexts (false).

isPassive

(Optional) Use this parameter to indicate whether the identity provider should authenticate passively (true) or not (false).

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier such as urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, or urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL encode the value. For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

RelayStateAlias

(Optional) Use this parameter to specify the parameter to use as the RelayState. For example, if your query string has target=http%3A%2F%2Fforgerock.com&RelayStateAlias=target, this is like setting RelayState=http%3A%2F%2Fforgerock.com.

reqBinding

(Optional) Use this parameter to indicate what binding to use for the authentication request. Valid values in include urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect (default) and urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

sunamcompositeadvice

(Optional) Use this parameter to specify a URL encoded XML blob that specifies the authentication level advice. For example, the following XML indicates a requested authentication level of 1. Notice the required : before the 1.

<Advice>
 <AttributeValuePair>
  <Attribute name="AuthLevelConditionAdvice"/>
  <Value>/:1</Value>
 </AttributeValuePair>
</Advice>
idpSingleLogoutInit.jsp Parameters
binding

(Required) Use this parameter to indicate what binding to use for the operation. The full, long name format is required for this parameter to work.

The value must be one of the following.

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

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

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

Consent

(Optional) Use this parameter to specify a URI that is a SAML Consent Identifier.

Destination

(Optional) Use this parameter to specify a URI Reference indicating the address to which the request is sent.

Extension

(Optional) Use this parameter to specify a list of Extensions as string objects.

goto

(Optional) Use this parameter to specify where to redirect the user when the process is complete. RelayState takes precedence over this parameter.

logoutAll

(Optional) Use this parameter to specify that the identity provider should send single logout requests to service providers without indicating a session index.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL encode the value. For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

spSingleLogoutInit.jsp Parameters
binding

(Required) Use this parameter to indicate what binding to use for the operation. The full, long name format is required for this parameter to work. For example, specify binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST to use HTTP POST binding with a self-submitting form rather than the default HTTP redirect binding. In addition, you can use binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact.

idpEntityID

(Required for Fedlets) Use this parameter to indicate the remote identity provider. If the binding is not set, then OpenAM uses this parameter to find the default binding. Make sure you URL encode the value. For example, specify idpEntityID=http://www.sp.example:8080/openam as idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam.

NameIDValue

(Required for Fedlets) Use this parameter to indicate the SAML Name Identifier for the user.

SessionIndex

(Required for Fedlets) Use this parameter to indicate the sessionIndex of the user session to terminate.

Consent

(Optional) Use this parameter to specify a URI that is a SAML Consent Identifier.

Destination

(Optional) Use this parameter to specify a URI Reference indicating the address to which the request is sent.

Extension

(Optional) Use this parameter to specify a list of Extensions as string objects.

goto

(Optional) Use this parameter to specify where to redirect the user when the process is complete. RelayState takes precedence over this parameter.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL encode the value. For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

spEntityID

(Optional, for Fedlets) Use this parameter to indicate the Fedlet entity ID. When missing, OpenAM uses the first entity ID in the metadata.

Example 11.1. SSO & SLO From the Service Provider

The following URL takes the user from the service provider side to authenticate at the identity provider and then come back to the end user profile page at the service provider after successful SSO. Lines are folded to show you the query string parameters.

http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp
&idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
&RelayState=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam%2Fidm%2FEndUser

The following URL initiates SLO from the service provider side, leaving the user at http://forgerock.com.

http://www.sp.example:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?
&idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
&RelayState=http%3A%2F%2Fforgerock.com

Procedure 11.12. To Indicate Progress During SSO

During SSO log in, OpenAM presents users with a self-submitting form when access has been validated. This page is otherwise blank. If you want to present users with something to indicate that the operation is in progress, then customize the necessary templates.

  1. Modify the templates to add a clue that SSO is in progress, such as an image.

    Edit the source of the OpenAM Java Server Page, saml2/jsp/autosubmitaccessrights.jsp, under the file system directory where the OpenAM .war has been unpacked.

    When you add an image or other presentation element, make sure that you retain the form and Java code as is.

  2. Unpack OpenAM-12.0.0-SNAPSHOT.war, and add your modified template files under WEB-INF/classes/ where you unpacked the .war.

    Also include any images you reference in the page.

  3. Pack up your custom version of OpenAM, and then deploy it in your web container.

11.10. Configuring OpenAM For the ECP Profile

The SAML 2.0 Enhanced Client or Proxy (ECP) profile is intended for use when accessing services over devices like simple phones, medical devices, and set-top boxes that lack the capabilities needed to use the more widely used SAML 2.0 Web Browser SSO profile.

The ECP knows which identity provider to contact for the user, and is able to use the reverse SOAP (PAOS) SAML 2.0 binding for the authentication request and response. The PAOS binding uses HTTP and SOAP headers to pass information about processing SOAP requests and responses, starting with a PAOS HTTP header that the ECP sends in its initial request to the server. The PAOS messages continue with a SOAP authentication request in the server's HTTP response to the ECP's request for a resource, followed by a SOAP response in an HTTP request from the ECP.

An enhanced client, such as a browser with a plugin or an extension, can handle these communications on its own. An enhanced proxy is an HTTP server such as a WAP gateway that can support the ECP profile on behalf of client applications.

OpenAM supports the SAML 2.0 ECP profile on the server side for identity providers and service providers. You must build the ECP.

By default an OpenAM identity provider uses the com.sun.identity.saml2.plugins.DefaultIDPECPSessionMapper class to find a user session for requests to the IDP from the ECP. The default session mapper uses OpenAM cookies as it would for any other client application. If for some reason you must change the mapping after writing and installing your own session mapper, you can change the class under Federation > Entity Providers > idp-name > IDP > Advanced > ECP Configuration.

By default an OpenAM service provider uses the com.sun.identity.saml2.plugins.ECPIDPFinder class to return identity providers from the list under Federation > Entity Providers > sp-name > SP > Advanced > ECP Configuration > Request IDP List. You must populate the list with identity provider entity IDs.

The endpoint for the ECP to contact on the OpenAM service provider is /SPECP as in http://www.sp.example:8080/openam/SPECP. The ECP provides two query string parameters to identify the service provider and to specify the URL of the resource to access.

metaAlias

This specifies the service provider, by default metaAlias=/realm-name/sp, as described in MetaAlias.

RelayState

This specifies the resource the client aims to access such as RelayState=http%3A%2F%2Fforgerock.org%2Findex.html.

For example, the URL to access the service provider and finally the resource at http://forgerock.org/index.html could be http://www.sp.example:8080/openam/SPECP?metaAlias=/sp&RelayState=http%3A%2F%2Fforgerock.org%2Findex.html.

11.11. Managing Federated Accounts

Identity providers and service providers must be able to communicate about users. Yet in some cases the identity provider can choose to communicate a minimum of information about an authenticated user, with no user account maintained on the service provider side. In other cases the identity provider and service provider can choose to link user accounts in a persistent way, in a more permanent way, or even in automatic fashion by using some shared value in the user's profiles such as an email address or by dynamically creating accounts on the service provider when necessary. OpenAM supports all these alternatives.

11.11.1. Using Transient Federation Identifiers

OpenAM allows you to link accounts using transient name identifiers, where the identity provider shares a temporary identifier with the service provider for the duration of the user session. Nothing is written to the user profile.

Transient identifiers are useful where the service is anonymous, and all users have similar access on the service provider side.

To use transient name identifiers, specify the name ID format urn:oasis:names:tc:SAML:2.0:nameid-format:transient when initiating single sign on.

The examples below work in an environment where the identity provider is www.idp.example and the service provider is www.sp.example. Both providers have deployed OpenAM on port 8080 under deployment URI /openam.

To initiate single sign on from the service provider, access the following URL with at least the query parameters shown.

http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?
 idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
 &metaAlias=/sp
 &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient

For a complete list of query parameters, see spSSOInit.jsp Parameters.

To initiate single sign on from the identity provider, access the following URL with at least the query parameters shown.

http://www.idp.example:8080/openam/saml2/jsp/idpSSOInit.jsp?
 spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam
 &metaAlias=/idp
 &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient

For a complete list of query parameters, see idpSSOInit.jsp Parameters.

The accounts are only linked for the duration of the session. Once the user logs out for example the accounts are no longer linked.

11.11.2. Using Persistent Federation Identifiers

OpenAM lets you use persistent pseudonym identifiers to federate user identities, linking accounts on the identity provider and service provider with a SAML persistent identifier.

Persistent identifiers are useful for establishing links between otherwise unrelated accounts.

The examples below work in an environment where the identity provider is www.idp.example and the service provider is www.sp.example. Both providers have deployed OpenAM on port 8080 under deployment URI /openam.

To initiate single sign on from the service provider, access the following URL with at least the query parameters shown.

http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?
 idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
 &metaAlias=/sp
 &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

For a complete list of query parameters, see spSSOInit.jsp Parameters.

To initiate single sign on from the identity provider, access the following URL with at least the query parameters shown.

http://www.idp.example:8080/openam/saml2/jsp/idpSSOInit.jsp?
 spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam
 &metaAlias=/idp
 &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

For a complete list of query parameters, see idpSSOInit.jsp Parameters.

On successful login, the accounts are persistently linked, with persistent identifiers stored in the user's accounts on the identity provider and the service provider.

11.11.3. Changing Federation of Persistently Linked Accounts

OpenAM implements the SAML 2.0 Name Identifier Management profile, allowing you to change a persistent identifier that has been set to federate accounts, and also to terminate federation for an account.

When user accounts are stored in an LDAP directory server, name identifier information is stored on the sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey attributes of a user's entry.[8] You can retrieve the name identifier value by checking the value of sun-fm-saml2-nameid-infokey.

For example, if the user's entry in the directory shows sun-fm-saml2-nameid-infokey: http://www.idp.example:8080/openam|http://www.sp.example:8080/openam| XyfFEsr6Vixbnt0BSqIglLFMGjR2, then the name identifier is XyfFEsr6Vixbnt0BSqIglLFMGjR2.

You can use this identifier to initiate a change request from the service provider as in the following example.

http://www.sp.example:8080/openam/saml2/jsp/spMNIRequestInit.jsp?
 idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
 &metaAlias=/sp
 &requestType=NewID
 &IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2

If desired, you can substitute openam/SPMniInit for openam/saml2/jsp/spMNIRequestInit.jsp

You can also initiate the change request from the identity provider as in the following example.

http://www.idp.example:8080/openam/saml2/jsp/idpMNIRequestInit.jsp?
 spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam
 &metaAlias=/idp
 &requestType=NewID
 &SPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2

If desired, you can substitute openam/IDPMniInit for openam/saml2/jsp/idpMNIRequestInit.jsp

idpMNIRequestInit.jsp Parameters
spEntityID

(Required) Use this parameter to indicate the remote service provider. Make sure you URL encode the value. For example, specify spEntityID=http://www.sp.example:8080/openam as spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam.

metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as metaAlias=/myRealm/idp. This parameter takes the format /realm-name/provider-name as described in MetaAlias. You do not repeat the slash for the top level realm, for example metaAlias=/idp.

requestType

(Required) Type of manage name ID request, either NewID to change the ID, or Terminate to remove the information that links the accounts on the identity provider and service provider.

SPProvidedID

(Required if requestType=NewID) Name identifier in use as described above.

affiliationID

(Optional) Use this parameter to specify a SAML affiliation identifier.

binding

(Optional) Use this parameter to indicate what binding to use for the operation. The full, long name format is required for this parameter to work.

The value must be one of the following.

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

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

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

relayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL encode the value. For example, relayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

spMNIRequestInit.jsp Parameters
idpEntityID

(Required) Use this parameter to indicate the remote identity provider. Make sure you URL encode the value. For example, specify idpEntityID=http://www.idp.example:8080/openam as idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam.

metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as metaAlias=/myRealm/sp. This parameter takes the format /realm-name/provider-name as described in MetaAlias. You do not repeat the slash for the top level realm, metaAlias=/sp.

requestType

(Required) Type of manage name ID request, either NewID to change the ID, or Terminate to remove the information that links the accounts on the identity provider and service provider.

IDPProvidedID

(Required if requestType=NewID) Name identifier in use as described above.

affiliationID

(Optional) Use this parameter to specify a SAML affiliation identifier.

binding

(Optional) Use this parameter to indicate what binding to use for the operation. The full, long name format is required for this parameter to work.

The value must be one of the following.

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

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

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

relayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL encode the value. For example, relayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

You can terminate federation as described in Section 11.11.4, “Terminating Federation of Persistently Linked Accounts”.

11.11.4. Terminating Federation of Persistently Linked Accounts

OpenAM lets you terminate account federation, where the accounts have been linked with a persistent identifier as described in Section 11.11.2, “Using Persistent Federation Identifiers”.

The examples below work in an environment where the identity provider is www.idp.example and the service provider is www.sp.example. Both providers have deployed OpenAM on port 8080 under deployment URI /openam.

To initiate the process of terminating account federation from the service provider, access the following URL with at least the query parameters shown.

http://www.sp.example:8080/openam/saml2/jsp/spMNIRequestInit.jsp?
 idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
 &metaAlias=/sp
 &requestType=Terminate

To initiate the process of terminating account federation from the identity provider, access the following URL with at least the query parameters shown.

http://www.idp.example:8080/openam/saml2/jsp/idpMNIRequestInit.jsp?
 spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam
 &metaAlias=/idp
 &requestType=Terminate

11.11.5. Configuring How Remote Accounts Map To Local Accounts

OpenAM lets you configure the service provider to link an account based on an attribute value from the identity provider. When you know the user accounts on both the identity provider and the service provider share a common attribute value, such as an email address or other unique user identifier, you can use this method to link accounts without user interaction. See Procedure 11.13, “To Map Accounts Based on an Attribute Value”.

OpenAM also lets you map users on the identity provider temporarily to a single anonymous user account on the service provider, in order to exchange attributes about the user without a user-specific account on the service provider. This approach can be useful when the service provider either needs no user-specific account to provide a service, or when you do not want to retain a user profile on the service provider but instead you make authorization decisions based on attribute values from the identity provider. See Procedure 11.14, “To Map Remote Accounts to a Single Service Provider Account”.

OpenAM further allows you to use attributes from the identity provider to create accounts dynamically on the service provider. When using this method, you should inform the user and obtain consent to create the account if necessary. See Procedure 11.15, “To Map Accounts With Dynamic Service Provider Account Creation”.

Procedure 11.13. To Map Accounts Based on an Attribute Value

The following steps demonstrate how to map accounts based on an attribute value that is the same in both accounts.

Perform the following steps on the hosted identity provider(s), and again on the hosted service provider(s).

  1. Login to the OpenAM console as administrator.

  2. Browse to Federation > hosted-provider-name > Assertion Processing.

  3. If the attribute to use when linking accounts is not yet included in the attribute map, add the attribute mapping, and then Save your work.

  4. On the hosted service provider, under Auto Federation, select Enabled and enter the local attribute name in the Attribute field, and then Save your work.

Procedure 11.14. To Map Remote Accounts to a Single Service Provider Account

The following steps demonstrate how to auto-federate using a single anonymous user account on the service provider.

Perform the following steps on the hosted identity provider(s), and again on the hosted service provider(s).

  1. Login to the OpenAM console as administrator.

  2. Browse to Federation > hosted-provider-name > Assertion Processing.

  3. If you want to get attributes from the identity provider and the attributes are not yet in the attribute map, add the attribute mappings, and then Save your work.

  4. On the hosted service provider, under Transient User, set the single account to which to map all users, such as anonymous, and then Save your work.

  5. After completing configuration on the providers, use transient identifiers to federate as described in Section 11.11.1, “Using Transient Federation Identifiers”.

Procedure 11.15. To Map Accounts With Dynamic Service Provider Account Creation

The following steps demonstrate how to map accounts with dynamic creation of missing accounts on the service provider side.

  1. Set up a mapping based on an attribute value as described in Procedure 11.13, “To Map Accounts Based on an Attribute Value”. The attributes you map from the identity provider are those that the service provider sets on the dynamically created accounts.

  2. On the service provider console, browse to Access Control > realm-name > Authentication > All Core Settings..., and Dynamic or Dynamic with User Alias, which are described in Hints For the Core Authentication Module, and then Save your work.

  3. To test your work, create a user on the identity provider, log out of the console, and initiate SSO logging in as the user you created.

    To initiate SSO, browse to one of the OpenAM SAML 2.0 JSPs with the appropriate query parameters. The following is an example URL for service provider initiated SSO.

    http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?
     idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
     &metaAlias=/sp

    On success, check http://www.sp.example:8080/openam/idm/EndUser to see the new user account.

11.11.6. Linking Federated Accounts in Bulk

If you manage both the identity provider and service provider, you can link accounts out-of-band, in bulk. You make permanent connections for a list of identity provider and service provider by using the ssoadm bulk federation commands.

Before you can run the bulk federation commands, first establish the relationship between accounts, set up the providers as described in Section 11.2, “Setting Up SAML 2.0 SSO”, and install the ssoadm command as described in To Set Up Administration Tools.

To understand the relationships between accounts, consider an example where the identity provider is at idp.example.org and the service provider is at sp.example.com. A demo user account has the Universal ID, id=demo,ou=user,dc=example,dc=org, on the identity provider. That maps to the Universal ID, id=demo,ou=user,dc=example,dc=com, on the service provider.

The ssoadm command then needs a file that maps local user IDs to remote user IDs, one per line, separated by the vertical bar character |. Each line of the file appears as follows.

local-user-ID|remote-user-ID

In the example, starting on the service provider side, the line for the demo user reads as follows.

id=demo,ou=user,dc=example,dc=com|id=demo,ou=user,dc=example,dc=org

All the users’ accounts mapped in your file must exist at the identity provider and the service provider when you run the commands to link them.

Link the accounts using the ssoadm bulk federation commands.

  1. Prepare the data with the ssoadm do-bulk-federation command.

    The following example starts on the service provider side.

    $ cat /tmp/user-map.txt
    id=demo,ou=user,dc=example,dc=com|id=demo,ou=user,dc=example,dc=org
    $ ssoadm  \
     do-bulk-federation \
     --metaalias /sp \
     --remoteentityid http://idp.example.org:8080/openam \
     --useridmapping /tmp/user-map.txt \
     --nameidmapping /tmp/name-map.txt \
     --adminid amadmin  \
     --password-file /tmp/pwd.txt \
     --spec saml2
    
    Bulk Federation for this host was completed. To complete the
    federation, name Id mapping file should be loaded to remote
    provider.
         
  2. Copy the name ID mapping output file to the other provider.

    $ scp /tmp/name-map.txt openam@idp.example.org:/tmp/name-map.txt
    openam@idp.example.org's password:
    name-map.txt                     100%  177     0.2KB/s   00:00
         
  3. Import the name ID mapping file with the ssoadm import-bulk-fed-data command.

    The following example is performed on the identity provider side.

    $ ssoadm \
     import-bulk-fed-data \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --metaalias /idp \
     --bulk-data-file /tmp/name-map.txt
    
    Bulk Federation for this host was completed.
         

At this point the accounts are linked.

11.11.7. Authentication & Linked Accounts

In a SAML 2.0 federation where accounts are durably linked, authentication is required only on the identity provider side.

Authentication is also required however on the service provider side when the OpenAM account mapper on the service provider is not able to map the user identified in the SAML assertion from the identity provider to a local user account.

This can happen for example the first time accounts are linked as described in Section 11.11.2, “Using Persistent Federation Identifiers”, after which the persistent identifier establishes the mapping.

This also happens when transient identifiers are used to map accounts. When accounts are linked as described in Section 11.11.1, “Using Transient Federation Identifiers”, then the service provider must locally authenticate the user for every SAML assertion received. This is because the identifier used to link the accounts is transient: it does not provide a durable means to link the accounts.

11.12. Using SAML 2.0 Artifacts

By default OpenAM transmits SAML messages by value. This makes it possible to access the SAML messages in the user agent. You can instead request that OpenAM transmit SAML messages by reference using SAML artifacts, which are small values that reference a SAML message. Providers then communicate directly to resolve artifacts, rather than sending the messages through the user agent.

When initiating single sign-on using idpSSOInit.jsp or spSSOInit.jsp for example, add binding=HTTP-Artifact to the list of query parameters. The following example works in an environment where the identity provider is www.idp.example and the service provider is www.sp.example. Both providers have deployed OpenAM on port 8080 under deployment URI /openam.

http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?
   idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
   &metaAlias=/sp
   &binding=HTTP-Artifact

11.13. SAML 2.0 & Policy Agents

You can use policy agents in a SAML 2.0 Federation deployment.

Procedure 11.16. To Use a Policy Agent with a SAML 2.0 Service Provider

The following procedure applies when OpenAM is configured as an IDP in one domain, and the desired policy agent protects resources on behalf of a second OpenAM server configured as an SP on a second domain.

  1. Install the policy agent.

    The basic process for installing policy agents is available in the Web Policy Agent Installation Guide and the Java EE Policy Agent User's Guide.

  2. Replace the given OpenAM Login URL and OpenAM Logout URLs with SAML 2.0 URLs described in Section 11.9, “Using SAML 2.0 Single Sign-On & Single Logout”.

    The following steps explain how to do this for web policy agents.

    • If you have configured the Web policy agents to store their properties centralized on an OpenAM server, navigate to the URL for the OpenAM console. Select Access Control > Realm Name > Agents > Web > Agent Name > OpenAM Services.

      For the Web Agent, under the OpenAM Services tab, in the Agent Logout URL section, set up a list of application logout URLs. In the Logout Redirect URL text box, enter an appropriate URL to redirect the user after logout.

    • Alternatively, if the Web policy agents are set up to store properties on local systems, find the OpenSSOAgentConfiguration.properties file in the /path/to/agent/config/ directory.

      You can specify OpenAM Login and Logout URLs with the com.sun.identity.agents.config.login.url and com.sun.identity.agents.config.logout.url attributes, respectively.



[8] These attribute types are configurable in the OpenAM console under Configuration > Global > SAMLv2 Service Configuration.