Identity Cloud

SAML 2.0

These topics cover concepts, configuration, and procedures for working with the Identity Cloud Security Assertion Markup Language (SAML) 2.0 features.

SAML 2.0

Learn how Identity Cloud support SAML 2.0.
Configure SAML 2.0

Configure Identity Cloud’s SAML 2.0 support under Native Consoles > Access Management.
Configure single sign-on

Enable SAML 2.0 single sign-on (SSO) and single logout (SLO).

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, visit https://www.forgerock.com.

Introduction to SAML 2.0

You configure and set up SAML 2.0 under Native Consoles > Access Management.

SAML 2.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 (IDP). The services are provided by service providers (SP). Both providers are configured to trust one another.

Identity Cloud can serve as the IDP for an SP or it can be the SP for an external IDP (such as Azure AD).

A high-level overview of the SAML 2.0 participants in Identity Cloud.
Figure 1. Overview of SAML 2.0 in Identity Cloud

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

SAML 2.0 concepts

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

Table 1. SAML 2.0 Terminology
Term Description

End user

The person who is attempting to access the resource or application. In SAML 2.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 2.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 Identity Cloud 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 IDP 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 SP has a trust relationship with the IDP, which enables the SP to rely on the assertions it receives from the IDP.

Circle of trust (CoT)

A circle of trust is an Identity Cloud concept that groups at least one IDP and at least one SP who agree to share authentication information.

Metadata

Providers in SAML 2.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 2.0 bindings are supported.

Sharing metadata greatly simplifies the creation of SAML 2.0 providers in a circle of trust. Identity Cloud 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 your tenant, referred to as hosted providers.

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

For more information, refer to Security Assertion Markup Language (SAML) 2.0.

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

When configuring Identity Cloud to provide single sign-on using SAML 2.0, you can:

  • Map accounts from the IDP to accounts in the SP, including mapping to an anonymous user.

  • Make assertions as the IDP to the SP, for example, to attest that the end user has authenticated with the IDP.

    The SP then consumes assertions from the IDP to make authorization decisions, for example to let an authenticated user complete a purchase that gets charged to the user’s account at the IDP.

SAML 2.0 example flow
{saml2_abbr} Flow
Figure 2. SAML 2.0 Flow

  1. An unauthenticated user attempts to access a SAML 2.0 SP.

  2. The SP determines the IDP associated with the end user, and redirects the user’s browser to the IDP, using an HTTP 302 Redirect message. A SAML 2.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 Identity Cloud. Identity Cloud also supports the HTTP-POST binding for processing SAML 2.0 authentication requests.

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

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

    The SP can include particular authentication requirements in the request, for example, to require the user to use multi-factor authentication.

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

    The IDP redirects the end user’s browser to the SP, and includes the SAML Artifact in the query parameters.

    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 Identity Cloud is returning SAML assertions. Identity Cloud also supports the HTTP-POST binding for transmitting SAML 2.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. For more information, refer to Federate identities.

    To link to an existing account, the SP might also need the end user to authenticate to the SP itself, to determine the matching local account. When the accounts are linked, the user only needs to authenticate to the IDP when requesting 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.

Use case: Let staff access Google Workspace

A common use case for SAML 2.0 is to let your internal staff access and use the applications provided by Google Workspace, such as Google Docs and Google Sheets. This section highlights how Identity Cloud provides the solution.

In this scenario, Google acts as the SP, and Identity Cloud acts as the IDP for a hypothetical organization, Example.com.

High-level steps to let staff access Google Workspace applications

  1. An administrative user configures Identity Cloud as the IDP under Native Consoles > Access Management.

  2. The administrative user configures Google Workspace as a remote SP and provides the values that Google needs to use Identity Cloud as its IDP. For example, the login, logout, and profile management URLs, and the validation certificate.

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

  4. When the configuration is complete, users attempting to access a Google Workspace service are 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 Identity Cloud, acting as the IDP:

    Log in to your corporate account at Example.com, with Identity Cloud acting as the IDP.

  6. After successfully authenticating with Identity Cloud the user is redirected back to the Google Workspace 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 Google Workspace apps, by authenticating to Identity Cloud using their corporate Example.com account:

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

Deployment considerations

Before you set up SAML 2.0 in Identity Cloud, you should:

  • Know which providers will participate in circles of trust.

  • Know how tenants act as IDPs or SPs.

  • Define how to map shared user attributes in identity information exchanged with other participants in a circle of trust. Identity Cloud user profile attribute names should map to user profile attribute names at other providers.

    For example, if you exchange user identifiers with a partner, and your Identity Cloud attribute is uid, but the partner’s attribute is userid, you must map uid to the partner’s userid attribute.

  • Agree with other providers on a synchronized time service.

  • Determine whether your session state configuration limits your usage of certain SAML 2.0 profiles. For more information, refer to Session state considerations.

Session state considerations

SAML 2.0 functionality uses a combination of the backend token service and browser-based data to store the progress of SAML 2.0 single sign-on (SSO) operations.

SSO 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 Identity Cloud tenant.

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, refer to WebSettings - setDomStorageEnabled in the Android Developers documentation.

The following table summarizes the high-level tasks required to configure SAML 2.0:

Task Resources

Configure an SP, an IDP, and a CoT

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

For example, if Identity Cloud 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.

Configure IDPs, SPs, and CoTs

Make sure your providers are secure

Configure signing and encryption secrets for your environment.

Sign and encrypt messages

Configure your environment for SSO and SLO

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

Implement SSO and SLO

Decide how to federate identities

Identity Cloud supports different ways to federate identities depending on the configuration, and whether they exist or not in the SP.

Federate identities

Configure IDPs, SPs, and CoTs

This section covers configuration tasks to implement SAML 2.0 in Identity Cloud.

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 Identity Cloud, a hosted provider is one served by the current Identity Cloud tenant, and a remote provider is one hosted elsewhere.

Create a circle of trust

A circle of trust groups at least one IDP and at least one SP who agree to share authentication information.

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Circles of Trust, and click Add Circle of Trust.

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

    Entity providers can be added at any time. This lets you create IDPs or SPs later on and add them.

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

    For information about circle of trust properties, refer to Circle of trust configuration properties.

Create a hosted IDP or SP

A hosted IDP or SP is a provider hosted within Identity Cloud. For example, if Identity Cloud is the authoritative source for users to a downstream application, then you would configure Identity Cloud to be a hosted IDP.

With the new application management, Identity Cloud acts as a hosted IDP through intuitive screens. For more information, refer to Create a custom SAML 2.0 application.

This procedure provides steps for creating a hosted IDP or SP:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Dashboard, and click SAML Applications.

  2. Click Add Entity Provider > Hosted.

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

    Identity Cloud truncates sequences of whitespace with a single whitespace character in values such as entity IDs. For example, if ID value (with one space) exists already, a new entity with the same name but multiple spaces would result in an error because the string values are treated as identical.

    Identity Cloud uses the Entity Provider Base URL value for all SAML 2.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.

    The UI only displays the configuration of a single role. To switch between SP and IDP configuration for a given provider, 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 to local attribute names. The SAML attribute names are the names in an assertion.

    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 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. If you are adding a new attribute map, click Add. If you are updating an existing attribute map, click Update.

  8. Customize any other properties as required, and click Save Changes at the bottom of the screen.

    For in-depth information about hosted IDP and SP properties, refer to:

  9. 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-env-fqdn>/am/saml2/jsp/exportmetadata.jsp\
?entityid=myHostedProvider\
&realm=/mySubRealm"

    If the remote provider has the ability to read the URL (refer to the preceding example), then you can provide the URL to the remote provider, and they can load the metadata that way instead.

Import and configure a remote IDP or SP

A remote IDP or SP is a provider outside of Identity Cloud. For example, Azure AD could be the authoritative source for a user profile in your organization. If that is the case, then Azure AD would be a remote IDP.

