Identity Cloud

SAML v2.0

This guide covers concepts, configuration, and usage procedures for working with the Security Assertion Markup Language (SAML) v2.0 features provided by ForgeRock Access Management.

This guide is written for anyone using Access Management for SAML v2.0 identity and service providers.

ForgeRockĀ® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Introduction to SAML v2.0

SAML v2.0 helps organizations share, or federate identities and services, without having to manage the identities or credentials themselves. The credentials are managed by a single entity, known as the identity provider. The services are provided by service providers. Both providers are configured to trust one another.

A high-level overview of the SAML v2.0 participants in AM.
Figure 1. Overview of SAML v2.0 in AM

AM uses the concept of the circle of trust to manage the relationship between IDPs and SPs.

SAML v2.0 concepts

Security Assertion Markup Language (SAML) v2.0 is a standard that enables users to access multiple services using only a single set of credentials. The services may be provided by different organizations, using multiple domains. In summary, SAML v2.0 provides cross-domain single sign-on (CDSSO).

Table 1. SAML v2.0 Terminology
Term Description

End user

The person who is attempting to access the resource or application. In SAML v2.0, the end user is often referred to as the subject.

The end user uses a user-agent, usually a web-browser, when performing a SAML v2.0 flow.

Single sign-on (SSO)

The ability for an end user to authenticate once but gain access to multiple applications, without having to authenticate separately to each one.

Single log out (SLO)

The ability for an end user to log out once but terminate sessions in multiple applications, without having to log out separately from each one.

Assertions

An assertion is a set of statements about an authenticated user that let services make authorization decisions, that is; whether to allow that user to access the service, and what functionality they can use.

SAML assertions are XML-formatted tokens. Assertions issued by AM can contain the following information about an end user:

  1. Their attributes, such as pieces of information from the user’s profile.

  2. The level of authentication they have performed.

Identity provider (IDP)

The identity provider is responsible for authenticating end users, managing their account, and issuing SAML assertions about them.

Service provider (SP)

The provider of the service or application that the end user is trying to access.

The service provider has a trust relationship with the identity provider, which enables the SP to rely on the assertions it receives from the IDP.

Circle of trust (CoT)

A circle of trust is an AM concept that groups at least one identity provider and at least one service provider who agree to share authentication information.

Metadata

Providers in SAML v2.0 share metadata, which represents the configuration of the provider, as well as the mechanisms it can use to communicate with other providers.

For example, the metadata may contain necessary certificates for signing verification, as well as which of the SAML v2.0 bindings are supported.

Sharing metadata greatly simplifies the creation of SAML v2.0 providers in a circle of trust. AM can import the XML-formatted metadata provided by other providers, which are referred to as remote providers. You can also export the metadata from providers created in an AM instance, referred to as hosted providers.

For more information about metadata, see Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.

When configuring AM to provide single sign-on using SAML v2.0, you can map accounts at the identity provider to accounts at the service provider, including mapping to an anonymous user.

The identity provider can then make assertions to the service provider, for example, to attest that the end 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.

SAML v2.0 example flow
SAML v2.0 Flow
Figure 2. SAML v2.0 Flow
  1. An unauthenticated user attempts to access a SAML v2.0 service provider.

  2. The service provider determines the identity provider associated with the end user, and redirects the user’s browser to the IDP, using an HTTP 302 Redirect message. A SAML v2.0 authentication request is included in the query string.

    This is an example of HTTP-Redirect binding, and is the default when requesting SAML authentication by AM. AM also supports the HTTP-POST binding for processing SAML v2.0 authentication requests.

    AM provides two deployment models to support single sign-on (SSO) when contacting the SP initially. For details, see Implement SSO and SLO.

  3. The identity provider validates the request, determines the authentication method that should be used, and authenticates the user.

    The SP may include certain requirements for the authentication it requires the user to perform in the authentication request, for example a requirement to use multiple factors.

  4. The IDP creates a SAML Artifact, which contains a unique artifact ID for the SAML v2.0 response.

    The IDP redirects the end user’s browser to the SP, and includes the SAML Artifact in the query parameters. Note that the browser only has access to the artifact ID rather than the SAML response itself, reducing risk of malicious interference.

  5. The SP communicates directly with the IDP, using the SOAP protocol, to retrieve the SAML response relating to the artifact ID.

    The IDP returns the SAML response, including the assertion, using the SOAP protocol, directly to the SP.

    The information in the SAML response is not shared with the user agent. This is an example of HTTP-Artifact binding, and is the default when AM is returning SAML assertions. AM also supports the HTTP-POST binding for transmitting SAML v2.0 assertions.

  6. The SP validates the SAML response, and that the signature matches the public key it holds for the IDP.

    Optionally, the SP can choose to create a new account locally for the user, or associate an identifier in the assertion with a user account it already has locally. Linked accounts are often referred to as a federated identity. See Federate identities.

    In order to link to an existing account, the SP may require the end user to also authenticate to the SP to determine the matching local account. Once linked, the user will only need to authenticate at the IDP when attempting access.

  7. The SP can now use the information provided in the assertion, and any details in the local federated identity, to authorize the user, and decide whether to provide its services to the end user.

SAML v2.0 requires interoperability, and depends on standards for describing how the providers interact and exchange information. The SAML v2.0 standards describe the messages sent between providers, how they are relayed, how they are exchanged, and common use cases.

Use case: Let staff access Google G Suite

A common use case for SAML v2.0 is to let your internal staff access and use the applications provided by Google G Suite, such as Google Docs and Google Sheets. This section highlights how AM provides the solution.

In this scenario, Google acts as the service provider, and AM acts as the identity provider for a hypothetical organization, Example.com.

High-level steps to let staff access G Suite applications
  1. In AM, an administrative user configures an AM instance as the IDP.

  2. The administrative user then configures Google G Suite as a remote SP, and provides the values that Google requires to use AM as its IDP. For example: the log in and log out URL, profile management URLs, and validation certificate.

  3. The G Suite administrator enters the provided URLs and certificate into the G Suite Admin console for the domain being configured.

  4. After configuration is complete, users attempting to access a G Suite service will be asked for their corporate email address:

    Provide Google with your corporate email address, so the relevant IDP can be determined.
  5. Based on the domain of the email address, Google redirects the user to sign in to AM, acting as the IDP:

    Log in to your corporate account at Example.com, with AM acting as the IDP.
  6. After successfully authenticating with AM the user is redirected back to the G Suite application, for example Google Docs.

    Google, acting as the SP, creates a federated identity in its systems to manage local account options, such as privacy settings. The user can now access any of the G Suite apps, by authenticating to the IDP using their corporate Example.com account:

    Google Docs showing a federated identity authenticated by AM, the trusted IDP.

Deployment considerations

Before you set up SAML v2.0 in AM, you should:

  • Know which providers will participate in circles of trust.

  • Know how AM installations act as identity providers or service providers.

  • Define how to map shared user attributes in identity information exchanged with other participants in a circle of trust. 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.

  • Agree with other providers on a synchronized time service.

  • Determine whether your session state configuration limits your usage of certain SAML v2.0 profiles. For more information, see Session state considerations.

Session state considerations

SAML v2.0 functionality uses a combination of the CTS and browser-based data to store the progress of SAML v2.0 single sign-on SSO operations.

This combination enables AM instances to continue single sign-on flows that started at a different instance, without the need for sticky load balancing in most scenarios.

Single sign-on progress is stored in a JSON web token (JWT) in the browser’s local storage. The browser must support the localStorage API to handle SSO without the need for sticky load balancing of the AM instances. You must configure sticky load balancing to support SAML v2.0 SSO with clients that do not support local storage, and on IdP proxy implementations.

You can enable local storage support in WebView components on Android by using the following property:

settings.setDomStorageEnabled(true)

You cannot use local storage when using multiple WebView components simultaneously. For more information, see WebSettings - setDomStorageEnabled in the Android Developers documentation.

Performing single log out (SLO) operations when there is more than a single AM instance has the following caveats:

  • AM instances cache information about SLO progress in memory. After the initial request, you must send each subsequent request in an SLO flow to the same instance; for example, by enabling sticky load balancing.

  • Use the HTTP-POST or HTTP-Redirect bindings for SAML v2.0 single logout (SLO). The SOAP binding is not supported.

The following table summarizes the high-level tasks required to configure SAML v2.0:

Task Resources

Configure an SP, an IDP, and a CoT

The first step is deciding if AM is the SP, the IDP, or both, and/or what metadata you need to import from other providers.

For example, if AM is the IDP for another service in your environment, you will have to import the metadata of the remote SP.

Ensure the SPs and IDPs that work together share the same CoT.

Make sure your providers are secure

Configure signing and encryption secrets for your environment.

Configure your environment for SSO and SLO

AM provides two options for implementing SSO and SLO: integrated mode, and standalone mode.

There are several considerations to make before deciding which mode is more appropriate for your environment.

Decide how to federate identities

AM supports different ways to federate identities depending of the configuration, and whether they exist or not in the SP.

Configure IDPs, SPs, and CoTs

This section covers configuration tasks to implement SAML v2.0 in AM.

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

In AM terms, a hosted provider is one served by the current AM instance; a remote provider is one hosted elsewhere.

Create a circle of trust

A circle of trust is an AM concept that groups at least one identity provider and at least one service provider who agree to share authentication information.

  1. Go to Realms > Realm Name > Applications > Federation > Circles of Trust, and click Add Circle of Trust.

  2. Provide a name, and click Create.

  3. On the Circle of Trust page, in the Entity Providers property, select at least one IDP and one SP.

    Note that entity providers can be added at any time, if you have not yet created them.

  4. Customize any other properties as required, and click Save Changes.

    For information about circle of trust properties, see Circle of trust configuration properties.

Create a hosted entity provider

This procedure provides steps for creating a hosted identity or service providers using the AM admin UI.

You can create identity and service provider roles in the AM admin UI.

