Chapter 12. Managing SAML 2.0 Federation
Prev |  | Next

# Chapter 12. Managing SAML 2.0 Federation

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.

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

## 12.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.

This section covers the following topics.

- Procedure 12.1, “To Create a Hosted Identity Provider”

- Procedure 12.2, “To Create a Hosted Service Provider”

- Procedure 12.3, “To Create a Remote Identity Provider”

- Procedure 12.4, “To Create a Remote Service Provider”

- Procedure 12.5, “To Create a Fedlet for Service Providers”

- Section 12.2.1, “Deploying the Identity Provider Discovery Service”

Procedure 12.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.

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 -o 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 12.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 -o 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 12.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 12.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 12.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 12.1. Fedlet Support for SAML 2.0 Features

SAML 2.0 Feature | Java Fedlet | .NET Fedlet
--- | --- | ---
IDP & SP-initiated Single Sign-On (HTTP Artifact) | Supported | Supported
IDP & SP-initiated Single Sign-On (HTTP POST) | Supported | Supported
IDP & SP-initiated Single Logout (HTTP POST) | Supported | Supported
IDP & SP-initiated Single Logout (HTTP Redirect) | Supported | Supported
Sign Requests & Responses | Supported | Supported
Encrypt Assertion, Attribute, & NameID Elements | Supported | Supported
Export SP Metadata | Supported | Supported
Attribute Queries | Supported | Supported
XACML Requests | Supported | Not supported
Multiple IDPs | Supported | Supported
External IDP Discovery Service | Supported | Supported
Bundled IDP Reader Service for Discovery | Supported | Not 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.

### 12.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 12.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 `` file to the `webapps/` directory.

       $ cp ~/Downloads/openam/ /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 12.7. To Configure the Discovery Service

1. Configure the identity provider discovery service.

   [D]

   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 12.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 12.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 -y "http://www.this-idp.example:8080/openam"
        -u amadmin -f /tmp/pwd.txt -i /idp -m this-standard.xml -x 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 -y "http://www.that-idp.example:8080/openam"
        -u amadmin -f /tmp/pwd.txt -i /idp -m that-standard.xml -x 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 -t discocot -m ~/Downloads/this-standard.xml
        -x ~/Downloads/this-extended.xml -u amadmin -f /tmp/pwd.txt

       Import file, /Users/mark/Downloads/this-standard.xml.
       Import file, /Users/mark/Downloads/this-extended.xml.
       $ ./ssoadm import-entity -t discocot -m ~/Downloads/that-standard.xml
        -x ~/Downloads/that-extended.xml -u amadmin -f /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

## 12.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`.

### 12.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.

### 12.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.

### 12.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.

### 12.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.

## 12.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`.

### 12.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.

### 12.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.

### 12.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.

### 12.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.

## 12.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.

## 12.6. 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 12.10. To Integrate With Google Apps

1. If you have not yet done so, set up OpenAM as described in Procedure 12.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.

## 12.7. 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 12.11. To Integrate With Salesforce CRM

1. If you have not yet done so, set up OpenAM as described in Procedure 12.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. Leave the NameID Format field empty.

   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.

## 12.8. 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 12.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 12.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 templates found in OpenAM sources, `saml2login.template` and `saml2loginwithrelay.template`.

   When you add an image or other presentation element, make sure that you retain the form and JavaScript as is. Also, as the files are templates, what you add must be static HTML.

2. Unpack , 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.

## 12.9. 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`.

## 12.10. 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.

### 12.10.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.

### 12.10.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.

### 12.10.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.[7] 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 12.10.4, “Terminating Federation of Persistently Linked Accounts”.

### 12.10.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 12.10.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

### 12.10.5. Configuring Auto-Federation

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 12.13, “To Auto-Federate 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 12.14, “To Auto-Federate Using 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 12.15, “To Auto-Federate With Dynamic Service Provider Account Creation”.

Procedure 12.13. To Auto-Federate Accounts Based on an Attribute Value

The following steps demonstrate how to auto-federate 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 for auto-federation is not yet 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 12.14. To Auto-Federate Using 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 is not yet in the attribute map, add the attribute mapping, 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 12.10.1, “Using Transient Federation Identifiers”.

Procedure 12.15. To Auto-Federate With Dynamic Service Provider Account Creation

The following steps demonstrate how to auto-federate, dynamically creating an account on the service provider if necessary.

1. Set up auto-federation as described in Procedure 12.13, “To Auto-Federate 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.

### 12.10.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 12.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.

## 12.11. 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

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

Prev |  | Next
Chapter 11. Configuring the Dashboard Service | Home | Chapter 13. Managing OAuth 2.0 Authorization