The following procedure provides steps for importing and configuring one or more remote IDP or SPs:

  1. Obtain the remote IDP or SP metadata as an XML-formatted file and save it onto the machine where you will be interacting with the Identity Cloud tenant. Each application has different ways to obtain the file.

  2. From the Identity Cloud admin UI, click Native Consoles > Access Management.

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

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

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

      Identity Cloud truncates sequences of whitespace with a single whitespace character in values such as entity IDs. For example, if ID value (with one space) exists already, a new entity with the same name but multiple spaces would result in an error because the string values are treated as identical.

  6. 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. If you have not created a circle of trust, refer to Create a circle of trust.

  7. Click Create.

  8. After you import the metadata, you can edit the configuration of an entity provider. To do this, go to Realms > Realm Name > Applications > Federation > Entity Providers, and select the entity provider to edit.

    The UI only displays the configuration of a single role. To switch between SP and IDP configuration for a given provider, click on the labels to select the role view:

    saml-roles

    For in-depth information about remote entity provider properties, refer to:

Sign and encrypt messages

By default, IDPs and SPs do not sign or encrypt SAML 2.0 messages.

Although this is useful for test and demo environments, secure your production and production-like environments with keys.

For information on how to create and configure keys for signing and encryption in Identity Cloud, refer to TLS, secrets, signing, trust, and encryption

How signing works

When Identity Cloud 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. Identity Cloud 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, Identity Cloud 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 Identity Cloud is unable to find a suitable key, it does not sign the element, and displays an error.

    Possible reasons that Identity Cloud might 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, Identity Cloud uses the default algorithm settings.

  5. Identity Cloud examines the configured signing key type, and uses RSA-SHA256 for RSA keys, DSA-SHA256 for DSA keys, and ECDSA-SHA512 for EC keys.

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

    Identity Cloud determines the correct default query signing algorithm based on the signing key’s algorithm: RSA, DSA, or EC.

    Identity Cloud reverts to the same defaults for XML and query signing algorithms only if 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 encryption works

When encrypting SAML 2.0 messages, the sender uses the receiver’s public key (exposed in the receiver’s metadata) to encrypt the request. The receiver decrypts the request with their private key.

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

Because SAML 2.0 messages are in XML format, the encryption requires an additional key to be transported with the message, as explained in the XML Encryption Syntax and Processing Version 1.1 specification. Identity Cloud 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.

  5. The SP uses the transport key to decrypt the assertion.

This scenario ensures only this SP can decrypt the message.

The following sections explore these topics in detail.

Configure the advertised signing and encryption algorithms

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.

Configure the required signing algorithms and digests:

  1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  2. In Assertion Content > Signing and Encryption > Secret ID And Algorithms:

    • In the Signing Algorithm list, select the signing algorithms this provider can use.

    • In the Digest Algorithm list, select the digest algorithms this provider can use.

      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>

      There is no default for these properties.

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

Configure the required encryption algorithms:

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

    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>

    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 protects better 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

    ✔

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

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

    ✖

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

Configure Identity Cloud to sign and encrypt SAML 2.0 assertion content

Identity Cloud can sign and encrypt the SAML 2.0 assertion content with the following caveats:

Assertions

HTTP-POST bindings require signed assertions.

Failure to enable signing when using HTTP-POST bindings can 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 when using the ForceAuthn flag.

SAML assertion responses

Signing AND encrypting is recommended because responses can contain user data.

SAML logout requests

Signing is recommended to verify the request’s authenticity.

To configure signing and encryption:

  1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

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

    For example, mySamlSecrets.

    How secret identifiers work:

    • Identity Cloud using a 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 Identity Cloud configuration, Identity Cloud 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, Identity Cloud will use the global default secrets relative to the entity provider’s role, in the realm. If they are not mapped, Identity Cloud will search for the global default secrets in the global secret stores.

  3. Save your changes.

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

  4. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  5. On the Assertion Content tab, in the Signing and Encryption section, select the SAML 2.0 elements that Identity Cloud should sign and the elements to encrypt.

  6. Save your changes.

    Identity Cloud now uses the key pairs you configured. For more information on how to create and configure keys for signing and encryption in Identity Cloud, refer to TLS, secrets, signing, trust, and encryption.

Implement SSO and SLO

Within SAML 2.0 you can implement single-sign on (SSO) and single logout (SLO). SSO is a familiar concept; however, SLO is the ability to terminate multiple login sessions by logging out of one central place.

There are two authentication initiations in which SSO can take place:

  • SP-initiated SSO: The SP initiates the login request.

    For example, if a user navigates to the SP first, then the SP directs to the IDP for the login. If the user already has a session on the IDP, then the IDP redirects the user back to the SP with a SAML assertion. If the user does not have a session, they enter their credentials. After a successful login, the user is redirected back to the SP with a SAML assertion. The user is allowed access to the SP application.

  • IDP-initiated SSO: The IDP initiates the login to the SP.

    For example, the user is already logged into the IDP and clicks an application (SP) to access the application. The IDP sends a SAML assertion to the SP. The user is allowed access to the SP application.

Identity Cloud provides two options for implementing single-sign on (SSO) and single logout (SLO) with SAML 2.0:

Integrated mode

Integrated mode SSO and SLO use a SAML2 authentication node on a service provider (SP), thereby integrating SAML 2.0 authentication into the Identity Cloud authentication process. The authentication node handles the SAML 2.0 protocol details for you.

Integrated mode supports SP-initiated SSO only because the authentication service that includes the SAML 2.0 node resides on the SP.

You cannot trigger IDP-initiated SSO in an integrated mode implementation.

Integrated mode does not support SLO.

Standalone mode

Standalone mode requires you invoke JSPs pages to initiate SSO and SLO.

The following table provides information to help you decide whether to implement integrated mode or standalone mode for your Identity Cloud SAML 2.0 deployment:

Table 4. Integrated or standalone mode?
Deployment task or requirement Implementation mode

You want to deploy SAML 2.0 SSO and SLO using the easiest technique.

Use integrated mode.

You want to trigger SAML 2.0 IDP-initiated SSO.

Use standalone mode.

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

Use standalone mode.

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

Use standalone mode.