To create other roles, AM provides the /realm-config/federation/entityproviders/saml2 REST endpoint.

  1. Go to Realms > Realm Name > Dashboard, and then click SAML Applications.

  2. Click Add Entity Provider > Hosted.

  3. Enter an Entity ID, and verify the Entity Provider Base URL value is correct.

    AM uses the Entity Provider Base URL value for all SAML v2.0 related endpoints, so ensure other entities in your SAML deployment are able to access the specified URL.

  4. In the Meta Aliases section, provide a URL-friendly value in either the Identity Provider Meta Alias, the Service Provider Meta Alias property, or both.

    Ensure the aliases for providers are unique in a circle of trust, as well as in the realm.

  5. Click Create.

    How do I switch between SP and IDP configuration for a given provider?

    AM only displays the configuration of a single role. Click on the labels to select the role view:

    saml-roles
  6. On the Assertion Processing tab, in the Attribute Mapper section, map SAML attribute names (Name in Assertion) to local attribute names.

    In this example, we map the SalesForce IDPEmail SAML attribute to the local mail attribute.
    Figure 3. Mapping SAML Attributes to Local Attributes

    The default mapping implementation has additional features beyond simply retrieving string attributes from the user profile.

    • Add an attribute that takes a static value by enclosing the profile attribute name in double quotes (").

      For example, you can add a static SAML attribute called partnerID with a value of staticPartnerIDValue by adding partnerID as the SAML Attribute with "staticPartnerIDValue" as the Local Attribute name.

    • Select the binary option when dealing with binary attribute values; for example, values that are Base64 encoded.

    • Use the optional Name Format Uri property as required by the remote provider. For example, you may need to specify urn:oasis:names:tc:SAML:2.0:attrname-format:uri.

  7. Customize any other properties as required, and click Save Changes.

    For information about hosted entity provider properties, see:

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

    $ curl \
    --output metadata.xml \
    "https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp\
    ?entityid=myHostedProvider\
    &realm=/mySubRealm"

    You may also be able to provide the URL in the above example to remote providers, if they can load the metadata by using a URL rather than a file.

Import and configure a remote entity provider

The following procedure provides steps for importing and configuring one or more remote entity providers:

  1. Obtain the entity provider metadata as an XML-formatted file.

  2. Go to Realms > Realm Name > Dashboard, and click SAML Applications.

  3. Click the Add Entity Provider drop-down button, and click Remote.

  4. On the New Remote Entity Provider page, perform one of the following steps to import the XML file:

    1. Drag and drop the XML file into the dotted box.

    2. Click within the dotted box to open a file browser to select the XML file.

    You can import multiple remote entities in a single operation, as long as the entity ID is unique within each.

  5. If you have already created a circle of trust, you can add the remote providers into one or more of them by using the Circles of Trust property.

  6. Click Create.

  7. After importing meta data, to edit the configuration of an entity provider, go to Realms > Realm Name > Applications > Federation > Entity Providers, and select the entity provider to edit.

    How do I switch between SP and IDP configuration for a given provider?

    AM only displays the configuration of a single role. Click on the labels to select the role view:

    saml-roles

    For information about remote entity provider properties, see:

Sign and encrypt messages

By default, IdPs and SPs do not sign or encrypt SAML v2.0 messages. While this is useful for test and demo environments, you should secure your production and production-like environments.

How does signing work?

When AM needs to sign a SAML request or response for the consumption of a remote entity provider, it will determine the signing algorithm, and optionally, the digest method, based on the following logic, as recommended by the SAML v2.0 Metadata Profile for AlgorithmSupport Version 1.0 specification:

  1. AM retrieves the remote entity provider’s metadata, and examines the role-specific extensions for a configured digest method, or signing algorithm.

  2. If there is no role-specific algorithm configured, AM checks for algorithms configured in the entity provider-level extensions.

  3. If signing algorithms are specified at either role-specific level or entity provider-level, but AM is unable to find a suitable key, it does not sign the element, and displays an error.

    Possible reasons that AM may not be able to locate a suitable signing key include:

    • Algorithm mismatch - the signing algorithm cannot be used with the private key configured in the relevant secret ID.

    • Keysize mismatch - the required key size and actual key size are not equal.

  4. If the entity provider does not specify supported signing and digest methods in the standard metadata, AM falls back to the global default algorithm settings.

  5. If the global default algorithms are not configured, AM examines the configured signing key type, and uses RSA-SHA256 for RSA keys, DSA-SHA256 for DSA keys, and ECDSA-SHA512 for EC keys.

    AM has different default signing algorithm settings for XML signatures, and for query signatures.

    AM determines the correct default query signing algorithm based on the signing key’s algorithm, be it RSA, DSA, or EC. It will only fall back to the same defaults for both XML and query signing algorithms when the settings are not correctly defined.

After determining the required algorithm, the sender uses their own private key to write the signature on the request. Then, the provider receiving the message uses the public key exposed in the sender’s metadata to validate the signature.

How does encryption work?

In summary, when encrypting SAML v2.0 messages, the sender uses the receiver’s public key (exposed in the receiver’s metadata) to encrypt the request. The receiver decrypts it with its private key.

As with signing, providers also expose in their metadata the algorithms that they can use to encrypt assertion content.

Since SAML v2.0 messages are in XML format, encrypting them requires an additional key that will be transported with the message, as explained in the XML Encryption Syntax and Processing Version 1.1 specification. AM refers to those keys as transport keys.

Consider the following example of an encryption/decryption flow:

  1. The IdP generates a random symmetric transport key using the transport key algorithm exposed in the SP’s metadata.

  2. The IdP encrypts the assertion with the transport key.

  3. The IdP encrypts the transport key with the public key of the SP (which is also exposed in its metadata).

  4. The SP decrypts the transport key using its private key. Then, it uses the transport key to decrypt the assertion.

This ensures only this SP can decrypt the message.

See the following procedures to configure signing and encryption in your environment:

Configure the advertised signing and encryption algorithms

  1. Configure the required signing algorithms and digests:

    Hosted IDPs and SPs can advertise the algorithms they can use to sign assertion content. This information appears as part of the provider’s metadata extension.

    Signing/digest algorithm metadata example
    <Extensions>
    <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
    </Extensions>
    • In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

    • On the Assertion Content tab, in the Signing Algorithm drop-down list, select the signing algorithms this provider can use.

      There is no default for this property.

    • On the Assertion Content tab, in the Digest Algorithm drop-down list, select the digest algorithms this provider can use.

      There is no default for this property.

  2. Configure the required encryption algorithms:

    Hosted SPs and IDPs advertise their encryption algorithms so that the remote providers know which ones they should use when sending encrypted data.

    Encryption algorithm metadata example
    <!-- Enable RSA-OAEP key transport with AES-GCM data encryption: -->
    <KeyDescriptor use="encryption">
     <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#rsa-oaep"/>
     <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc11#aes128-gcm"/>
    </KeyDescriptor>
    • In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

    • On the Assertion Content tab, in the Encryption Algorithm drop-down list, select the algorithms this provider can use.

      Select one or more AES algorithms from the list to encrypt assertion content, and one or more asymmetric algorithms to encrypt the transport key.

      For assertion encryption algorithms, ForgeRock recommends AES-GCM over the older AES-CBC modes. GCM offers authenticated encryption, which better protects against an attacker tampering with an encrypted assertion. Also sign assertions to make such attacks harder to exploit.

      Table 2. Assertion Encryption Algorithms
      Algorithm Identifier Recommended

      http://www.w3.org/2009/xmlenc11#aes128-gcm

      http://www.w3.org/2009/xmlenc11#aes192-gcm

      http://www.w3.org/2009/xmlenc11#aes256-gcm

      http://www.w3.org/2001/04/xmlenc#aes128-cbc (default)

      http://www.w3.org/2001/04/xmlenc#aes192-cbc

      http://www.w3.org/2001/04/xmlenc#aes256-cbc

      Table 3. Key Transport Algorithms
      Algorithm Identifier Recommended

      http://www.w3.org/2009/xmlenc11#rsa-oaep(1)

      http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p (default)

      http://www.w3.org/2001/04/xmlenc#rsa-1_5(2)

      (1) When this algorithm is configured, AM will use the Mask Generation Function Algorithm property (Configure > Global Services > Common Federation Configuration) to create the transport key.

      (2) For security reasons, ForgeRock strongly recommends that you do not use this option.

Configure AM to sign and encrypt SAML v2.0 assertion content

Considerations when configuring signing and encryption
Assertions

HTTP-POST bindings require signed assertions.

Failure to enable signing when using HTTP-POST bindings may result in errors such as the following:

ERROR: UtilProxySAMLAuthenticatorLookup.retrieveAuthenticationFromCache: Unable to do sso or federation.
com.sun.identity.saml2.common.SAML2Exception: Provider's signing certificate alias is missing.

Or:

ERROR: SAML2Utils.verifyResponse:Assertion is not signed or signature is not valid.
SAML authentication requests

Signing is recommended to verify the request’s authenticity, and also when using the ForceAuthn flag.

SAML assertion responses

Signing AND encrypting is recommended, since responses can contain user data.

SAML logout requests

Signing is recommended to verify the request’s authenticity.

  1. In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  2. On the Assertion Content tab, in the [.label]# Secret ID Identifier# property, enter a string value to identify the secret IDs this provider will use.

    For example, mySamlSecrets.

    How do secret identifiers work?

    AM uses the secret identifier to know which secret IDs are relevant for a provider. You can reuse the identifier that another provider is already using if you want them to share the same secrets.

    When a provider is removed from the AM configuration, AM automatically removes the secret IDs related to their identifier, unless they are being used by another provider.

    If you do not specify a value for the secret ID identifier, AM will use the global default secrets relative to the entity provider’s role, in the realm. If they are not mapped, AM will search for the global default secrets in the global secret stores.

  3. Save your changes.

    AM creates two new secret IDs, at the realm level, based on the value you specified.

  4. In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  5. On the Assertion Content tab, in the Signing and Encryption section, select the SAML v2.0 elements that AM should sign, and the elements to encrypt.

  6. Save your changes.

    AM now uses the key pairs you configured in the realm’s secret store to sign or encrypt the elements you selected.

Implement SSO and SLO

AM provides two options for implementing SSO and SLO with SAML v2.0:

Integrated mode

Integrated mode single sign-on and single logout uses a SAML2 authentication node on a service provider (SP), thereby integrating SAML v2.0 authentication into the AM authentication process. The authentication node handles the SAML v2.0 protocol details for you.

Integrated mode supports SP-initiated single sign-on only, because the authentication service that includes the SAML v2.0 node resides on the SP.

You cannot trigger IDP-initiated single sign-on in an integrated mode implementation.

Integrated mode with trees does not support SLO.

Standalone mode

Standalone mode requires that you invoke JSPs pages to initiate single sign-on and SLO.

The following table provides information to help you decide whether to implement integrated mode or standalone mode for your AM SAML v2.0 deployment:

Table 4. Integrated or Standalone Mode?
Deployment Task or Requirement Implementation Mode

You want to deploy SAML v2.0 single sign-on and single logout using the easiest technique.

You want to trigger SAML v2.0 IDP-initiated SSO.

You want to use the SAML v2.0 Enhanced Client or Proxy (ECP) single sign-on profile.

Your IDP and SP instances are using the same domain name; for example, mydomain.net.(1)

(1) Due to the way integrated mode tracks authentication status by using a cookie, it cannot be used when both the IDP and SP share a domain name.

SSO and SLO in integrated mode

Authentication nodes and trees support SSO in integrated mode only. The SAML2 Authentication node handles the SAML v2.0 authentication flow, but relies on other nodes.

Integrated mode flow (trees)
SAML v2.0 Integrated Mode Flow
Figure 4. SAML v2.0 Integrated Mode Flow
  1. An unauthenticated user initiates authentication to an AM SAML v2.0 service provider. The login URL references an authentication tree that includes a SAML2 authentication node. For example, https://<tenant-name>.forgeblocks.com/am/XUI/?service=mySAM2LTree.

  2. If there are any authentication nodes that precede the SAML2 Authentication node, AM executes them.

  3. The SAML2 authentication node processing begins.

  4. The authentication node requests an assertion from the IdP. The configuration of the SAML2 Authentication node determines the details of the request.

    If the user is not authenticated in the IdP, the IdP will request them to authenticate.

  5. The IdP responds to the SP with a SAML assertion.

  6. If the SAML assertion contains a non-transient name ID, AM searches the identity store, attempting to locate a user with the same name ID.

    If the name ID for the account exists, the tree ends in the success node.

    If the name ID does not exist…​

  7. ... and a Create Object node is configured in the tree, it creates a new account in the SP using auto-federation, including the name ID in the user profile.

  8. ... and method of authenticating the user is available in the tree, a Write Federation Information node writes the persistent name ID in the user profile.

    For more information about linking when autofederation is not configured, see Link identities for authentication.

Implement SAML v2.0 single sign-on in integrated mode

The following list is an overview of the activities you perform when implementing SAML v2.0 single sign-on in integrated mode:

  1. Preparing entity providers and a circle of trust, and changing several endpoints in the service provider configuration.

  2. Configuring a tree that contains, at least, the SAML2 authentication node.

Configure AM for integrated mode

  1. If you have not already done so, configure SAML v2.0 by performing the tasks listed in Deployment considerations.

  2. In the AM admin UI, create a hosted service provider by following the steps in Create a hosted entity provider.

    Ensure that you have configured the attribute map (Assertion Processing > Attribute Mapper). It determines how AM will map assertion attributes coming from the IdP to the user’s profile on the SP.

    During the authentication process, the mapping is used to find existing users on the SP, and to create or update user accounts on the SP.

  3. Configure a remote identity provider by following the steps in Import and configure a remote entity provider.

    When you specify the circle of trust for the IDP, use the Add to Existing option and specify the circle of trust that you created when you created the hosted service provider.

  4. Change the Assertion Consumer Service locations in the hosted service provider configuration.

    The default locations support standalone mode. Therefore, you must change the locations when implementing integrated mode.

    Change the locations as follows:

    • In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Services > Assertion Consumer Service.

    • Change the location of the HTTP-Artifact consumer service to use AuthConsumer, rather than Consumer. For example, if the location is https://<sp-tenant-name>.forgeblocks.com/am/Consumer/metaAlias/sp, change it to https://<sp-tenant-name>.forgeblocks.com/am/AuthConsumer/metaAlias/sp.

    • Similarly, change the location for the HTTP-POST consumer service to use AuthConsumer rather than Consumer.

      Note that you do not need to change the location for the PAOS service because integrated mode does not support the PAOS binding.

    • The results will resemble the following:

      Editing the Consumer Service URLs for Integrated Mode.

      Save your changes. Now you are ready to configure authentication trees.

Create accounts dynamically during federation

When using integrated mode, the SP can leverage authentication tree’s features to tailor the authentication experience to the users. Therefore, you can create very complicated trees, or even multiple trees to satisfy the requirements of your organization.

The example shown in this procedure uses the SAML v2.0 node to request an assertion from the IdP, and then creates an account for the user in the SP if one does not exist.

If you are not using auto-federation, you can also use authentication trees to create persistent links between the user accounts.

Perform the steps in this procedure to configure a tree similar to the following:

Example Tree to Create Accounts Dynamically
Figure 5. Example Tree to Create Accounts Dynamically
  1. Add a SAML2 Authentication node.

    Integrated mode is SP SSO-initiated only, and SLO is not supported.

    The node processes the assertion, makes its contents available to the authentication tree’s state in the userInfo object, and tries to map the assertion’s nameID using the uid mapping in the SP’s assertion map.

    If the node finds a match, the tree continues through the Account Exists output. Otherwise, the tree continues through the No Account Exists output.

    Note that the attribute the node uses to map the nameID is not configurable, and this example adds nodes to process the userInfo object and match its contents to the managed user’s schema.

  2. Add a Scripted Decision node to copy the information from the assertion to the authentication tree’s shared state.

    Example script
    outcome = "true";
    if (sharedState.get("userInfo")) {
    if (sharedState.get("objectAttributes")) {
    sharedState.remove("objectAttributes");
    }
    var userName=null,sn=null,mail=null;
    
        try { userName=sharedState.get("userInfo").get("attributes").get("uid").get(0).toString(); } catch (e) {}
        try { sn=sharedState.get("userInfo").get("attributes").get("sn").get(0).toString(); } catch (e) {}
        try { mail=sharedState.get("userInfo").get("attributes").get("mail").get(0).toString(); } catch (e) {}
    
      sharedState.put("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
    }

    For more information, see Scripted decision node API functionality.

  3. Add an Identify Existing User node to search the user with the appropriate attribute.

    For example, userName.

  4. Complete the tree adding the required nodes to create the new account if it does not exist on the SP.

    The scripted decision node that you created before gathering the attributes that are now available to create the account. However, these may not be enough to satisfy your managed user rules. To ensure that the required attributes are available, use the Required Attributes Present node to check them, and the Attribute Collector node to collect the ones missing.

    Finally, to create the account, use the Create Object node.

    Ensure that you configure the appropriate identity resource in this node. For example, managed/alpha_user.

  5. (Optional) If you have not configured auto-federation, you can add the Write Federation Information node to create a persistent link between the accounts.

SSO and SLO in standalone mode

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

SLO attempts to log out all session participants:

  • For hosted IDPs, single logout attempts to log out of all SPs with which the session established SAML federation.

  • For hosted SPs, single logout attempts to log out of the IDP that was source of the assertion for the user’s session.

Verify that the Federation authentication module is present

Standalone mode requires that a Federation authentication module instance is present in the realm in which you define your circle of trust, identity providers, and service providers.

The module must be of type Federation, and also have the name as Federation.

AM creates a Federation authentication module when you create a new realm, so the required module is already available unless you explicitly deleted it. If you deleted the Federation authentication module and need to restore it to a realm, create a new authentication module named Federation of module type Federation. No additional configuration is needed.

Do not add the Federation authentication module to an authentication chain. The module is used for internal purposes.

JSP pages for SSO and SLO

With standalone mode, AM SAML v2.0 Federation provides JSP files that direct users to do SSO and SLO across providers in a circle of trust. AM has two JSPs for single sign-on and two JSPs for SLO, allowing you to initiate both processes either from the identity provider side, or from the service provider side.

The JSP pages are available under the context root at /saml2/jsp/, for example https://<tenant-name>.forgeblocks.com/am/saml2/jsp/.

For details of how to use JSPs in a worked example, see Test SAML2 SSO using JSP flows.

When you perform HTTP GET requests to these JSPs, there are several query parameters to specify. Which query parameters you can use depends on the JSP. When setting parameters in the JSPs, make sure the parameter values are correctly URL-encoded.

The JSP pages only support query parameters sent by using HTTP GET requests. Do not attempt to use HTTP POST or PUT requests to the pages.

IDP-initiated SSO JSP

idpSSOInit.jsp

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

Also mapped to the endpoint idpssoinit under the context root.

URLs:
  • https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpSSOInit.jsp

  • https://<idp-tenant-name>.forgeblocks.com/am/idpssoinit

Example:
  • The following URL initiates single sign-on from the identity provider side, leaving the user at https://forgerock.com:

    https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpSSOInit.jsp
    ?metaAlias=/idp&spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
    &RelayState=https%3A%2F%2Fforgerock.com
idpSSOInit.jsp query parameters
metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as, metaAlias=/alpha/idp.

This parameter takes the format /realm-name/provider-name, as described in MetaAlias.

spEntityID

(Required) Use this parameter to indicate the remote service provider.

Make sure you URL-encode the value. For example, specify spEntityID=https://www.sp.com:8443/openam as spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam.

affiliationID

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

binding

(Optional) Use this parameter to indicate which binding to use for the operation.

For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. You can also specify binding=HTTP-Artifact.

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier.

For example, 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=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

RelayStateAlias

(Optional) Use this parameter to specify the parameter to use as RelayState.

For example, if the query string target=https%3A%2F%2Fforgerock.com&RelayStateAlias=target, is equivalent to RelayState=https%3A%2F%2Fforgerock.com.

IDP-initiated SLO JSP

idpSingleLogoutInit.jsp

Used to initiate single logout from the IDP.

Also mapped to the endpoint IDPSloInit under the context root.

URLs:
  • https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpSingleLogoutInit.jsp

  • https://<idp-tenant-name>.forgeblocks.com/am/IDPSloInit

Example:
  • The following URL performs single logout from the identity provider side, using a self-submitting form rather than a redirect, and leaving the user at https://forgerock.com:

    https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpSingleLogoutInit.jsp
    ?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    &RelayState=https%3A%2F%2Fforgerock.com
idpSingleLogoutInit.jsp query parameters
binding

(Required) Use this parameter to indicate which 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

  • 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=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

    To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

SP-initiated SSO JSP

spSSOInit.jsp

Use this page to initiate single sign-on from the service provider side.

Also mapped to the endpoint spssoinit under the context root.

URLs:
  • https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spSSOInit.jsp

  • https://<sp-tenant-name>.forgeblocks.com/am/spssoinit

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

    https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spSSOInit.jsp
    ?metaAlias=/sp
    &idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
    &RelayState=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam%2FXUI%2F%23profile%2Fdetails
spSSOInit.jsp query parameters
idpEntityID

(Required) Use this parameter to indicate the remote identity provider. Make sure you URL-encode the value.

For example, encode idpEntityID=https://www.idp.com:8443/openam as: idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam.

metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as metaAlias=/alpha/sp.

This parameter takes the format /realm-name/provider-name as described in MetaAlias.

affiliationID

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

AllowCreate

(Optional) When set to true, the identity provider can create a new identifier for the principal if none exists.

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.

AM accepts the following values:

  • better. Specifies that the authentication context statement in the assertion must be better (stronger) than one of the provided authentication contexts.

  • exact. Specifies that the authentication context statement in the assertion must exactly match at least one of the provided authentication contexts.

  • maximum. Specifies that the authentication context statement in the assertion must not be stronger than any of the other provided authentication contexts.

  • minimum. Specifies that the authentication context statement in the assertion must be at least as strong as one of the provided authentication contexts.

AuthnContextClassRef

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

When hosted IDP and SP entities are saved in the AM admin UI, any custom authentication contexts are also saved, as long as they are included in the extended metadata. You can load custom authentication contexts in the extended metadata using the ssoadm command.

AuthnContextDeclRef

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

AuthLevel

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

binding

(Optional) Use this parameter to indicate which binding to use for the operation.

For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. You can also specify binding=HTTP-Artifact.

Destination

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

ForceAuthn

(Optional) When set to true the identity provider should force authentication.

Configure the org.forgerock.openam.saml2.authenticatorlookup.skewAllowance advanced property to specify the maximum permissible time since authentication by the IDP. See SAML v2.0 Advanced Properties.

When false, the IDP can reuse existing security contexts.

isPassive

(Optional) When set to true the identity provider authenticates passively.

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier.

For example, 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=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

RelayStateAlias

(Optional) Use this parameter to specify the parameter to use as the RelayState.

For example, the query string target=https%3A%2F%2Fforgerock.com&RelayStateAlias=target, is the same as RelayState=https%3A%2F%2Fforgerock.com.

reqBinding

(Optional) Use this parameter to indicate the 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 kbd:[:] before the 1:

<Advice>
  <AttributeValuePair>
    <Attribute name="AuthLevelConditionAdvice"/>
    <Value>/:1</Value>
  </AttributeValuePair>
</Advice>

SP-initiated SLO JSP

spSingleLogoutInit.jsp

Used to initiate single logout from the SP.

Also mapped to the endpoint SPSloInit under the context root.

URLs:
  • https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spSingleLogoutInit.jsp

  • https://<sp-tenant-name>.forgeblocks.com/am/SPSloInit

Example:
  • The following URL initiates single logout from the service provider side, using the HTTP redirect method, leaving the user at https://forgerock.com:

    https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spSingleLogoutInit.jsp
    ?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
    &RelayState=https%3A%2F%2Fforgerock.com
spSingleLogoutInit.jsp query parameters
binding

(Required) Use this parameter to indicate which 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. You can also specify 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 property is not set, then AM uses this parameter to find the default binding. Make sure you URL-encode the value.

For example, specify idpEntityID=https://www.idp.com:8443/openam as idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%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.

The RelayState parameter 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=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

ECP profile configuration

The SAML v2.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 v2.0 Web Browser single sign-on profile.

The ECP knows which identity provider to contact for the user, and is able to use the reverse SOAP (PAOS) SAML v2.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.

AM supports the SAML v2.0 ECP profile on the server side for identity providers and service providers. You must build the ECP.

By default, an AM 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 AM cookies as it would for any other client application. If you must change the mapping after writing and installing your own session mapper, you can change the class under Realms > Realm Name > Applications > Federation > Entity Providers > IDP Name > IDP > Advanced > ECP Configuration#.

By default, an AM service provider uses the com.sun.identity.saml2.plugins.ECPIDPFinder class to return identity providers from the list under Realms > Realm Name > Applications > 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 AM service provider is /SPECP as in https://<sp-tenant-name>.forgeblocks.com/am/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=https%3A%2F%2Fforgerock.org%2Findex.html. Make sure this parameter is URL-encoded.

For example, to access the service provider followed by the resource at https://forgerock.org/index.html, use https://<sp-tenant-name>.forgeblocks.com/am/SPECP?metaAlias=/sp&RelayState=https%3A%2F%2Fforgerock.org%2Findex.html.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

Federate identities

AM supports linking, or federating, identities between the IDP and the SP.

See the following table for a list of tasks to configure how AM federates identities:

Task Resources

Decide whether to permanently link identities

AM lets you choose whether to maintain the link between federated entities after logout (persistent federation) or to create a new link each time the user logs in (transient federation).

Also, learn how to manage persistent federation.

Link identities automatically

Configure AM to link identities automatically when they exist in both the IDP and the SP, or to create an account on the SP when the NameID that the IDP provides unequivocally identifies the identity.

Link identities using the authentication service

Configure AM to link identities when the NameID that the IDP provides is not enough to unequivocally identify the identity.

Link identities in the IDP to a single, shared account on the SP

Configure AM to temporarily link an identity in the IDP to, for example, the anonymous user in the SP.

Persistent or transient federation

You can choose to permanently link identities, known as persistent federation. AM lets you configure the service provider to persistently link identities, 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 another unique user identifier, you can use this method to link accounts without user interaction. See Link identities automatically based on an attribute value.

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. This is known as transient federation.

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

In a SAML v2.0 federation where accounts have been persistently linked, authentication is required only on the identity provider side.

Authentication is required on the service provider side, however, when the service provider is unable to map the identity in the assertion from the identity provider to a local user account.

This can happen the first time accounts are linked, for example. After which, the persistent identifier establishes the mapping.

Authenticating to the SP may also be required when transient federation is used when linking identities. The service provider must authenticate the user for every SAML assertion received. This is because the identifier used to link the identities is transient; it does not provide a repeatable, durable means to link the identities.

You can prevent the ability to persistently link accounts on the SP side by setting the spDoNotWriteFederationInfo property to true, and on the IDP side by setting the idpDisableNameIDPersistence to true.

Enable persistent federation

Both integrated and standalone SAML v2.0 implementations allow you to persistently link accounts.

Before attempting to configure persistent federation, ensure that you have configured AM for SAML v2.0 single sign-on, created the identity and service providers, and configured a circle of trust. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

  1. If you are using integrated mode:

    • Create an authentication tree that contains the SAML2 Authentication node.

      If you have not created one yet, see SSO and SLO in Integrated Mode for an example.

    • In the NameID Format field, specify the value urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

      You can also link accounts together using different nameid formats. For example, you could use the urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified value, and receive the IDP user’s e-mail address in the NameID value. The SP would display the login page to identify the local user account and persistently link them.

    • Save your work.

    • Initiate single sign-on by accessing a URL that calls an authentication tree that includes the SAML2 node.

      For example, https://<sp-tenant-name>.forgeblocks.com/am/XUI/#login/&realm=alpha&service=mySAML2Tree.

  2. If you are using standalone mode single sign-on:

    • Initiate single sign-on with either the spSSOInit.jsp or idpSSOInit.jsp JSP page, including NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent as a query parameter.

      For example, to initiate single sign-on from the service provider, access a URL similar to the following:

      https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spSSOInit.jsp
      ?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
      &metaAlias=/sp
      &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

      To initiate single sign-on from AM acting as the identity provider, access a URL similar to the following:

      https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpSSOInit.jsp
      ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
      &metaAlias=/idp
      &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  3. To test your work:

    • Authenticate to the IDP as the user you want to persistently link.

      On success, you will be redirected to the SP.

      If there was no login page displayed at the SP, you might have enabled auto-federation, or AM was able to find a link between the two identities without requiring authentication at the SP.

      To ensure there are no existing links, create a new identity in the IDP, and initiate single sign-on again, authenticating to the IDP as the new user.

    • Authenticate to the SP as the local user to link with.

      The accounts are persistently linked, with persistent identifiers stored in the user’s profile on both the IDP and the SP.

      Subsequent attempts to access the SP will only require that the user authenticates to the IDP, as the identities are now permanently linked.

      You can prevent the ability to persistently link accounts on the SP side by setting the spDoNotWriteFederationInfo property to true, and on the IDP side by setting the idpDisableNameIDPersistence to true.

Enable transient federation

Both integrated and standalone SAML v2.0 implementations allow you to temporarily link accounts.

Before attempting to configure transient federation, ensure that you have configured AM for SAML v2.0, created the identity and service providers, and configured a circle of trust. You must also have configured AM to support single sign-on. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

  1. If you are using integrated mode:

    • Create an authentication tree that contains the SAML2 Authentication node.

      If you have not created one yet, see SSO and SLO in Integrated Mode for an example.

    • In the NameID Format field, specify the value urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

    • Save your work.

    • Initiate single sign-on by accessing a URL that calls an authentication tree that includes the SAML v2.0 node:

      For example, https://<sp-tenant-name>.forgeblocks.com/am/XUI/#login/&realm=alpha&service=mySAMLTree.

  2. If you are using standalone mode SSO:

    • Initiate single sign-on with either the spSSOInit.jsp or idpSSOInit.jsp JSP page, including NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient as a query parameter.

      For example, to initiate single sign-on from the service provider, access a URL similar to the following:

      https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spSSOInit.jsp
      ?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
      &metaAlias=/sp
      &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient

      To initiate single sign-on from the identity provider, access a URL similar to the following:

      https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpSSOInit.jsp
      ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
      &metaAlias=/idp
      &NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  3. To test your work:

    • Authenticate to the IDP as the user you want to temporarily link.

      On success, you will be redirected to the SP.

    • Authenticate to the SP as the local user.

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

      Nothing is written in the user’s profile on either the identity provider and the service provider.

      Subsequent attempts to access the SP will require that the user authenticates to the IDP AND the SP (assuming no existing session exists), as the identities are not linked.

Manage federation of persistently linked accounts

AM implements the SAML v2.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. (To configure these attribute types, in the AM admin UI, go to Configure > Global Services > SAMLv2 Service Configuration.)

AM provides a pair of JSP files for managing persistently linked accounts; idpMNIRequestInit.jsp for initiating changes from the IDP side, and spMNIRequestInit.jsp for initiating changes from the SP side.

The JSP parameters are listed below. When setting parameters in the JSPs, make sure the parameter values are correctly URL-encoded.

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=https://www.sp.com:8443/openam as spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%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.

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 which 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=https://www.idp.com:8443/openam as idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%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.

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

Change federation of persistently linked accounts

  1. Retrieve the name identifier value, used to manage the federation in the second step.

    1. You can retrieve the name identifier value on the IDP side by checking the value of the sun-fm-saml2-nameid-infokey property.

      For example, if the user’s entry in the directory shows:

        sun-fm-saml2-nameid-infokey:
          https://<idp-tenant-name>.forgeblocks.com/am|
          https://<sp-tenant-name>.forgeblocks.com/am|
          XyfFEsr6Vixbnt0BSqIglLFMGjR2

      Then, the name identifier on the IDP side is XyfFEsr6Vixbnt0BSqIglLFMGjR2.

    2. You can retrieve the name identifier value on the SP side by checking the value of sun-fm-saml2-nameid-info.

      For example, if the user’s entry in the directory shows:

        sun-fm-saml2-nameid-info:
          https://<sp-tenant-name>.forgeblocks.com/am|
          https://<idp-tenant-name>.forgeblocks.com/am|
          ATo9TSA9Y2Ln7DDrAdO3HFfH5jKD|
          https://<idp-tenant-name>.forgeblocks.com/am|
          urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|
          9B1OPy3m0ejv3fZYhlqxXmiGD24c|
          https://<sp-tenant-name>.forgeblocks.com/am|
          SPRole|false

      Then, the name identifier on the SP side is 9B1OPy3m0ejv3fZYhlqxXmiGD24c.

  2. Use the identifier to initiate a change request, as in the following examples:

    1. To initiate a change request from the service provider, use a URL similar to the following example:

      https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spMNIRequestInit.jsp
      ?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
      &metaAlias=/sp
      &requestType=NewID
      &IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2

      You can substitute am/SPMniInit for am/saml2/jsp/spMNIRequestInit.jsp.

    2. To initiate a change request from the identity provider, use a URL similar to the following example:

      https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpMNIRequestInit.jsp
      ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
      &metaAlias=/idp
      &requestType=NewID
      &SPProvidedID=9B1OPy3m0ejv3fZYhlqxXmiGD24c

      You can substitute am/IDPMniInit for am/saml2/jsp/idpMNIRequestInit.jsp

Terminate federation of persistently linked accounts

AM lets you terminate account federation, where the accounts have been linked with a persistent identifier, as described in Enable persistent federation.

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 AM on port 8443 under deployment URI /openam.

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

    https://<sp-tenant-name>.forgeblocks.com/am/saml2/jsp/spMNIRequestInit.jsp
    ?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
    &metaAlias=/sp
    &requestType=Terminate
  2. To initiate the process of terminating account federation from the identity provider, access the following URL with at least the query parameters shown:

    https://<idp-tenant-name>.forgeblocks.com/am/saml2/jsp/idpMNIRequestInit.jsp
    ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
    &metaAlias=/idp
    &requestType=Terminate

Link identities automatically with auto-federation

AM lets you configure the service provider to automatically link identities based on an attribute value in the assertion returned from the identity provider, known as auto-federation.

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 configure AM to map the attributes to each other, and link identities, without the user having to authenticate to the SP.

Link identities automatically based on an attribute value

This procedure demonstrates how to automatically link identities based on an attribute value that is the same in both accounts.

Before attempting to configure auto-federation, ensure that you have configured AM for SAML v2.0, created the identity and service providers, and configured a circle of trust. You must also have configured AM to support single sign-on. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

Perform the following steps on the hosted IDP(s), and again on the hosted SP(s):

  1. Go to Realms > Realm Name > Applications > Federation > Entity Providers, and click on the name of the hosted provider.

    How do I switch between SP and IDP configuration for a given provider?

    AM only displays the configuration of a single role. Click on the labels to select the role view:

    saml-roles
  2. On the hosted IDP:

    • Go to the Assertion Processing tab.

    • Review the Attribute Map configuration. If the attributes you want to use to link the accounts on the IDP and the SP are not in the map already, add them.

      The IDP will send these attributes in the assertion, and the SP will then map them using its own attribute map.

      Tips to configure the attribute map on the IDP

      The user profile attributes used here must both be allowed in user profiles, and also be specified for the identity repository.

      To see the profile attributes available for an LDAP identity repository, log in to the AM admin UI, and go to Realms > Realm Name > Identity Stores > User Configuration. Check the LDAP User Attributes list.

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

      Example of Static Attribute Mapping. Notice that the static value is enclosed in double quotes.
    • Save your work.

  3. On the hosted SP:

    • Go to the Assertion Processing tab.

    • Review the Attribute Map configuration, and ensure that the attribute mappings you created on the IDP are represented in the map.

      Tips to configure the attribute map on the SP

      The value of Key is a SAML attribute sent in an assertion, and the value of Value is a property in the user’s session, or an attribute of the user’s profile.

      By default, the SP maps the SAML attributes it receives to equivalent-named session properties. However, when the SP is configured to create identities during autofederation and the identity does not exist yet, the SP maps the SAML attributes to their equivalents in the newly-created user profile.

      The special mapping Key: *, Value: * means that the SP maps each attribute it receives in the assertion to equivalent-named properties or attributes. For example, if the SP receives mail and firstname in the assertion, it maps them to mail and firstname respectively.

      Remove the special mapping and add key pairs to the map if:

      • (During autofederation) The attributes in the IdP’s and the SP’s identity stores do not match.

      • You need control over the names of the session properties.

      • You need control over which attributes the SP should map, because the IdP adds too many to the assertion.

      For example, if the the SAML attribute is firstname and you want the SP to map it to a session property/user profile attribute called cn, create a mapping similar to Key: firstname, Value: cn.

    • Enable auto-federation. In the Attribute property, enter the SAML attribute name that the SP will use to link accounts, as configured in the Attribute Map.

    • Save your work.

  4. To test your work, initiate single sign-on; for example, as described in IDP-Initiated SSO JSP.

    Authenticate to the IDP as the demo user. Attempt to access the SP, and you will notice that the user has a session, and can access their profile page on the SP without having to authenticate again.

Create identities automatically with auto-federation

On occasion, there may not yet be an identity to link with on the SP. For example, if it is the first time a user is attempting to access the service, and they do not have an account in the SP identity store.

You can configure AM to dynamically create an account for the user in the SP identity store, using the values in the assertion as profile properties, as defined in the attribute mappings.

Create and link identities based on attribute values

Before attempting to configure auto-federation to create identities based on attribute values, ensure that you have configured AM for SAML v2.0, created the identity and service providers, and configured a circle of trust. You must also have configured AM to support single sign-on. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

The following steps demonstrate how to dynamically create missing accounts on the SP:

  1. Go to Realms > Realm Name > Applications > Federation > Entity Providers, and click on the name of the hosted provider.

    How do I switch between SP and IDP configuration for a given provider?

    AM only displays the configuration of a single role. Click on the labels to select the role view:

    saml-roles
  2. On the hosted IDP:

    • Go to the Assertion Processing tab.

    • Review the Attribute Map configuration. If the attributes you want to populate when creating the new user are not in the map already, add them.

      The IDP will send these attributes in the assertion, and the SP will then map them using its own attribute map.

      Tips to configure the attribute map on the IDP

      The user profile attributes used here must both be allowed in user profiles, and also be specified for the identity repository.

      To see the profile attributes available for an LDAP identity repository, log in to the AM admin UI, and go to Realms > Realm Name > Identity Stores > User Configuration. Check the LDAP User Attributes list.

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

      Example of Static Attribute Mapping. Notice that the static value is enclosed in double quotes.
    • Save your work.

  3. On the hosted SP:

    • Go to the Assertion Processing tab.

    • Review the Attribute Map configuration, and ensure that the attribute mappings on the IDP are represented in the map.

      Tips to configure the attribute map on the SP

      The value of Key is a SAML attribute sent in an assertion, and the value of Value is a property in the user’s session, or an attribute of the user’s profile.

      By default, the SP maps the SAML attributes it receives to equivalent-named session properties. However, when the SP is configured to create identities during autofederation and the identity does not exist yet, the SP maps the SAML attributes to their equivalents in the newly-created user profile.

      The special mapping Key: *, Value: * means that the SP maps each attribute it receives in the assertion to equivalent-named properties or attributes. For example, if the SP receives mail and firstname in the assertion, it maps them to mail and firstname respectively.

      Remove the special mapping and add key pairs to the map if:

      • (During autofederation) The attributes in the IdP’s and the SP’s identity stores do not match.

      • You need control over the names of the session properties.

      • You need control over which attributes the SP should map, because the IdP adds too many to the assertion.

      For example, if the the SAML attribute is firstname and you want the SP to map it to a session property/user profile attribute called cn, create a mapping similar to Key: firstname, Value: cn.

    • Enable auto-federation. In the Attribute property, enter the SAML attribute name that the SP will use to link accounts, as configured in the Attribute Map.

      The value of the named attribute is used as the username of the created user when auto-federation is enabled.

    • Save your work.

    • Navigate to Realms > Realm Name > Authentication > Settings.

    • On the User Profile tab, in the User Profile field, select Dynamic or Dynamic with User Alias.

      For more information the user profile property, see User profile.

    • Save your work.

  4. To test your work:

    • Create a new user on the identity provider, including values for any attributes you mapped in the providers.

    • Log out of the AM admin UI, and initiate SSO; for example, as described in IDP-Initiated SSO JSP.

    • Authenticate as the new user you created in the IDP.

    • On success, check https://<sp-tenant-name>.forgeblocks.com/am/XUI/#profile/details to see the new user account created on the SP, and the attributes that were copied from the assertion.

Link identities for authentication

Identity providers and service providers must be able to communicate about users. Yet, in some cases, the identity provider chooses to communicate a minimum of information about an authenticated user; for example, a generated, opaque NameID that cannot directly be used to locate to an identity in the SP identity store.

AM can use these pseudonym identifiers for establishing links between otherwise unrelated accounts, by requiring that the user authenticates to the SP using a linking authentication mechanism.

The following list describes the sequence of events that occurs the first time a user attempts to authenticate to the AM service provider:

  1. Accessing the service provider.

    A user attempts to access a service and is redirected to the AM server acting as the service provider, specifying the SAML v2.0 service in the login URL. For example:

    • An authentication tree containing the SAML2 Authentication node.

      For example, https://<sp-tenant-name>.forgeblocks.com/am/XUI/#login/&service=spSAMLTree.

  2. Authentication at the identity provider.

    AM redirects the user to the identity provider. The user authenticates successfully at the identity provider. The identity provider returns a SAML assertion to the SP.

  3. Service provider attempts to access a federated identity.

    AM attempts to locate the identity in its own user store. No link between the IDP identity and a local one is found.

  4. Authenticating the user to the SP

    AM goes through a path in the authentication tree that lets the user authenticate on the SP.

  5. Identity federation.

    After successful authentication at the SP, AM then writes the name ID from the assertion into the local user’s profile, creating a permanent link between the two identities.

    For more information on creating permanent links between identities, see Persistent or transient federation

    For an example of an authentication tree that links identities, see SSO and SLO in Integrated Mode.

The following list describes the sequence of events that occurs during subsequent authentication attempts, after the user’s identities on the identity and service providers have been federated:

  1. Accessing the service provider.

    A returning user attempts to access their service and is redirected to the AM server acting as the service provider. Their login URL specifies the SAML v2.0 login service.

    For example, an authentication tree containing the SAML2 Authentication node and the Write Federation Information node:

    https://<sp-tenant-name>.forgeblocks.com/am/XUI/#login/&service=spSAMLTree.

  2. Authentication at the identity provider.

    AM redirects the user to the identity provider, and the user authenticates successfully at the identity provider. The identity provider returns a SAML assertion to the SP.

  3. Service provider attempts to access a federated identity.

    AM attempts to locate the name ID in its user store. The search for the name ID succeeds.

    As there is a match, the user does not need to log in to the SP, and is given access to the service.

Link accounts persistently

If you are not using auto-federation, perform the steps in this procedure to configure a tree similar to the following to link accounts persistently:

Example Tree to Link Accounts Persistently
  1. Add a SAML2 Authentication node.

    Integrated mode is SP SSO-initiated only, and SLO is not supported.

    Ensure that the NameID Format specified is persistent.

    The node processes the assertion, makes its contents available to the authentication tree’s state in the userInfo object, and tries to map the assertion’s nameID using the uid mapping in the SP’s assertion map.

    If the node finds a match, the tree continues through the Account Exists output. Otherwise, the tree continues through the No Account Exists output.

    Note that the attribute the node uses to map the nameID is not configurable, and this example adds nodes to process the userInfo object and match its contents to the managed user’s schema instead.

  2. Add a Scripted Decision node to copy the information from the assertion to the authentication tree’s shared state.

    Example script
    outcome = "true";
    if (sharedState.get("userInfo")) {
    if (sharedState.get("objectAttributes")) {
    sharedState.remove("objectAttributes");
    }
    var userName=null,sn=null,mail=null;
    
        try { userName=sharedState.get("userInfo").get("attributes").get("uid").get(0).toString(); } catch (e) {}
        try { sn=sharedState.get("userInfo").get("attributes").get("sn").get(0).toString(); } catch (e) {}
        try { mail=sharedState.get("userInfo").get("attributes").get("mail").get(0).toString(); } catch (e) {}
    
      sharedState.put("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
    }

    For more information, see Scripted decision node API.

  3. Add an Identify Existing User node to search the user with the appropriate attribute.

    For example, userName.

  4. Authenticate the user to the SP.

  5. Add the Write Federation Information node to the successful outcome of the authentication process to create the link between the accounts.

    If a transient link exists, it will be converted into a persistent one.

Link identities to a single, shared account

AM lets you map identities on the identity provider temporarily to a single account on the service provider; for example, the anonymous account, 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 create or retain identity data on the service provider, but instead you make authorization decisions based on attribute values from the identity provider.

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

Before attempting these steps, ensure that you have configured AM for SAML v2.0, created the identity and service providers, and configured a circle of trust. You must also have configured AM to support single sign-on. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

  1. On the hosted identity provider:

    • In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted Identity Provider Name.

    • On the Assertion Processing tab, if the attributes you want to access from the SP are not yet included in the Attribute Map property, add the attribute mappings.

      Enter attribute map values using the following format: SAML Attribute Name=Profile Attribute Name.

    • Save your work.

  2. On the hosted service provider:

    • In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted Service Provider Name.

    • On the Assertion Processing tab, if the attributes you want to access from the IDP are not yet included in the Attribute Map property, add the attribute mappings.

      Enter attribute map values using the following format: SAML Attribute Name=Profile Attribute Name.

      You can use a special wildcard mapping of *=*, which maps each attribute in the assertion to an identically named attribute on the SP, using the relevant value.

    • Ensure that the Auto Federation property is not selected.

    • In the Transient User property, add the account name AM will use to link all identities from the IDP, for example; anonymous.

    • Save your work.

  3. To test your work:

    • Create a new user on the identity provider, including values for any attributes you mapped in the providers.

    • Log out of the AM admin UI, and initiate SSO using transient federation; for example, as described in Enable transient federation.

    • Authenticate to the IDP as the new user you created.

    • After successfully authenticating to the IDP, check that the identity is linked to a transient account by performing the following steps:

      • In a separate browser or private window, log in to the AM admin UI of the SP.

      • Go to Realms > Realm Name > Sessions.

      • Enter the transient user name you configured earlier; for example, anonymous.

        You will see one or more sessions of users who have initiated single sign-on and been temporarily linked to the transient user account.

Link identities in bulk

If you manage both the identity provider and service provider, you can link accounts in bulk 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 Configure IDPs, SPs, and CoTs, and install the ssoadm tool.

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

The ssoadm command requires 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=sp,dc=com|id=demo,ou=user,dc=idp,dc=com

All the user 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=sp,dc=com\|id=demo,ou=user,dc=idp,dc=com
    $ ssoadm do-bulk-federation \
      --metaalias /sp \
      --remoteentityid https://www.idp.com:8443/openam \
      --useridmapping /tmp/user-map.txt \
      --nameidmapping /tmp/name-map.txt \
      --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \
      --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@www.idp.com:/tmp/name-map.txt
    openam@www.idp.com’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 uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \
      --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.

Customize SAML v2.0 with plugins

AM includes several plugin points that let you extend SAML v2.0 functionality.

AM provides a scripting engine and template scripts for you to extend SAML v2.0 behavior by running scripts stored as configuration, rather than by updating code. Creating and modifying plugin scripts enables rapid development without the need to change or recompile core AM.

For information about creating scripts, see Manage scripts through the AM admin UI.

To view sample scripts, see Sample scripts.

You can use a sample script as a base for your own implementation, and configure AM for your custom implementation in the entity provider settings.

For information about configuration settings, see the Reference section.

The following table provides an overview of the SAML v2.0 plugin points.

Plugin Description

Customize the default IDP attribute mapper to specify which user attributes are included in an assertion.

Customize SAML responses and browser redirects.

SAML v2.0 scripting API

The following properties are common to all SAML v2.0 plugin scripts. See individual plugins for additional properties specific to the script type.

Show script properties
hostedEntityId

The entity ID for the hosted IDP.

logger

The logger instance particular to the script type. The output log files will be prefixed by a static string denoting the script type. Always present.

realm

The name of the realm that the user is authenticating to.

IDP attribute mapper plugin

Use this plugin to map user-configured attributes to SAML attribute objects to insert into the generated SAML assertion.

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

To view a template script, including the available script properties, see saml2-idp-attribute-mapper.js.

Create a custom IDP attribute mapper script

Complete the following steps to implement an example IDP attribute mapper script that modifies the SAML attributes that are inserted in the assertion returned by the IDP.

This task assumes your environment is already correctly configured for single sign-on using SAML v2.0, where AM is the hosted IDP.

  1. In the AM admin UI, go to Realms > Realm Name > Scripts, and click New Script.

  2. Enter a unique name for your script, select SAML2 IDP Attribute Mapper from the Script Type drop-down list, and click Create.

  3. Copy the saml2-idp-attribute-mapper.js script and paste in the Script field.

  4. Insert the following lines of example code to return a custom static attribute, around line 150, preceding return attributes;:

    var customSet = new java.util.HashSet();
    customSet.add("test");
    attributes.add(idpAttributeMapperScriptHelper.createSAMLAttribute("customSAMLAttribute", null, customSet));

    For information about the bindings that are available to the script, see IDP attribute mapper scripting API.

  5. Validate and save your changes.

  6. Configure AM to use the updated IDP attribute mapper script.

    1. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP Name > Assertion Processing.

    2. In the Attribute Mapper Script field, select SAML2 IDP Attribute Mapper Script.

      Alternatively, if you created a script rather than modifying the default, select the new script name.

    3. Save your changes.

  7. Test your changes and verify that the AttributeStatement element in the SAML assertion contains the custom attribute.

    For example:

    <saml:AttributeStatement>
      <saml:Attribute Name="customSAMLAttribute">
        <saml:AttributeValue
            xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">test
        </saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>

IDP attribute mapper scripting API

The following properties are available to IDP attribute mapper scripts, in addition to the common SAML v2.0 properties.

Show script properties
idpAttributeMapperScriptHelper

An IdpAttributeMapperScriptHelper instance containing methods used for IDP attribute mapping. Always present.

remoteEntityId

The remote entity ID.

session

Contains a representation of the user’s single sign-on session object.

IDP adapter plugin

Use this plugin to alter the processing of the authentication request at a particular point in the SAML journey, such as to redirect the user before single sign-on takes place, or before a failure response is sent.

The plugin provides hooks at the following points in assertion processing:

Table 5. IDP Adapter Plugin Points
Plugin point Description

preSingleSignOn

Invoked when the authentication request is first received. Only applicable to SP-initiated flows.

preAuthentication

Invoked before the request is redirected for authentication. Only applicable to SP-initiated flows.

preSendResponse

Invoked after the user has successfully authenticated or for an existing valid session, before the response is sent.

preSignResponse

Invoked after the response has been constructed, but before the response is signed, to let you customize the content of the SAML response.

preSendFailureResponse

Invoked before a SAML error response is returned. Only applicable to SP-initiated flows.

To view a template script, including the available script properties, see saml2-idp-adapter.js.

Create a custom IDP adapter script

Complete the following steps to implement an example IDP adapter script that determines whether the authentication journey should be redirected, based on the evaluation of a policy.

This task assumes your environment is already correctly configured for single sign-on using SAML v2.0, where AM is the hosted IDP.

You will also need to configure a policy that belongs to a policy set named saml, and has the following example configuration:

  • Actions: ASSERT:Denied

  • Response Attributes: redirect_uri: https//example.com

  • Subjects: "type": "AuthenticatedUsers"

  1. In the AM admin UI, go to Realms > Realm Name > Scripts, and click New Script.

  2. Enter a unique name for your script, select SAML2 IDP Adapter from the Script Type drop-down list, and click Create.

  3. Copy the saml2-idp-adapter.js script and paste in the Script field.

  4. Insert the following code for the preSendResponse function to redirect or send an error response if the policy for the SP evaluates to false. For example:

    function preSendResponse () {
    
      var frJava = JavaImporter(
        com.sun.identity.saml2.common.SAML2Exception);
    
      try {
        var ents = idpAdapterScriptHelper.getEntitlements(
            "saml", realm, session, authnRequest).iterator();
        while(ents.hasNext()){
          var entitlement = ents.next();
          var isAllowed = entitlement.getActionValue("Assert");
    
          if(isAllowed != null && isAllowed == true){
            return false;
          } else{
            var redirectUris = entitlement.getAttributes().get("redirect_uri");
    
            if (redirectUris == null || redirectUris.isEmpty()){
              logger.error("No redirect_uri");
              response.sendError(403);
            } else{
              var redirectUri = redirectUris.iterator().next();
              response.sendRedirect(redirectUri);
            } return true;
          }
        }
      } catch(error) {
        logger.error("Error in preSend reponse. " + error);
        throw new frJava.SAML2Exception(error);
      }
    }
  5. Validate and save your changes.

  6. Configure AM to use the updated IDP adapter script.

    1. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP Name > Advanced.

    2. In the IDP Adapter Script field, select the script you created.

    3. Save your changes.

  7. Test your changes using an SP-initiated flow and verify that the user is redirected to the redirect_uri (in this example, https://example.com).

IDP adapter scripting API

The following properties are available to IDP adapter scripts, in addition to the common SAML v2.0 properties.

Show script properties
authnRequest

The original authentication request sent from the SP. Not available to the preSendFailureResponse function.

faultCode

The fault code returned in the SAML response.

Only available to the preSendFailureResponse function.

faultDetail

Contains the details of the fault returned in the SAML response.

Only available to the preSendFailureResponse function.

idpAdapterScriptHelper

The IdpAdapterScriptHelper instance contains supporting methods that provide context information when customizing the IDP adapter plugin points.

Always present.

relayState

A String representing the relayState used in the redirect.

Not available to the preSingleSignOn or preSendFailureResponse functions.

reqId

The id to use for continuation of processing if the adapter redirects.

Not available to the preSignResponse or preSendFailureResponse functions.

request

The HttpServletRequest object. Always present.

res

The SAML response.

Only available to the preSignResponse function.

response

The HttpServletResponse object.

Not available to the preSignResponse function.

session

Contains a representation of the user’s single sign-on session object.

Not available to the preSingleSignOn or preSendFailureResponse functions.

Reference

This reference section covers service provider, identity provider, and circle of trust configuration properties. For the global services reference, see Reference.

Hosted identity provider configuration properties

Once you have set up a hosted identity provider, you can configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content

The following groups appear under the Assertion Content tab:

Signing and Encryption
Request/Response Signing

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

Encryption

When selected, the service provider must encrypt NameID elements.

Secret ID and Algorithms
Secret ID Identifier

Specifies an identifier for the secret ID AM uses for this entity provider, when resolving secrets.

For example, when this value is set to demo, the entity provider will use the following secret IDs:

  • am.applications.federation.entity.providers.saml2.demo.signing

  • am.applications.federation.entity.providers.saml2.demo.encryption

If not specified, AM uses the entity provider role-specific, default global secret IDs.

Signing Algorithm

The algorithms the provider can use to sign the request/response attributes selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Digest Algorithm

The digest algorithms the provider can use when signing the requests and responses selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Encryption Algorithm

This field specifies two types of encryption algorithms for the provider:

  • Symmetric algorithms, which the provider can use to encrypt the objects selected in the Encryption group. Select one or more AES algorithms from the drop-down list.

    Default: http://www.w3.org/2001/04/xmlenc#aes128-cbc

  • Asymmetric algorithms, advertised as the provider’s transport key algorithm. When SAML v2.0 token encryption is enabled, hosted providers should use the algorithm the remote provider is advertising when encrypting symmetric encryption keys.

    Select one or more algorithms from the drop-down list:

    Key Transport Algorithms
NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign-on.

The following diagram shows how the hosted IDP decides which of the supported NameID formats is used:

Diagram showing how the hosted IDP decides which of the supported NameID formats is used.
NameID Value Map

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

NameID mapping supports Base64-encoded binary values. With this flag set, AM Base64-encodes the profile attribute when adding it to the assertion.

Authentication Context
Mapper

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

Default value: com.sun.identity.saml2.plugins.DefaultIDPAuthnContextMapper

Authentication Context

Specifies the authentication context classes the IDP supports, and any AM authentication mechanisms that are used when an SP specifies the respective class in a SAML v2.0 authentication request.

  • The Predefined Reference drop-down list specifies the list of context references.

  • The Key drop-down list specifies the authentication mechanism that AM uses when an SP specifies an authentication context class in a SAML v2.0 authentication request.

    Authentication Mechanisms Reference for the Key Drop-down List
    Service

    AM will use the specified authentication chain or tree to authenticate the user.

    For example, in the Value field, enter HmacOneTimePassword to use the built-in one-time password example authentication tree, or ldapService to use the built-in chain that authenticates against the default identity store.

    Module

    AM will use the specified authentication module to authenticate the user.

    Authentication Level

    AM will authenticate the user with a method that has an associated authentication level equal to or higher than the specified value.

    If there is more than one suitable method, AM presents the available options by using a ChoiceCallback.

    For more information on using and returning callbacks during authentication, see Authenticate using REST.

    The Role, User, and Resource URL options are deprecated and should not be used.
  • The Value field specifies the name relative to the authentication mechanism you chose in the previous step. For example, if you chose the Service authentication mechanism, add the name of an authentication tree or chain in the Value field.

  • The Level field specifies the numeric value of precedence of the supported context reference classes.

    Classes with higher numbers are considered stronger than lower numbered classes. The values determine which authentication classes can be used when the SP makes an authentication request that uses a comparison attribute; for example, minimum or better.

    Note that the value in the Level field should match the auth level of the specified chain, module, or tree. For example, if the specified authentication chain sets an auth level of 10, set the same value in the Level field in the Authentication Context table. As AM compares the current auth level against the level specified in the Authentication Context table, if the two values do not match, AM may require a logged in user to re-authenticate unnecessarily.

    Example

    image::auth-context-mappings.png[Choose the authentication mechanisms AM uses when receiving authentication requests that specify an authentication context class.]

    For more information on authentication context classes, see Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.

    Default value: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

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

Assertion Cache
Enabled

When enabled, cache assertions.

Assertion Processing

The following properties appear under the Assertion Processing tab:

Attribute Mapper
Attribute Mapper Plugin

This extension point is used to map the IDP attributes that are inserted into the SAML assertion.

The plugin can be implemented either in JavaScript or as a Java class. If defined, the scripted implementation takes precedence, otherwise AM invokes the Attribute Mapper class.

The following plugin properties determine which implementation is used:

Attribute Mapper

Specifies the Java class for the Attribute Mapper plugin.

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

This class is not invoked if a script is selected for Attribute Mapper Script.

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

Attribute Mapper Script

Specifies the scripted implementation of the Attribute Mapper plugin.

Select from a list of all the Saml2 IDP Attribute Mapper type scripts saved to this realm.

For details of an example script, see saml2-idp-attribute-mapper.js.

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.

To see the profile attributes available for an LDAP identity repository, log in to the AM admin UI, and go to Realms > Realm Name > Identity Stores > User Configuration. Check the LDAP User Attributes list.

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

Example of Static Attribute Mapping. Notice that the static value is enclosed in double quotes.
Account Mapper
Account Mapper

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

Disable NameID Persistence

Disables the storage of the NameID values in the user data store for all NameIDs issued by the IDP instance as long as the NameID format is anything but the persistent NameID format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. That is, you can disable the storage of NameID values with persistent NameID-Format if and only if there is a NameID value mapping set up for the NameID-Format.

By preventing the storage of the NameID values, the ManageNameID and the NameIDMapping SAML profiles will no longer work when using any persistent NameID formats. Existing account links that have been established and stored are not removed when disabling NameID persistence.

Default value: false

Local Configuration
Auth URL

If present, overrides the default UI login URL used to authenticate users during federation.

Use this property to specify an alternative URL for authenticating users, for example, if you have created a custom user interface other than the UI.

The specified authentication URL is responsible for authenticating the federated user and must establish a session in AM, and return the SSO token value in the tenant session cookie name.

To find the name of the session cookie, see How Do I View the Tenant Session Cookie Name?

The domain of the authentication URL must be configured in AM so that the cookie is accepted, and if host cookies are configured in AM, then the fully qualified domain name of the authentication URL must be identical to that of the AM instance.

AM redirects users to the URL specified, and appends a goto parameter. The parameter contains the URL the user must be redirected to after authentication. The specified authentication URL must not override the goto parameter, as that would redirect the user elsewhere and federation will fail.

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.

Services

The following properties appear under the Services tab:

MetaAlias
MetaAlias

Used to locate the provider’s entity identifier, specified as [/realm-name]*/provider-name, where provider-name cannot contain slash characters (kbd:[/]). For example: /myRealm/mySubrealm/idp.

Ensure the MetaAlias is unique for each provider configured in a CoT and in the realm.

IDP Service Attributes
Artifact Resolution Service

Specifies the endpoint to manage artifact resolution. The Index is a unique number identifier for the endpoint.

Single Logout Service

Specifies the endpoints to manage single logout, depending on the SAML binding selected.

Manage NameID Service

Specifies the endpoints to manage name identifiers, depending on the SAML binding selected.

Single SignOn Service

Specifies the endpoints to manage single sign-on.

Assertion ID Request Service

Specifies the endpoints to request for an specific assertion by referring to its assertion ID.

NameID Mapping
URL

Specifies the endpoint to manage name identifier mapping.

Advanced settings

The following properties appear under the Advanced tab:

SAE Configuration
IDP URL

Specifies the endpoint to manage 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 sends a SOAP logout request over the back channel to all service providers when a session times out. A session may time out when the maximum idle time or maximum session time is reached, for example.

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 permitted for the RelayState parameter. For single logout (SLO) operations, AM validates the redirection URL in the RelayState parameter against this list. If the RelayState parameter’s value is in the list, AM allows redirection to the RelayState URL. If it is not in the list, a browser error occurs.

Use the pattern matching rules described in Configure success and failure redirection URLs to specify URLs in the list.

If you DO NOT specify any URLs in this property, AM only allows redirection to RelayState URLs that match the domain of the instance. Any other URL will cause a browser error.

This property does not apply to IDP-initiated single sign-on, where the validation of the RelayState parameter should be performed on the service provider.
IDP Adapter
IDP Adapter Class

Specifies a class to invoke immediately before sending a SAML v2.0 response.

Remote identity provider configuration properties

Once you have set up a remote identity provider, you can configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content

The following properties appear under the Assertion Content tab:

Signing and Encryption
Request/Response Signing

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

Encryption

When selected, the service provider must encrypt NameID elements.

NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign-on.

Basic Authentication
Enabled, User Name, Password

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

Services

The following properties appear under the Services tab:

IDP Service Attributes
Artifact Resolution Service

Specifies the endpoint to manage artifact resolution. The Index is a unique identifier for the endpoint.

Single Logout Service

Specifies the endpoints to manage single logout, depending on the SAML binding selected.

Manage NameID Service

Specifies the endpoints to manage name identifiers, depending on the SAML binding selected.

Single SignOn Service

Specifies the endpoints to manage single sign-on.

NameID Mapping
URL

Specifies the endpoint to manage name identifier mapping.

Hosted service provider configuration properties

Once you have set up a hosted service provider, you can configure it through the AM admin UI by going to > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content

The following properties appear under the Assertion Content tab:

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.

Secret ID and Algorithms
Secret ID Identifier

Specifies an identifier for the secret ID AM uses for this entity provider, when resolving secrets.

For example, when this value is set to demo, the entity provider will use the following secret IDs:

  • am.applications.federation.entity.providers.saml2.demo.signing

  • am.applications.federation.entity.providers.saml2.demo.encryption

If not specified, AM uses the entity provider role-specific, default global secret IDs.

Signing Algorithm

The algorithms the provider can use to sign the request/response attributes selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Digest Algorithm

The digest algorithms the provider can use when signing the requests and responses selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Encryption Algorithm

This field specifies two types of encryption algorithms for the provider:

  • Symmetric algorithms, which the provider can use to encrypt the objects selected in the Encryption group. Select one or more AES algorithms from the drop-down list.

    Default: http://www.w3.org/2001/04/xmlenc#aes128-cbc

  • Asymmetric algorithms, advertised as the provider’s transport key algorithm. When SAML v2.0 token encryption is enabled, hosted providers should use the algorithm the remote provider is advertising when encrypting symmetric encryption keys.

    Select one or more algorithms from the drop-down list:

    Key transport algorithms
NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign-on.

The following diagram shows how the hosted SP decides which of the supported NameID formats is used:

Diagram showing how the hosted SP decides which of the supported NameID formats is used.
Disable NameID Persistence

Disables the storage of NameIDs in the user data store, even if the NameID format is urn:oasis:names:tc:SAML:2.0:nameid-format:persistent in the received assertion and the account mapper has identified the local user.

You may want to disable storage of NameID values if you are using a read-only data store, or an external identity store that does not have the AM identity schemas applied.

When local authentication is utilized for account linking purposes, disabling federation persistence requires end users to authenticate locally for each SAML-based login.

Default value: false

Authentication Context
Mapper

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

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

Authentication Context

Specifies the authentication context classes the SP supports, and any AM authentication mechanisms that are used when an IDP specifies the respective class in a SAML v2.0 authentication request.

  • The Predefined Reference drop-down list specifies the list of context references.

  • The Key drop-down list specifies the authentication mechanism that AM uses when an SP specifies an authentication context class in a SAML v2.0 authentication request.

    Authentication Mechanisms Reference for the Key Drop-down List
    Service

    AM will use the specified authentication chain or tree to authenticate the user.

    For example, in the Value field, enter HmacOneTimePassword to use the built-in one-time password example authentication tree, or ldapService to use the built-in chain that authenticates against the default identity store.

    Module

    AM will use the specified authentication module to authenticate the user.

    Authentication Level

    AM will authenticate the user with a method that has an associated authentication level equal to or higher than the specified value.

    If there is more than one suitable method, AM presents the available options by using a ChoiceCallback.

    For more information on using and returning callbacks during authentication, see Authenticate using REST.

    The Role, User, and Resource URL options are deprecated and should not be used.
  • The Value field specifies the name relative to the authentication mechanism you chose in the previous step. For example, if you chose the Service authentication mechanism, add the name of an authentication tree or chain in the Value field.

  • The Level field specifies the numeric value of precedence of the supported context reference classes.

    Classes with higher numbers are considered stronger than lower numbered classes. The values determine which authentication classes can be used when the SP makes an authentication request that uses a comparison attribute; for example, minimum or better.

    Note that the value in the Level field should match the auth level of the specified chain, module, or tree. For example, if the specified authentication chain sets an auth level of 10, set the same value in the Level field in the Authentication Context table. As AM compares the current auth level against the level specified in Authentication Context table, if the two values do not match, AM may require a logged in user to re-authenticate unnecessarily.

    Example
    Choose the authentication mechanisms AM uses when receiving authentication requests that specify an authentication context class.

    For more information on authentication context classes, see Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.

    Default value: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Comparison Type

Used in conjunction with the Default Authentication Context to specify the possible range of authentication mechanisms the IDP can choose from.

For example, if the Comparison Type field is set to better, and the PasswordProtectedTransport authentication context class is selected in the Default Authentication Context field, the IDP must select an authentication mechanism with a higher level assigned.

Default: exact

Include Request Authentication Context

Specifies whether to include an authentication context class as the Requested Authentication Context in the SAML v2.0 Authentication Request.

Default: Enabled

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

Assertion Processing

The following properties appear under the Assertion Processing tab:

Attribute Mapper
Attribute Mapper

Specifies a class that implements the attribute mapping.

Attribute Map

Maps SAML attributes to session properties, or user profile attributes.

The value of Key is a SAML attribute sent in an assertion, and the value of Value is a property in the user’s session, or an attribute of the user’s profile.

By default, the SP maps the SAML attributes it receives to equivalent-named session properties. However, when the SP is configured to create identities during autofederation and the identity does not exist yet, the SP maps the SAML attributes to their equivalents in the newly-created user profile.

The special mapping Key: *, Value: * means that the SP maps each attribute it receives in the assertion to equivalent-named properties or attributes. For example, if the SP receives mail and firstname in the assertion, it maps them to mail and firstname respectively.

Remove the special mapping and add key pairs to the map if:

  • (During autofederation) The attributes in the IdP’s and the SP’s identity stores do not match.

  • You need control over the names of the session properties.

  • You need control over which attributes the SP should map, because the IdP adds too many to the assertion.

For example, if the the SAML attribute is firstname and you want the SP to map it to a session property/user profile attribute called cn, create a mapping similar to Key: firstname, Value: cn.

Auto Federation
Enabled

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

Attribute

Specifies the SAML 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.

Transient User

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

Artifact Message Encoding
Artifact Message Encoding

Specifies the message encoding format for artifacts.

URL
Local Authentication URL

Use this property to specify an alternative URL to redirect the user to after validating the SAML2 assertion from the IDP; for example, if you have created a custom user interface other than the AM UI.

When in integrated mode, the query parameters are appended to the configured URL. Typically, these parameters contain all the information necessary for AM to continue the authentication journey.

When in standalone mode, AM redirects users to the specified URL, and appends a goto parameter. This parameter contains the URL the user must be redirected to next.

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.

Services

The following properties appear under the Services tab:

MetaAlias
MetaAlias

Used to locate the hosted provider’s entity identifier, specified as [/realm-name]*/provider-name, where provider-name can not contain slash characters (kbd:[/]). For example: /myRealm/mySubrealm/sp.

Ensure the MetaAlias is unique for each provider configured in a CoT and in the realm.

SP Service Attributes
Single Logout Service

Specifies the endpoints to manage single logout, depending on the SAML binding selected.

Manage NameID Service

Specifies the endpoints to manage name identifiers, depending on the SAML binding selected.

Assertion Consumer Service

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

The scheme, FQDN, and port configured must exactly match those of the service provider as they appear in its metadata.

To determine the service provider’s endpoint URL, AM uses the Base URL service, if configured.

If the URL does not match, the SAML v2.0 flow will fail and AM will log Invalid Assertion Consumer Location specified in the audit log file.

Advanced Settings

The following properties appear under the Advanced tab:

SAE Configuration
SP URL

Specifies the endpoint to manage Secure Attribute Exchange requests.

SP Logout URL

Specifies the endpoint 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, AM includes a Scoping element in the authentication request to enable the request to be proxied.

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 sends a SOAP logout request over the back channel to all identity providers when a session times out. A session may time out when the maximum idle time or maximum session time is reached, for example.

Relay State URL List
Relay State URL List

List of URLs permitted for the RelayState parameter. AM validates the redirection URL in the RelayState parameter against this list. If the RelayState parameter’s value is in the list, AM allows redirection to the RelayState URL. If it is not in the list, a browser error occurs.

Use the pattern matching rules described in Configure success and failure redirection URLs to specify URLs in the list.

If you DO NOT specify any URLs in this property, AM only allows redirection to RelayState URLs that match the domain of the instance. Any other URL will cause a browser error.

Remote service provider configuration properties

Once you have set up a remote service provider, you can configure it through the AM admin UI by going to Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content

The following properties appear under the Assertion Content tab:

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.

NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign-on.

Disable NameID Persistence

Disables the storage of NameID values at the IDP when generating an assertion for this remote SP.

Default value: false

Basic Authentication
Enabled, User Name, Password

When enabled, require authentication with the specified user name and password at SOAP endpoints.

Assertion Processing

The following properties appear under the Assertion Processing tab:

Attribute Mapper
Attribute Map

Override any mappings of attributes to user profile attributes at the IDP.

Artifact Message Encoding
Encoding

Specifies the message encoding format for artifacts.

Services

The following properties appear under the Services tab:

SP Service Attributes
Single Logout Service

Specifies the endpoints to manage single logout, depending on the SAML binding selected.

Manage NameID Service

Specifies the endpoints to manage name identifiers, depending on the SAML binding selected.

Assertion Consumer Service

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

Advanced

The following properties appear under the Advanced tab:

Request Processing
Skip Endpoint Validation For Signed Requests

When enabled, AM does not verify Assertion Consumer Service URL values provided in SAML authentication requests. This allows the Assertion Consumer Service URL to contain dynamic query parameters, for example.

As assertion consumer service URL verification is part of the SAML v2.0 spec, you can only skip validation if the authentication request is digitally signed by the SP. To digitally sign authentication requests, in the remote SP configuration go to Assertion Content > Signing and Encryption > Request/Response Signing, and select Authentication Requests Signed.

You must configure the remote SP to sign the authentication request.

AM returns an error if it receives an unsigned authentication request and this option is enabled.

SAE Configuration
SP URL

Specifies the endpoint to manage Secure Attribute Exchange requests.

SP Logout URL

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

IDP Proxy
IDP Proxy enabled

When enabled, the authentication requests from this service provider can be proxied.

Proxy all requests

When enabled, AM proxies every authentication request from the SP, whether it contains a Scoping element or not.

The IDP Proxy option must be enabled for this option to take effect.

Introduction enabled

When enabled, use introduction cookies to find the proxy identity provider.

This property only works with a non-default SAML2IDPProxyFRImpl implementation, and will be deprecated in a future release.

Use IDP Finder

When enabled, use the IDP finder service to determine the IDP to which to proxy authentication requests.

Proxy Count

Specifies the maximum number of proxy identity providers. AM sets the specified value in the Scoping element of authentication request it proxies for this SP.

The Proxy all requests option must be enabled for this option to take effect.

IDP Proxy List

Specifies a list of URIs identifying preferred proxy identity providers.

Circle of trust configuration properties

Once you have set up a circle of trust, you can configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Circle of Trust > Circle of Trust Name.

Name

String to refer to the circle of trust.

Once you have set up a circle of trust, the Name cannot be configured.

Description

Short description of the circle of trust.

Status

Whether this circle of trust is operational.

Entity Providers

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

SAML2 Writer Service URL

SAML v2.0 service that writes identity provider entity identifiers to Common Domain cookies after successful authentication, used in identity provider discovery. Example: https://discovery.example.com:8443/openam/saml2writer.

SAML2 Reader Service URL

SAML v2.0 service that reads identity provider entity identifiers from Common Domain cookies, used in identity provider discovery. Example: https://discovery.example.com:8443/openam/saml2reader.

SAML v2.0 advanced properties

To configure SAML v2.0 advanced properties, in the AM admin UI, go to Configure > Server Defaults > Advanced.

openam.saml.decryption.debug.mode

When enabled, AM decrypts SAML v2.0 messages that are sent and received, and writes the content to the debug logs.

As these messages may contain user information, you should not enable this property in production environments.

Default: False

org.forgerock.openam.saml2.authenticatorlookup.skewAllowance

Specifies the allowable time difference, in seconds, between any existing session the user may have, and the current time when an authentication request specifies ForceAuthn.

If the authenticated user’s session was created outside of the allowable time range, AM rejects the assertion, and re-authentication is required.

Default: 60

Copyright Ā© 2010-2022 ForgeRock, all rights reserved.