Chapter 12. Managing SAML 2.0 Federation
Prev		Next

Chapter 12. Managing SAML 2.0 Federation

Table of Contents

12.1. About SAML 2.0 SSO & Federation
12.2. Setting Up SAML 2.0 SSO
12.3. Configuring Identity Providers
12.4. Configuring Service Providers
12.5. Configuring Circles of Trust
12.6. Configuring Google Apps as a Remote Service Provider
12.7. Configuring Salesforce CRM as a Remote Service Provider
12.8. Using SAML 2.0 Single Sign-On & Single Logout
12.9. Configuring OpenAM For the ECP Profile
12.10. Managing Federated Accounts
12.11. Using SAML 2.0 Artifacts

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

12.2.1. Deploying the Identity Provider Discovery Service

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

On the OpenAM console Common Tasks page, click Create Hosted Identity Provider.
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.
Select the Signing Key you imported into the OpenAM key store.
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.
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.
Click Configure to save your configuration.
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

On the OpenAM console Common Tasks page, click Create Hosted Service Provider.
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.
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.
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).
Click Configure to save your configuration.
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

Obtain the identity provider metadata, or the URL where you can obtain it.
On the OpenAM console Common Tasks page, click Register Remote Identity Provider.
Provide the identity provider metadata or link to obtain metadata.
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.
Click Configure to save your configuration.

Procedure 12.4. To Create a Remote Service Provider

Obtain the service provider metadata, or the URL where you can obtain it.
On the OpenAM console Common Tasks page, click Register Remote Service Provider.
Provide the identity provider metadata or link to obtain metadata.
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).
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.
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.

If you have not done so already, set up your identity provider.
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.
For the attributes you share, map service provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).
Click Create to generate the Fedlet.zip file under the OpenAM configuration directory, such as $HOME/openam/myfedlets/httpwwwexamplecom80myapp/Fedlet.zip.
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.

Deploy the .war file into your web application container.
Configure the discovery service.
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.
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.

Copy the file to the webapps/ directory.

$ cp ~/Downloads/openam/ /path/to/tomcat/webapps/disco.war

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

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

On the service provider console, login as OpenAM Administrator.
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.
On each identity provider console, login as OpenAM Administrator.
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.

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.

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.

For each identity provider extended metadata file, change the value of the hosted attribute to 0, meaning the identity provider is remote.

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.

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

12.3.1. Hints for Assertion Content
12.3.2. Hints for Assertion Processing
12.3.3. Hints for Services
12.3.4. Hints for Advanced Settings

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

12.4.1. Hints for Assertion Content
12.4.2. Hints for Assertion Processing
12.4.3. Hints for Services
12.4.4. Hints for Advanced Settings

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

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.
On the OpenAM console Common Tasks page, click Configure Google Apps.
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.
On the second Configure Google Apps for Single Sign-On page, save the OpenAM verification certificate to a text file, such as OpenAM.pem.
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

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.
On the OpenAM console Common Tasks page, click Configure Salesforce CRM.
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.
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.
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.
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

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.

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

12.10.1. Using Transient Federation Identifiers
12.10.2. Using Persistent Federation Identifiers
12.10.3. Changing Federation of Persistently Linked Accounts
12.10.4. Terminating Federation of Persistently Linked Accounts
12.10.5. Configuring Auto-Federation
12.10.6. Linking Federated Accounts in Bulk

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.

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

metaAlias

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

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

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

Login to the OpenAM console as administrator.
Browse to Federation > hosted-provider-name > Assertion Processing.
If the attribute to use for auto-federation is not yet in the attribute map, add the attribute mapping, and then Save your work.
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).

Login to the OpenAM console as administrator.
Browse to Federation > hosted-provider-name > Assertion Processing.
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.
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.
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.

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

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.

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

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