(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 in integrated mode

Journeys support SSO in integrated mode only via the SAML2 Authentication node. It handles the SAML 2.0 authentication flow but relies on other nodes.

Integrated mode flow (journeys)
{saml2_abbr} Integrated Mode Flow
Figure 4. SAML 2.0 Integrated Mode Flow

  1. An unauthenticated user initiates authentication to an Identity Cloud SAML 2.0 SP. The login URL references a journey that includes a SAML2 Authentication node. For example, https://<tenant-env-fqdn>/am/XUI/?service=mySAM2LTree.

  2. If there are any authentication nodes that precede the SAML2 Authentication node, Identity Cloud 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 requests 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, Identity Cloud searches the identity store, and attempts to locate a user with the same name ID.

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

    If the name ID does not exist...

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

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

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

Implement SAML 2.0 single sign-on in integrated mode

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

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

    For more information, refer to Configure Identity Cloud for integrated mode.

  2. Configuring a journey that contains, at least, the SAML2 Authentication node.

    For more information, refer to Create accounts dynamically during federation.

Configure Identity Cloud for integrated mode

  1. If you haven’t already done so, configure SAML 2.0 by performing the tasks listed in Deployment considerations.

  2. Under Native Consoles > Access Management, create a hosted SP by following the steps in Create a hosted entity provider.

    You must configure the attribute map (Assertion Processing > Attribute Mapper) first. This determines how Identity Cloud maps assertion attributes 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 IDP 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 you created when you created the hosted SP.

  4. Change the Assertion Consumer Service locations in the hosted SP configuration.

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

    Change the locations as follows:

    • Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > SP 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://<tenant-env-sp-fqdn>/am/Consumer/metaAlias/sp, change it to https://<tenant-env-sp-fqdn>/am/AuthConsumer/metaAlias/sp.

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

      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 your journey(s).

Create accounts dynamically during federation

In integrated mode, the SP can use journeys to tailor the authentication experience to the users. You can create multiple complex journeys to satisfy the requirements of your organization.

The example shown in this procedure uses the SAML 2.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 journeys to create persistent links between user accounts.

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

Example journey to create accounts dynamically
Figure 5. Example journey 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 journey’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 journey continues through the Account Exists output. Otherwise, the journey continues through the No Account Exists output.

    The attribute the node uses to map the nameID is not configurable. This example adds nodes to process the userInfo object and matches its contents to the managed user’s schema.

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

    Example script

    • Next-generation

    • Legacy

    if (nodeState.get("userInfo")) {
  if (nodeState.get("objectAttributes")) {
    nodeState.remove("objectAttributes");
  }
  var userName=null,sn=null,mail=null;

  try {
    var attribs = nodeState.get("userInfo")["attributes"];

    userName=attribs["uid"][0];
    sn=attribs["sn"][0];
    mail=attribs["mail"][0];

  } catch (e) {
    logger.error("Error getting userInfo: " + e);
  }
  nodeState.putShared("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
}
action.goTo("true");
    var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

if (nodeState.get("userInfo")) {
  if (nodeState.get("objectAttributes")) {
    nodeState.remove("objectAttributes");
  }
  var userName=null,sn=null,mail=null;

  try {
    var attribs = nodeState.get("userInfo").get("attributes");

    userName=attribs.get("uid").get(0).asString();
    sn=attribs.get("sn").get(0).asString();
    mail=attribs.get("mail").get(0).asString();

  } catch (e) {
    logger.error("Error getting userInfo: " + e);
  }
  nodeState.putShared("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
}
action = fr.Action.goTo("true").build();

    For more information, refer to 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 journey by adding the required nodes to create the new account if it does not exist on the SP.

    The scripted decision node you created before gathering the attributes are now available in the journey’s shared state to create the account; however, these may not be enough to satisfy your managed user rules.

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

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

    For examples, refer to Link identities by using journeys.

Invoke JSPs using standalone mode to initiate SSO and SLO

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

The required module is available by default in Identity Cloud. 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, Identity Cloud SAML 2.0 federation provides JSP files that direct users to do SSO and SLO across providers in a circle of trust. Identity Cloud has two JSPs for SSO and two JSPs for SLO, allowing you to initiate both processes either from the IDP side, or from the SP side.

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

For details of how to use JSPs in an example, refer to 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 SSO from the IDP side. Call this on the IDP not the SP.

Also mapped to the endpoint idpssoinit under the context root.

URLs:

  • https://<tenant-env-fqdn>/am/saml2/jsp/idpSSOInit.jsp

  • https://<tenant-env-fqdn>/am/idpssoinit

Example:

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

    https://<tenant-env-fqdn>/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 SLO from the IDP.

Also mapped to the endpoint IDPSloInit under the context root.

URLs:

  • https://<tenant-env-fqdn>/am/saml2/jsp/idpSingleLogoutInit.jsp

  • https://<tenant-env-fqdn>/am/IDPSloInit

Example:

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

    https://<tenant-env-fqdn>/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 SLO 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, refer to the IDP advanced reference section.

SP-initiated SSO JSP

spSSOInit.jsp

Use this page to initiate SSO from the SP side.

Also mapped to the endpoint spssoinit under the context root.

URLs:

  • https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSSOInit.jsp

  • https://<tenant-env-sp-fqdn>/am/spssoinit

Example:

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

    https://<tenant-env-sp-fqdn>/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 IDP. 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 IDP 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.

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

Identity Cloud saves custom authentication contexts when you save hosted IDP and SP entities, as long as they’re 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 (|) characters.

AuthLevel

(Optional) Use this parameter to specify the authentication level of the authentication context that Identity Cloud 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.

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, refer to the SP advanced 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 : 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://<tenant-env-sp-fqdn>/am/saml2/jsp/spSingleLogoutInit.jsp

  • https://<tenant-env-sp-fqdn>/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://<tenant-env-sp-fqdn>/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 Identity Cloud 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, refer to the SP advanced section.

Use devices to access services

To use devices to access services, for example; simple phones, medical devices, or set-top boxes, use the SAML 2.0 Enhanced Client or Proxy (ECP) profile. This is used because certain devices lack the capabilities needed to use the more widely used SAML 2.0 Web Browser SSO profile.

The ECP knows which IDP to contact for the user, and is able to use the reverse SOAP (PAOS) SAML 2.0 binding for the authentication request and response.

The PAOS binding uses HTTP and SOAP headers to pass information about processing SOAP requests and responses, starting with a PAOS HTTP header that the ECP sends in its initial request to the server. The PAOS messages continue with a SOAP authentication request in the server’s HTTP response to the ECP’s request for a resource, followed by a SOAP response in an HTTP request from the ECP.

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

Identity Cloud supports the SAML 2.0 ECP profile on the server side for IDPs and SPs.

You must build the ECP:

  • By default, an Identity Cloud IDP 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 Identity Cloud cookies as it would for any other client application.

    If you must change the mapping after writing and installing your own session mapper, go to Native Consoles > Access Management > Realms > Realm Name, then select Applications > Federation > Entity Providers > IDP Name > IDP > Advanced > ECP Configuration.

  • By default, an Identity Cloud SP uses the com.sun.identity.saml2.plugins.ECPIDPFinder class to return the IDP from the list of IDP entity IDs.

    You populate this list under Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > SP Name > SP > Advanced > ECP Configuration > Request IDP List.

  • The endpoint for the ECP to contact on the Identity Cloud SP is /SPECP as in https://<tenant-env-sp-fqdn>/am/SPECP.

  • The ECP provides two query string parameters to identify the SP and to specify the URL of the resource to access:

    metaAlias

    This specifies the SP 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 SP followed by the resource at https://forgerock.org/index.html, use https://<tenant-env-sp-fqdn>/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, refer to the services section.

Federate identities

Federation in SAML 2.0 is a necessary step that provides a seamless SSO experience to users. Federation is the agreement between an Identity provider (IDP) and one or more Service providers (SPs) to use the same standard. This allows the IDP and SP to share information in a trusted manner within a circle of trust.

Refer to the following table for a list of tasks to configure how Identity Cloud federates identities

Task Resources

Decide whether to permanently link identities

Identity Cloud 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 Identity Cloud 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 Identity Cloud 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 Identity Cloud to link an identity in the IDP temporarily. For example, to link the anonymous user in the SP.

For a list of frequently asked questions, refer to the knowledge base article FAQ: SAML 2.0 federation in Identity Cloud.

Choose persistent or transient federation

In Identity Cloud, there are two ways to federate users with SAML 2.0:

  • Permanently link identities with persistent federation.

    Persistent federation requires an attribute value that is the same on the IDP and the SP; for example, an email address or another unique user identifier. Use this method to link accounts without user interaction.

    For more information, refer to Link identities automatically based on an attribute value.

    When accounts are persistently linked, authentication is required only by the IDP. Authentication is required on the SP side if the SP is unable to map the identity in the assertion from the IDP to a local user account. This can happen the first time accounts are linked, for example, after which the persistent identifier establishes the mapping. When the mapping is established, authentication is required only by the IDP.

  • Maintain no user account on the SP with transient federation.

    Transient federation can be useful when the SP needs no user-specific account to provide a service or when you do not want to retain a user profile on the SP, but you make authorization decisions based on attribute values from the IDP.

    When accounts are transiently linked, authentication to the SP might be required.

    The SP must authenticate the user for every SAML assertion received. This is due to the identifier being used to link identities in a transient way. It doesn’t provide a repeatable, durable means to link the identities.

You can prevent the ability to link accounts persistently.

For an SP, set the Disable NameID Persistence property to true in the NameID Format section of the Assertion Content tab. For more information, refer to SP assertion content.

For an IDP, set the Disable NameID Persistence to true in the Account Mapper section of the Assertion processing tab. For more information, refer to IDP assertion processing.

Once you choose how you federate users, enable persistent or transient federation.

Enable persistent federation

For more information on persistent federation, refer to Choose persistent or transient federation.

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

Before you configure persistent federation, ensure you:

Integrated mode

To enable persistent federation with integrated mode:

  1. Create a journey that contains the SAML2 Authentication node.

    Refer to SSO and SLO in Integrated Mode for an example.

  2. In the NameID Format field of the SAML2 Authentication node, specify the value urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

    You can link accounts 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 displays the login page to identify the local user account and persistently link the two accounts.

  3. Save your work.

  4. Initiate SSO by accessing a URL that calls an journey that includes the SAML2 Authentication node.

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

Standalone mode

To enable persistent federation with standalone mode:

  1. Initiate SSO with 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 SSO from the SP, access a URL similar to the following:

    https://<tenant-env-sp-fqdn>/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 SSO from Identity Cloud acting as the IDP, access a URL similar to the following:

    https://<tenant-env-fqdn>/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

Test your work

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

    On success, you are redirected to the SP.

    If there was no login page displayed at the SP, you might have enabled auto-federation, or Identity Cloud 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 SSO again, authenticating to the IDP as the new user.

  2. 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 only requires the user authenticates to the IDP, as the identities are now permanently linked.

    You can prevent the ability to persistently link accounts.

    For an SP, set the Disable NameID Persistence property to true in the NameID Format section of the Assertion Content tab. For more information, refer to SP assertion content.

    For an IDP, set the Disable NameID Persistence to true in the Account Mapper section of the Assertion processing tab. For more information, refer to IDP assertion processing.

Manage persistent federation

When using persistent federation, you can configure and manage the federation of the persistently linked accounts.

Identity Cloud implements the SAML 2.0 Name Identifier Management profile, which allows you to change a persistent identifier set to federate accounts, as well as terminate federation for an account.

Name identifier information from identities are stored in the sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey attributes of a user’s entry.

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

When setting parameters in the JSPs, make sure the parameter values are correctly URL-encoded.
Table 5. idpMNIRequestInit.jsp parameters
Parameter Description

spEntityID

(Required) Indicate the remote SP. 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) 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 IDP and the SP.

SPProvidedID

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

affiliationID

(Optional) Specify a SAML affiliation identifier.

binding

(Optional) 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) 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.
Table 6. spMNIRequestInit.jsp parameters
Parameter Description

idpEntityID

(Required) Indicate the remote IDP. 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) 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 IDP and the SP.

IDPProvidedID

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

affiliationID

(Optional) Specify a SAML affiliation identifier.

binding

(Optional) 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) 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

To 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://<tenant-env-fqdn>/am|
    https://<tenant-env-sp-fqdn>/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://<tenant-env-sp-fqdn>/am|
    https://<tenant-env-fqdn>/am|
    ATo9TSA9Y2Ln7DDrAdO3HFfH5jKD|
    https://<tenant-env-fqdn>/am|
    urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|
    9B1OPy3m0ejv3fZYhlqxXmiGD24c|
    https://<tenant-env-sp-fqdn>/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://<tenant-env-sp-fqdn>/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://<tenant-env-fqdn>/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

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

The following examples work in an environment where the IDP is www.idp.example and the SP is www.sp.example.

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

    https://<tenant-env-sp-fqdn>/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 IDP, access the following URL with at least the query parameters shown:

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

Enable transient federation

For more information on transient federation, refer to Choose persistent or transient federation.

Both integrated and standalone SAML 2.0 implementations let you link accounts temporarily (transiently).

Before you configure transient federation, ensure you:

Integrated mode

To enable transient federation with integrated mode:

  1. Create a journey that contains the SAML2 Authentication node.

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

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

  3. Save your work.

  4. Initiate SSO by accessing a URL that calls a journey that includes the SAML 2.0 node:

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

Standalone mode

To enable transient federation with standalone mode:

  1. Initiate SSO with 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 SSO from the SP, access a URL similar to the following:

    https://<tenant-env-sp-fqdn>/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 SSO from the IDP, access a URL similar to the following:

    https://<tenant-env-fqdn>/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

Test your work

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

    On success, you are redirected to the SP.

  2. Authenticate to the SP as the local user.

    The accounts are only linked 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 the IDP and the SP.

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

Link identities automatically with auto-federation

Before linking identities, you must first choose between persistent or transient federation.

Identity Cloud lets you configure the SP to link identities automatically, based on an attribute value in the assertion returned from the IDP. This process is called auto-federation.

When the identities on both the IDP and the SP share a common attribute value, such as an email address or other unique user identifier, you can configure Identity Cloud to map the attributes to each other and link identities. The user doesn’t authenticate to the SP.

Link identities automatically based on an attribute value

You can automatically link identities based on an attribute value that is the same in both the IDP and the SP.

Before you configure auto-federation, ensure that you:

For an overview of the tasks listed above, refer to Deployment considerations.

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

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers, and click on the name of the hosted provider.

    Identity Cloud only displays the configuration of a single role.

    To switch between an IDP and SP configuration for a given provider, select the role to 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 sends these attributes in the assertion, and the SP maps them using its own attribute map.

      The default IDP mapping implementation lets you 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. 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 auto-federation and the identity doesn’t 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 auto-federation the attributes in the IDP and 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 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 SSO; for example, as described in IDP-Initiated SSO JSP.

    Authenticate to the IDP as an existing 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

In many instances there isn’t 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, then there is no way to link from the IDP to the SP.

You can configure Identity Cloud to to create an account dynamically 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 you configure auto-federation to create identities based on attribute values:

To create missing identities on the SP dynamically:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers, and click on the name of the hosted provider.

    Identity Cloud only displays the configuration of a single role.

    To switch between an IDP and SP configuration for a given provider, select the role to 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, add them.

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

      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. 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. 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. 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 auto-federation and the identity doesn’t 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 auto-federation the attributes in the IDP and 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 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 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, refer to User profile.

    • Save your work.

  4. To test your work:

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

    • Log out of the 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://<tenant-env-sp-fqdn>/enduser/?realm=realm_name/profile and click Edit Personal Info to see the new user account created on the SP, and the attributes that were copied from the assertion.

Link identities for authentication

IDPs and SPs must be able to communicate about users. Yet, in some cases, the IDP 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.

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

First authentication to the SP

The following list describes the sequence of events that occurs the first time a user attempts to authenticate to the Identity Cloud SP:

  1. Accessing the SP.

    A user attempts to access a service and is redirected to Identity Cloud which acts as the SP, specifying the SAML 2.0 service in the login URL.

    For example, a journey containing the SAML2 Authentication node:

    https://<tenant-env-sp-fqdn>/am/XUI/#login/&service=spSAMLJourney

  2. Authentication at the IDP.

    Identity Cloud redirects the user to the IDP. The user authenticates successfully to the IDP. The IDP returns a SAML assertion to the SP.

  3. SP attempts to access a federated identity.

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

  4. Authenticating the user to the SP

    Identity Cloud goes through a path in the journey that lets the user authenticate on the SP.

  5. Identity federation.

    After successful authentication at the SP, Identity Cloud 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, refer to Enable persistent federation.

    For an example of a journey that links identities, refer to SSO and SLO in Integrated Mode.

Subsequent authentications to the SP

The following list describes the sequence of events that occur during subsequent authentication attempts, after the user’s identities on the IDP and SPs have been federated:

  1. Accessing the SP.

    A returning user attempts to access their service and is redirected to Identity Cloud, which acts as the SP. Their login URL specifies the SAML 2.0 login service.

    For example, a journey containing the SAML2 Authentication node and the Write Federation Information node:

    https://<tenant-env-sp-fqdn>/am/XUI/#login/&service=spSAMLJourney.

  2. Authentication at the IDP.

    Identity Cloud redirects the user to the IDP, and the user authenticates successfully at the IDP. The IDP returns a SAML assertion to the SP.

  3. SP attempts to access a federated identity.

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

    When 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 journey, similar to the following, to link accounts persistently:

Example journey to link accounts persistently

  1. Add a SAML2 Authentication node.

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

    Ensure the NameID Format specified is persistent.

    The node processes the assertion, makes its contents available to the journey’s shared 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 journey continues through the Account Exists output. Otherwise, the journey continues through the No Account Exists output.

    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 journey’s shared state.

    Example script

    • Next-generation

    • Legacy

    if (nodeState.get("userInfo")) {
  if (nodeState.get("objectAttributes")) {
    nodeState.remove("objectAttributes");
  }
  var userName=null,sn=null,mail=null;

  try {
    var attribs = nodeState.get("userInfo")["attributes"];

    userName=attribs["uid"][0];
    sn=attribs["sn"][0];
    mail=attribs["mail"][0];

  } catch (e) {
    logger.error("Error getting userInfo: " + e);
  }
  nodeState.putShared("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
}
action.goTo("true");
    var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

if (nodeState.get("userInfo")) {
  if (nodeState.get("objectAttributes")) {
    nodeState.remove("objectAttributes");
  }
  var userName=null,sn=null,mail=null;

  try {
    var attribs = nodeState.get("userInfo").get("attributes");

    userName=attribs.get("uid").get(0).asString();
    sn=attribs.get("sn").get(0).asString();
    mail=attribs.get("mail").get(0).asString();

  } catch (e) {
    logger.error("Error getting userInfo: " + e);
  }
  nodeState.putShared("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
}
action = fr.Action.goTo("true").build();

    For more information, refer to Scripted decision node API functionality.

  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 is converted into a persistent one.

Link identities to a single, shared account

Identity Cloud lets you map identities on the IDP temporarily to a single account on the SP (for example, the anonymous account). This lets you exchange attributes about the user without a user-specific account on the SP.

This approach is useful when the SP doesn’t need a user-specific account to provide a service, or when you don’t want to create or retain identity data on the SP, but you must make authorization decisions based on attribute values from the IDP.

Before you configure identities to link to a single account, ensure you:

Perform the following steps:

  1. On the hosted IDP:

    • Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP Name.

    • On the Assertion Processing tab, if the attributes you want to access from the SP aren’t 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 SP:

    • Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted SP Name.

    • On the Assertion Processing tab, if the attributes you want to access from the IDP are not 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.

    • In the Auto Federation section, ensure that Enabled is not selected.

    • In the Account Mapper > Transient User property, add the account name Identity Cloud 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 IDP, including values for any attributes you mapped in the providers.

    • Log out of the 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 UI of the SP.

      • Go to Realms > Realm Name > Sessions.

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

        The sessions of users who initiated SSO and who are temporarily linked to the transient user account display.

Customize SAML 2.0

Identity Cloud lets you extend SAML 2.0 functionality with scripts:

Script type Description

Use IDP attribute mapper to map user-configured attributes to SAML attributes

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

Use IDP adapter to alter authentication request processing

Customize SAML responses and browser redirects.

Use SP adapter to alter authentication request processing

Customize configuration in the hosted SP adapter environment.

Use IDP attribute mapper to map user-configured attributes to SAML attributes

Use this script type to map user-configured attributes to SAML attributes into the generated SAML assertion.

The default implementation retrieves the mapped attribute values from the user profile first. If the attribute values are missing from the user’s profile, then Identity Cloud attempts to retrieve them from the user’s session.

For a template script, refer to saml2-idp-attribute-mapper.js.

Demonstrate an IDP attribute mapper

Before you try the example, configure single sign-on using SAML v2.0 with Identity Cloud as the hosted IDP.

The following example modifies the SAML attributes in the assertion returned by the IDP:

Create the script

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Scripts, click + New Script, add these settings, and click Create:

    Name

    A unique name for your script

    Script Type

    Scroll down to select Saml2 IDP Attribute Mapper

  2. In the Script text field for the new script, paste the template saml2-idp-attribute-mapper.js script.

  3. Insert the following lines just before return attributes; around line 150 to return a custom static attribute:

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

  4. Click Validate, make any necessary corrections, and click Save Changes.

Configure the IDP

  1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted IDP Name > Assertion Processing.

  2. In the Attribute Mapper Script field, select your script.

  3. Save your changes.

Test the script

  1. Perform a SAML v2.0 flow.

  2. Verify the AttributeStatement element in the SAML assertion contains the custom attribute:

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

Available objects

Identity Cloud injects the following objects into the execution context of an IDP attribute mapper script:

Binding Information

hostedEntityId

The entity ID for the hosted IDP.

idpAttributeMapperScriptHelper

An object with methods for IDP attribute mapping. For details, refer to IdpAttributeMapperScriptHelper.

logger

Write a message to the Identity Cloud am-core log source. The logger identifier takes the form scripts.script-type.script-id. For details, refer to Debug.

realm

The realm the user authenticates to.

remoteEntityId

The remote entity ID.

session

Represents the user’s single sign-on session object. For details, refer to SSOToken.

Use IDP adapter to alter authentication request processing

Use this script type to alter the processing of the authentication request; for example, redirect the user before single sign-on, or before sending a failure response.

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

Processing phase Description

preSingleSignOn

Invoked when Identity Cloud receives the authentication request. Only applicable to SP-initiated flows.

preAuthentication

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

preSendResponse

Invoked after the user successfully authenticates or makes the request with an existing valid session, and before the response is sent.

preSignResponse

Invoked after Identity Cloud prepares the response, but before it signs the response. This lets you customize the content of the SAML response.

preSendFailureResponse

Invoked before Identity Cloud returns a SAML error response. Only applicable to SP-initiated flows.

For a template script, refer to saml2-idp-adapter.js.

Demonstrate an IDP adapter

Before you try the example, configure single sign-on using SAML v2.0 with Identity Cloud as the hosted IDP.

The following example determines whether to redirect the authentication journey based policy evaluation:

Configure a policy

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Authorization > Resource Types and create a new resource type with the following settings:

    Name

    SAML SP Access

    Pattern

    *

    Action

    Assert (Default State: Deny)

  2. Go to Policy Sets and create a new policy set with the following settings:

    Id

    saml

    Name

    saml

    Resource Types

    SAML SP Access

  3. Add a new policy with the following settings:

    Name

    SAML Access Policy

    Resource Types

    SAML SP Access

    Resources

    *

    Actions

    ASSERT:Denied

    Response Attributes

    redirect_uri: https://example.com

    Subjects

    "type": "AuthenticatedUsers"

Create the script

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Scripts, click + New Script, add these settings, and click Create:

    Name

    A unique name for your script

    Script Type

    Scroll down to select Saml2 IDP Adapter

  2. In the Script text field for the new script, paste the template saml2-idp-adapter.js script.

  3. Insert the following code in the preSendResponse function. The script causes Identity Cloud to redirect or send an error response if the policy for the SP evaluates to false:

    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);
  }
}

  4. Click Validate, make any necessary corrections, and click Save Changes.

Configure the IDP

  1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted IDP Name > Advanced.

  2. In the IDP Adapter Script field, select your script.

  3. Save your changes.

Test the script

  1. Perform an SP-initiated flow.

  2. Verify the user is redirected to the redirect_uri from the policy (https://example.com).

Available objects

Identity Cloud injects the following objects into the execution context of an IDP adapter script:

Binding Information

authnRequest

The original authentication request from the SP. For details, refer to AuthnRequest.

Not available to the preSendFailureResponse function.

faultCode

The fault code in the SAML response.

Only available to the preSendFailureResponse function.

faultDetail

The details of the fault in the SAML response.

Only available to the preSendFailureResponse function.

hostedEntityId

The entity ID for the hosted IDP.

idpAdapterScriptHelper

An object with methods to provide context when customizing the IDP adapter plugin points. For details, refer to IdpAdapterScriptHelper.

logger

Write a message to the Identity Cloud am-core log source. The logger identifier takes the form scripts.script-type.script-id. For details, refer to Debug.

realm

The realm the user authenticates to.

relayState

A String representing the relayState in the redirect.

Not available to the preSingleSignOn or preSendFailureResponse functions.

reqId

The identifier to continue processing if the adapter redirects.

Not available to the preSignResponse or preSendFailureResponse functions.

request

The HttpServletRequest object.

res

The SAML response. For details, refer to Response.

Only available to the preSignResponse function.

response

The HttpServletResponse object.

Not available to the preSignResponse function.

session

Represents the user’s single sign-on session object. For details, refer to SSOToken.

Not available to the preSingleSignOn or preSendFailureResponse functions.

Use SP adapter to alter authentication request processing

Use this script type to make application-specific changes during the processing of the authentication request on the SP side, such as updating the SPNameQualifier attribute.

The script provides hooks at the following points:

Processing phase Description

preSingleSignOnRequest

Invoked before Identity Cloud sends the single sign-on request to the IDP.

preSingleSignOnProcess

Invoked before single sign-on processing begins on the SP side, when Identity Cloud receives the response from the IDP.

postSingleSignOnSuccess

Invoked when single sign-on processing succeeds.

postSingleSignOnFailure

Invoked when single sign-on processing fails.

postNewNameIDSuccess

Invoked when the processing of a new name identifier succeeds.

postTerminateNameIDSuccess

Invoked when the association of a name identifier between an SP and IDP is successfully terminated.

preSingleLogoutProcess

Invoked before the single logout process starts on the SP side, while the user session is still valid.

postSingleLogoutProcess

Invoked after the single logout process succeeds, when the user session has been invalidated.

Demonstrate an SP adapter

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

Complete the following steps to implement an example SP adapter script that updates the SPNameQualifier attribute in the authentication request:

Create the script

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Scripts, and click +New Script.

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

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

  4. In the Script field, add code to the preSingleSignOnRequest function to change the value of SPNameQualifier in the authentication request. Optionally, add code to redirect a successful login in the postSingleSignOnSuccess function.

    For example:

    function preSingleSignOnRequest() {
  logger.error("In preSingleSignOnRequest");
  authnRequest.getNameIDPolicy().setSPNameQualifier("mySP-Updated");
}

function postSingleSignOnSuccess() {
    logger.error("In postSingleSignOnSuccess");
    response.sendRedirect("https://example.com");
    return true;
}

  5. Validate and save your changes.

Configure the SP

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted SP Name > Assertion Processing.

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

  3. Save your changes.

Test the script

  1. Test your changes using an SP-initiated flow.

  2. Verify that the SAML2.0 request contains the updated value (SPNameQualifier="mySP-Updated") and that the user is redirected to https://example.com on successful login.

Available objects

Identity Cloud injects the following objects into the execution context of an SP adapter script:

Binding Information

authnRequest

The original authentication request sent from the SP.

Only available to single sign-on functions.

Refer to AuthnRequest.

binding

The binding used for the name identifier request: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect or urn:oasis:names:tc:SAML:2.0:bindings:SOAP

Not available to single sign-on functions.

failureCode

The failure code associated with the error that has occurred.

Possible values
Constant Value

SUCCESS

0

INVALID_RESPONSE

1

FEDERATION_FAILED_WRITING_ACCOUNT_INFO

3

SSO_FAILED_SESSION_ERROR

4

SSO_FAILED_ATTRIBUTE_MAPPING

5

SSO_FAILED_NO_USER_MAPPING

6

SSO_FAILED_AUTH_USER_INACTIVE

7

SSO_FAILED_AUTH_USER_LOCKED

8

SSO_FAILED_AUTH_ACCOUNT_EXPIRED

9

SSO_FAILED_SESSION_GENERATION

10

SSO_FAILED_META_DATA_ERROR

11

Only available to preSendFailureResponse.

hostedEntityId

The entity ID for the hosted IDP.

idpEntityID

The identifier of the IDP for which the sign-on request is sent.

idRequest

The ManageNameIDRequest object for the name identifier request.

Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

idResponse

The ManageNameIDResponse object for the name identifier request.

Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

isFederation

A boolean indicating whether federation is used, otherwise false.

Only available to the postSingleSignOnSuccess function.

logger

Write a message to the Identity Cloud am-core log source. The logger identifier takes the form scripts.script-type.script-id. For details, refer to Debug.

logoutRequest

The single logout LogoutRequest.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

logoutResponse

The single logout LogoutResponse.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

out

The PrintWriter for writing to.

Only available to postSingleSignOnSuccess.

profile

The protocol profile used: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact or urn:oasis:names:tc:SAML:2.0:bindings:PAOS.

Available to preSingleSignOnProcess, postSingleSignOnSuccess, and postSingleSignOnFailure.

realm

The realm the user authenticates to.

request

The HttpServletRequest object.

Always present.

response

The HttpServletResponse object.

Always present.

Session

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

Refer to the SSOToken interface for information about SSO token and authentication information, as well as session-related properties.

Only available to postSingleSignOnSuccess.

SpAdapterScriptHelper

The SpAdapterScriptHelper object contains supporting methods that provide context information when customizing the SP adapter plugin points.

Always present.

SsoResponse

The SSO response received from the IDP.

Available to preSingleSignOnProcess, postSingleSignOnSuccess, and postSingleSignOnFailure.

userId

The unique universal ID of the user associated with the request.

Not available to single sign-on functions.

Reference

This reference covers the configuration settings for identity providers (IDPs), service providers (SPs), and circles of trust.

Hosted identity provider

To edit hosted IDP settings, go to Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content tab

Signing and Encryption
Request/Response Signing

The parts of messages the IDP requires the SP to sign digitally.

Encryption

When NameID Encryption is selected, the SP must encrypt name identifier (NameID) elements.

Secret ID and Algorithms
Secret ID Identifier

By default, Identity Cloud uses the entity provider’s role-specific, default global secret IDs. Alternatively, set an identifier for the secret ID Identity Cloud uses for this entity provider when resolving secrets. For example, when you set this to demo, the entity provider uses the following secret IDs:

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

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

Signing Algorithm

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

The provider’s metadata extension lists these algorithms.

This property has no default.

Digest Algorithm

The digest algorithms the provider uses to sign the requests and responses selected in the Request/Response Signing group.

The provider’s metadata extension lists these algorithms.

This property has no default.

Encryption Algorithm

There are two types of encryption algorithms for the provider:

  • Symmetric algorithms; the provider uses these 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; the provider advertises this as the transport key algorithm. When SAML 2.0 token encryption is enabled, hosted providers should use the algorithm the remote provider advertises to encrypt symmetric encryption keys.

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

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

    • http://www.w3.org/2009/xmlenc11#rsa-oaep

      For this algorithm, Identity Cloud uses http://www.w3.org/2009/xmlenc11#mgf1sha256 to create the transport key.

    • http://www.w3.org/2001/04/xmlenc#rsa-1_5

      For security reasons, do not use this option.

NameID Format
NameID Format List

Supported NameIDs for users shared between providers for single sign-on (SSO).

The following diagram shows how the hosted IDP determines which NameID format to use:

How the hosted IDP decides which NameID formats to use
NameID Value Map

Map of NameID formats to user profile attributes. You do not need to map the persistent and transient NameIDs.

NameID mapping supports Base64-encoded binary values. When Binary is enabled, Identity Cloud Base64-encodes the profile attribute it adds to the assertion.

Authentication Context
Mapper

A class implementing the IDPAuthnContextMapper interface to set up the authentication context.

Do not edit this field.

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

Authentication Context

The supported authentication context classes and any authentication mechanisms Identity Cloud uses when an SP specifies the class in a SAML 2.0 authentication request. For details, refer to Authentication Context for the OASIS Security Assertion Markup Language (SAML) v2.0.

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

  • The Predefined Reference specifies the list of context references.

  • The Key specifies the authentication mechanism Identity Cloud uses when an SP specifies the class in a SAML 2.0 authentication request:

    Service

    Set the Value to the authentication journey to use.

    Module

    Not supported.

    User

    Not supported.

    Role

    Not supported.

    Authentication Level

    Identity Cloud uses a method where the authentication level is greater than or equal to the Value. Match the Value field with the Level field to avoid requiring users to re-authenticate unnecessarily.

    If more than one suitable method exists, Identity Cloud presents the available options with a ChoiceCallback.

  • The Value depends on the Key.

  • The Level specifies precedence for supported context reference classes.

    Higher numbers are stronger than lower numbers.

Assertion Time
Not-Before Time Skew

Grace period in seconds for the NotBefore time in assertions.

Effective Time

Assertion validity in seconds.

Basic Authentication
Enabled, User Name, Password

When enabled, authenticate with the specified credentials at SOAP endpoints.

Assertion Cache
Enabled

When enabled, cache assertions.

Assertion Processing tab

Attribute Mapper

Extension point to map the IDP attributes included in the SAML assertion.

Attribute Mapper

The Java class for the default implementation, which retrieves attributes from the user profile. If the attributes are not present in the profile, retrieve attributes from the user session.

Do not edit this field. It is not used if Attribute Mapper Script is set.

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

Attribute Mapper Script

A JavaScript implementation of an attribute mapper.

Select a Saml2 IDP Attribute Mapper script from this realm.

For an example, refer to saml2-idp-attribute-mapper.js.

Attribute Map

Maps SAML attributes to user profile attributes or session properties.

The default implementation also supports static values. Enclose the profile attribute name in double quotes ("):

The static value is enclosed in double quotes.
Account Mapper
Account Mapper

The Java class for the default implementation to map remote users to local user profiles.

Disable NameID Persistence

By default, Identity Cloud stores NameIDs the IDP issues when the NameID format is persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent). When you set this, Identity Cloud no longer stores persistent NameIDs.

Only enable this setting after configuring a NameID Value Mapping for persistent NameIDs; otherwise, the ManageNameID and the NameIDMapping SAML profiles no longer work with persistent NameIDs.

Identity Cloud does not remove existing, stored account links when you enable this setting.

Local Configuration
Auth URL

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

Use this setting, for example, if you have created a custom UI for federation.

The application exposing the URL must authenticate federated users, establish their sessions, and return SSO tokens in the tenant session cookies.

Identity Cloud must accept the cookie for the domain of the URL. If Identity Cloud uses host cookies, the FQDN of the URL must match your tenant’s FQDN.

Identity Cloud redirects users to the URL, appending a goto parameter. The parameter contains the URL to redirect to after authentication. The application must not override the goto parameter, as changing it causes federation to fail. For details, refer to Success and failure redirection URLs.

Reverse Proxy URL

The URL of the reverse proxy for SAML endpoints if one exists.

External Application Logout URL

The URL to send an HTTP POST with all cookies when receiving a logout request. Add a user session property by including it as a query string parameter named appsessionproperty.

Services tab

MetaAlias

Read-only alias to locate the provider’s entity identifier, specified as /realm-name/provider-name; for example: /alpha/myIDP.

IDP Service Attributes
Artifact Resolution Service

The endpoint to manage artifact resolution.

Single Logout Service

The endpoints to manage single logout (SLO) depending on the SAML binding.

Manage NameID Service

The endpoints to manage NameIDs depending on the SAML binding.

Single SignOn Service

The endpoints to manage SSO.

These endpoints are used only for SP-initiated flows but are included as a requirement of the SAML V 2.0 Metadata specification.

NameID Mapping

The endpoint to manage NameID mapping.

Assertion ID Request Service

The endpoints to request a specific assertion by assertion ID.

Advanced tab

SAE Configuration
IDP URL

The endpoint to manage Secure Attribute Exchange (SAE) requests.

Application Security Configuration

Encryption settings for SAE.

ECP Configuration
IDP Session Mapper

A Java class to find a valid session in an HTTP servlet request to an IDP with a SAML Enhanced Client or Proxy (ECP) profile.

Do not edit this field.

Session Synchronization
Enabled

When enabled, the IDP sends backchannel SOAP logout requests to all SPs when a session times out. A session can time out after the maximum idle time or maximum session time, for example.

IDP Finder Implementation
IDP Finder Implementation Class

A Java class to find the preferred IDP for a proxied authentication request.

IDP Finder JSP

A JSP to present the list of IDPs to the user.

Enable Proxy IDP Finder For All SPs

When enabled, Identity Cloud applies the finder for all remote SPs.

Relay State URL List
Relay State URL List

List of accepted RelayState URLs.

Identity Cloud validates the RelayState redirection URLs against this list during SLO. Identity Cloud only allows redirection to RelayState URLs in this list or matching the tenant domain; otherwise, a browser error occurs.

This setting does not apply to IDP-initiated SSO as the SP validates the RelayState URL.

Use the pattern matching rules in Success and failure redirection URLs to specify URLs.

IDP Adapter
IDP Adapter Class

A Java class Identity Cloud invokes immediately before sending a SAML 2.0 response.

IDP Adapter Script

A JavaScript implementation of an IDP adapter.

Select a Saml2 IDP Adapter script from this realm.

For an example, refer to saml2-idp-adapter.js.

Remote identity provider

To edit remote IDP settings, go to Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content tab

Signing and Encryption
Request/Response Signing

The parts of messages the IDP requires the SP to sign digitally.

Encryption

When selected, the SP must encrypt NameID elements.

NameID Format
NameID Format List

Supported NameIDs for users shared between providers for single sign-on (SSO).

Basic Authentication
Enabled, User Name, Password

When enabled, authenticate with the specified credentials at SOAP endpoints.

Services tab

IDP Service Attributes
Artifact Resolution Service

The endpoint to manage artifact resolution.

Single Logout Service

The endpoints to manage SLO depending on the SAML binding.

These endpoints are used only for SP-initiated flows but are included as a requirement of the SAML V 2.0 Metadata specification.

Manage NameID Service

The endpoints to manage NameIDs depending on the SAML binding.

Single SignOn Service

The endpoints to manage SSO.

NameID Mapping
URL

The endpoint to manage NameID mapping.

Hosted service provider

To edit hosted SP settings, go to Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content tab

Signing and Encryption
Request/Response Signing

The parts of messages the SP requires the IDP to sign digitally.

Encryption

When selected, the IDP must encrypt the selected elements.

Secret ID and Algorithms
Secret ID Identifier

By default, Identity Cloud uses the entity provider’s role-specific, default global secret IDs. Alternatively, set an identifier for the secret ID Identity Cloud uses for this entity provider when resolving secrets. For example, when you set this to demo, the entity provider uses the following secret IDs:

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

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

Signing Algorithm

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

The provider’s metadata extension lists these algorithms.

This property has no default.

Digest Algorithm

The digest algorithms the provider uses to sign the requests and responses selected in the Request/Response Signing group.

The provider’s metadata extension lists these algorithms.

This property has no default.

Encryption Algorithm

There are two types of encryption algorithms for the provider:

  • Symmetric algorithms; the provider uses these 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; the provider advertises this as the transport key algorithm. When SAML 2.0 token encryption is enabled, hosted providers should use the algorithm the remote provider advertises to encrypt symmetric encryption keys.

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

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

    • http://www.w3.org/2009/xmlenc11#rsa-oaep

      For this algorithm, Identity Cloud uses http://www.w3.org/2009/xmlenc11#mgf1sha256 to create the transport key.

    • http://www.w3.org/2001/04/xmlenc#rsa-1_5

      For security reasons, do not use this option.

NameID Format
NameID Format List

Supported NameIDs for users shared between providers for SSO.

The following diagram shows how the hosted SP determines which NameID format to use:

How the hosted SP decides which NameID formats to use
Disable NameID Persistence

By default, Identity Cloud stores NameIDs the IDP issues when the NameID format is persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) and the account manager matched a local user to the assertion. When you set this, Identity Cloud no longer stores persistent NameIDs.

When you enable this setting, end users must authenticate locally for each SAML login.

Authentication Context
Mapper

A class implementing the SPAuthnContextMapper interface to set up the authentication context.

Do not edit this field.

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

Authentication Context

The supported authentication context classes and any authentication mechanisms Identity Cloud uses when an IDP specifies the class in a SAML 2.0 authentication request. For details, refer to Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0.

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

  • The Predefined Reference specifies the list of context references.

  • The Key specifies the authentication mechanism Identity Cloud uses when an IDP specifies the class in a SAML 2.0 authentication request:

    Service

    Set the Value to the authentication journey to use.

    Module

    Not supported.

    User

    Not supported.

    Role

    Not supported.

    Authentication Level

    Identity Cloud uses a method where the authentication level is greater than or equal to the Value. Match the Value field with the Level field to avoid requiring users to re-authenticate unnecessarily.

    If more than one suitable method exists, Identity Cloud presents the available options with a ChoiceCallback.

  • The Value depends on the Key.

  • The Level specifies precedence for supported context reference classes.

    Higher numbers are stronger than lower numbers.

Comparison Type

Sets the range of authentication mechanisms the IDP can choose.

For example, when this is set to Better and PasswordProtectedTransport is the default authentication context class, the IDP must select an authentication mechanism with a higher level assigned.

Default: Exact

Include Request Authentication Context

When enabled, include the authentication context class as the requested authentication context in the SAML 2.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 credentials at SOAP endpoints.

Assertion Processing tab

Attribute Mapper

Extension point to map the SP attributes included in the SAML assertion.

Attribute Mapper

The Java class for the default implementation, which sets attributes in the user profile or properties in the session.

Do not edit this field.

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

Attribute Map

Maps SAML attributes to user profile attributes or session properties.

The Key is a SAML attribute from the assertion. The Value is the profile attribute or session property.

By default, the SP maps SAML attributes to session properties with the same names. When the SP creates a profile during auto-federation, the SP maps SAML attributes to the new user profile.

The special mapping Key: *, Value: * maps each attribute in the assertion to a session property or profile attribute with the same name. For example, if the SP receives mail and givenName in the assertion, it maps them to mail and givenName.

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

  • (Auto-federation) 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 the attributes to map because the IDP adds too many to the assertion.

Auto Federation
Enabled

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

Attribute

The SAML attribute to match accounts at different providers.

Account Mapper
Account Mapper

The Java class for the default implementation to map remote users to local user profiles.

Use Name ID as User ID

When selected, fall back to the NameID from the assertion to find the user.

Transient User

When set, map all transient users from the IDP to this profile.

Artifact Message Encoding
Artifact Message Encoding

The message encoding format for artifacts.

URL
Local Authentication URL

If set, overrides the default redirect URL to use after validating the SAML 2.0 assertion from the IDP.

Use this setting, for example, if you have created a custom UI for federation.

In integrated mode, Identity Cloud appends query string parameters to this URL. The parameters contain details to let Identity Cloud continue the authentication journey.

In standalone mode, Identity Cloud redirects users to the specified URL and appends a goto parameter, identifying the next redirect URL for the user.

Intermediate URL

A URL to redirect the user to after authentication but before the original URL requested.

External Application Logout URL

The URL to send an HTTP POST with all cookies when receiving a logout request. Add a user session property by including it as a query string parameter named appsessionproperty.

Default Relay State URL
Default Relay State URL

The URL to redirect users to after completing the request. Identity Cloud uses this if the response does not specify the RelayState.

Adapter
Adapter

A Java class to perform application-specific processing during the federation process.

Adapter Environment

Environment variables Identity Cloud passes to the adapter class.

Services tab

MetaAlias

Read-only alias to locate the provider’s entity identifier, specified as /realm-name/provider-name; for example: /alpha/mySP.

SP Service Attributes
Single Logout Service

The endpoints to manage SLO depending on the SAML binding.

Manage NameID Service

The endpoints to manage NameIDs depending on the SAML binding.

Assertion Consumer Service

The endpoints to consume assertions, where the order corresponds to the index of the URL in the standard metadata.

The scheme, FQDN, and port configured must exactly match the SPs settings in its metadata.

If the base URL service is configured, Identity Cloud uses it to determine the SP’s endpoint URL.

If the URL does not match, the SAML 2.0 flow fails and Identity Cloud logs an Invalid Assertion Consumer Location specified message.

Advanced tab

SAE Configuration
SP URL

The endpoint to manage SAE requests.

SP Logout URL

The SP endpoint to process global logout requests.

Application Security Configuration

Encryption settings for SAE.

ECP Configuration
Request IDP List Finder Implementation

A Java class to return a list of preferred IDPs trusted for the SAML ECP profile.

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

Request IDP List Get Complete

A URI reference to retrieve the complete list of IDPs if the IDPList element is not complete.

Request IDP List

A list of IDPs for the ECP client or proxy to contact. The default finder implementation uses this.

IDP Proxy
IDP Proxy

When enabled, Identity Cloud adds a Scoping element to the authentication request for proxying.

Introduction

When enabled, use introductions to find the proxy IDP.

Proxy Count

The maximum number of proxy identity providers.

IDP Proxy List

A list of URIs for preferred proxy IDPs.

Session Synchronization
Enabled

When enabled, the SP sends backchannel SOAP logout requests to all IDPs when a session times out. A session can time out after the maximum idle time or maximum session time, for example.

Relay State URL List
Relay State URL List

List of accepted RelayState URLs.

Identity Cloud validates the RelayState redirection URLs against this list during SLO. Identity Cloud only allows redirection to RelayState URLs in this list or matching the tenant domain; otherwise, a browser error occurs.

Use the pattern matching rules in Success and failure redirection URLs to specify URLs.

Remote service provider

To edit remote SP settings, go to Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content tab

Signing and Encryption
Request/Response Signing

The parts of messages the SP requires the IDP to sign digitally.

Encryption

When selected, the IDP must encrypt the selected elements.

NameID Format
NameID Format List

Supported NameIDs for users shared between providers for SSO.

Disable NameID Persistence

When enabled, do not store NameIDs at the IDP when generating an assertion for this remote SP.

Default value: false

Basic Authentication
Enabled, User Name, Password

When enabled, authenticate with the specified credentials at SOAP endpoints.

Assertion Processing tab

Attribute Mapper
Attribute Map

Override mappings from assertion attributes to user profile attributes at the IDP.

Artifact Message Encoding
Encoding

The message encoding format for artifacts.

Services tab

SP Service Attributes
Single Logout Service

The endpoints to manage SLO depending on the SAML binding.

Manage NameID Service

The endpoints to manage NameIDs depending on the SAML binding.

Assertion Consumer Service

The endpoints to consume assertions, where the order corresponds to the index of the URL in the standard metadata.

Advanced tab

Request Processing
Skip Endpoint Validation For Signed Requests

When enabled, Identity Cloud does not verify assertion consumer service (ACS) URLs in SAML authentication requests. The ACS URL can contain dynamic query parameters, for example.

The SAML 2.0 specification requires ACS URL verification. When you enable this, the SP must digitally sign the authentication request; in Assertion Content > Signing and Encryption > Request/Response Signing, enable Authentication Requests Signed. If Identity Cloud receives an unsigned authentication request, it returns an error.

SAE Configuration
SP URL

The endpoint to manage SAE requests.

SP Logout URL

The SP endpoint to process global logout requests.

IDP Proxy
IDP Proxy enabled

When enabled, authentication requests from the SP can be proxied.

Proxy all requests

When enabled, Identity Cloud proxies every authentication request from the SP, even if the Scoping element is missing.

Set IDP Proxy enabled for this setting to take effect.

Introduction enabled

When enabled, use introductions to find the proxy IDP.

This property requires a non-default SAML2IDPProxyFRImpl implementation.

Use IDP Finder

When enabled, Identity Cloud uses the IDP finder service to determine the proxy IDP.

Proxy Count

The maximum number of proxy identity providers. Identity Cloud sets the specified value in the Scoping element of proxied authentication requests.

Enable Proxy all requests for this setting to take effect.

IDP Proxy List

A list of URIs for preferred proxy IDPs.

Circle of trust

To edit circle of trust settings, go to Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Circle of Trust > Circle of Trust Name.

Name

String to refer to the circle of trust.

You can’t change its Name after creation.

Description

Short description for the circle of trust.

Status

Whether this circle of trust is operational.

Entity Providers

Known hosted and remote IDPs and SPs participating in this circle of trust.

SAML2 Writer Service URL

SAML 2.0 service to write IDP entity identifiers to common domain cookies after successful authentication for IDP discovery; for example: https://[.var]##<tenant-env-fqdn>##/am/saml2writer.

SAML2 Reader Service URL

SAML 2.0 service to read ID entity identifiers from common domain cookies for IDP discovery; for example: https://[.var]##<tenant-env-fqdn>##/am/saml2reader.

Copyright © 2010-2024 ForgeRock, all rights reserved.