PingOne Advanced Identity Cloud

SAML 2.0

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

SAML 2.0

Learn how Advanced Identity Cloud support SAML 2.0.
Configure SAML 2.0

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

Name changes for ForgeRock products

Product names changed when ForgeRock became part of Ping Identity. Learn more in New name for ForgeRock Identity Cloud.

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.

Advanced 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 Advanced Identity Cloud.
Figure 1. Overview of SAML 2.0 in Advanced Identity Cloud

Advanced 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 Advanced 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 Advanced 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. Advanced 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 Advanced 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 Advanced Identity Cloud. Advanced Identity Cloud also supports the HTTP-POST binding for processing SAML 2.0 authentication requests.

    Advanced 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 Advanced Identity Cloud is returning SAML assertions. Advanced 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 Advanced Identity Cloud provides the solution.

In this scenario, Google acts as the SP, and Advanced 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 Advanced Identity Cloud as the IdP as a custom application.

  2. The administrative user configures Google Workspace as a remote SP and provides the values that Google needs to use Advanced 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 Advanced Identity Cloud, acting as the IdP:

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

  6. After successfully authenticating with Advanced 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 Advanced Identity Cloud using their corporate Example.com account:

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

Deployment considerations

Before you set up SAML 2.0 in Advanced 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. Advanced 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 Advanced 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 Advanced 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 Advanced Identity Cloud is the SP, the IdP, or both, and/or what metadata you need to import from other providers.

For example, if Advanced 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

Advanced 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

Advanced 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

To implement SAML 2.0 in AM, you share metadata for your hosted providers with other remote providers in a circle of trust (CoT).

You must also configure remote providers by importing their metadata.

In Advanced Identity Cloud, a hosted provider is one served by the current Advanced Identity Cloud tenant, and a remote provider is one hosted elsewhere.

Create a hosted IdP or SP

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

With application management, Advanced Identity Cloud acts as a hosted IdP through intuitive screens. Learn more in Create a custom SAML 2.0 application.

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

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

    Advanced Identity Cloud truncates sequences of whitespace with a single whitespace character in values such as entity IDs. For example, if MyEntityID value (with one space) exists already, and you add a new entity, My Entity ID value (same name but multiple spaces), then AM will throw an error because the string values are treated as identical.

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

    The aliases for providers must be unique in a circle of trust and 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.

    If the remote provider can read the metadata URL, you can provide the URL to the remote provider, and they can load the metadata that way instead.

Import a remote IdP or SP

A remote IdP or SP is a provider outside of Advanced 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 Advanced Identity Cloud tenant. Each application has different ways to obtain the file.

  2. From the Advanced 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.

      Advanced 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 (CoT).

  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

    Learn more about remote entity provider properties in:

Import SAML 2.0 metadata using REST

To import metadata using REST, send an HTTP POST request to the /realm-config/saml2/remote?_action=importEntity endpoint.

  1. Convert the XML metadata to a base64 encoded string:

    1. Encode the XML metadata:

      $ openssl base64 -in <metadata.xml> -out <metadata_base64.txt>

    2. Replace any + symbols with - in the resulting base64-encoded string.

  2. Import the metadata:

    1. Create an access token for the appropriate realm. Learn more in Get an access token.

    2. Run the following command:

      $ curl \
--request POST 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/saml2/remote?_action=importEntity' \
--header 'authorization: Bearer <access-token>' \ (1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--data-raw '{"standardMetadata":"<base64urlencodedstring>"}' (2)
      1 Replace <access-token>' with the access token.
      2 Replace <base64urlencodedstring> with the XML metadata you converted to a base64-encoded string in step 1.

Configure a SAML 2.0 application journey

Configure the remote SP so that a specific authentication journey is always run for users authenticating with your SAML 2.0 app. The federation flow invokes the associated journey regardless of any existing sessions or requested or configured authentication contexts.

To configure a SAML 2.0 app journey, specify a journey in Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Remote SP > Tree Name.

Learn more in Remote SP configuration.

When you configure an app journey, the processing of the SAML 2.0 request depends on the authentication context requested by the SP. The following table shows the SAML response for each comparison type and the requested authentication context.

Authentication context Comparison type Response

SP requested authn context

Exact / None

Requested authn context included

SP requested authn context

Better / Maximum / Minimum

UNSPECIFIED

SP doesn’t request authn context

-

UNSPECIFIED

IDP-initiated (no requested authn context)

-

UNSPECIFIED

You can’t delete a journey if it’s referenced by a SAML 2.0 app.

Create a circle of trust (CoT)

A CoT groups at least one IdP and at least one SP who agree to share authentication information.

With application management, you can use intuitive screens to create trusted agreements between providers through SAML 2.0 applications.

Learn more in Create a custom SAML 2.0 application.

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

    You can create IdPs and SPs at any time and add them later on.

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

    Learn about CoT configuration in CoT configuration.

Export SAML 2.0 metadata

SAML 2.0 metadata is an XML document that contains the necessary information to transmit an agreement between identity providers (IdPs) and service providers (SPs). It contains information on setting up federation (through NameID) and specifies the locations of various services. The SAML 2.0 metadata contains settings such as endpoint URLs, supported bindings, identifiers, and public keys.

Exporting SAML 2.0 metadata from PingOne Advanced Identity Cloud lets you share metadata with other entity providers and can be useful for troubleshooting your configuration.

You can access the SAML 2.0 metadata for your entity provider by opening your tenant environment’s metadata URL in a browser. The URL is in the following format:

https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=<entityid>&realm=/<realm> (1) (2)
1 <entityid> is the name of your IdP or SP entity provider.
2 <realm> is the realm where the entity provider is configured, for example, alpha.

To export the metadata to a file, run the following command:

$ curl --output <metadata.xml> "<tenant-env-metadata-url>"
Example

If the URL to access your metadata is:

https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha

Run the following command to export your metadata:

$ curl \
--output metadata.xml \
"https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha"

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 Advanced Identity Cloud, refer to TLS, secrets, signing, trust, and encryption

How signing works

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

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

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

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

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

    Advanced 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. Advanced 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 Advanced Identity Cloud to sign and encrypt SAML 2.0 assertion content

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

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

  3. Save your changes.

    Advanced 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 Advanced Identity Cloud should sign and the elements to encrypt.

  6. Save your changes.

    Advanced Identity Cloud now uses the key pairs you configured. For more information on how to create and configure keys for signing and encryption in Advanced 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.

Advanced 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 Advanced 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 Advanced 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 can’t 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 Advanced Identity Cloud SAML 2.0 SP. The login URL references an authentication journey that includes a SAML2 Authentication node. For example, https://<tenant-env-fqdn>/am/XUI/?service=mySAM2LTree.

  2. Advanced Identity Cloud runs any authentication nodes that precede the SAML2 Authentication node in the journey.

  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.

  5. The IdP requests the user to authenticate if they’ve not already done so.

  6. The user provides their credentials.

  7. The IdP authenticates the user successfully.

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

  9. If the SAML assertion contains a non-transient name ID, Advanced 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 continues.

    If the name ID doesn’t exist...

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

  11. ... and a method of authenticating the user is available in the journey, Advanced Identity Cloud authenticates the user.

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

  13. The journey continues…​

  14. …​ and authentication is successful.

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 Advanced 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 Advanced 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 PingOne Advanced 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 doesn’t exist on the SP.

    The scripted decision node placed the attributes required to create the account in the journey’s shared state; however, these might 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 haven’t configured auto-federation, you can add the Write Federation Information node to create a persistent link between the accounts.

    Refer to Link identities by using journeys for an example.

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 PingOne Advanced 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, Advanced Identity Cloud SAML 2.0 federation provides JSP files that direct users to do SSO and SLO across providers in a circle of trust. Advanced 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://example.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%example.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.

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

PingOne Advanced 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 Advanced 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 IdP authenticates passively.

A value of true is not honored if you have configured a SAML 2.0 app journey, and the journey includes a node that requires user interaction.
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 Advanced 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.

Advanced 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 Advanced 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 Advanced 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 Advanced 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 Advanced 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 Advanced Identity Cloud federates identities

Task Resources

Decide whether to permanently link identities

Advanced 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 Advanced Identity Cloud to link identities automatically when they exist in both the IdP and the SP.

Link identities using the authentication service

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

Choose persistent or transient federation

In PingOne Advanced 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:

  • Configure PingOne Advanced Identity Cloud for SAML 2.0.

  • Create the IdP.

    • If PingOne Advanced Identity Cloud is the IdP, utilize the Advanced Identity Cloud admin UI with application management.

  • Create SPs.

  • Configure a circle of trust (CoT).

  • Configure PingOne Advanced Identity Cloud to support SSO.

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

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

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

PingOne Advanced 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:

  • Configure PingOne Advanced Identity Cloud for SAML 2.0.

  • Create the IdP.

    • If PingOne Advanced Identity Cloud is the IdP, utilize the Advanced Identity Cloud admin UI with application management.

  • Create SPs.

  • Configure a circle of trust (CoT).

  • Configure PingOne Advanced Identity Cloud to support SSO.

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.

PingOne Advanced 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 PingOne Advanced 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:

  • Configure PingOne Advanced Identity Cloud for SAML 2.0.

  • Create the IdP. If PingOne Advanced Identity Cloud is the IdP, use the Advanced Identity Cloud admin UI with application management.

  • Create SPs.

  • Configure a circle of trust (CoT).

  • Configure PingOne Advanced Identity Cloud to support SSO.

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.

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

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.

PingOne Advanced 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 PingOne Advanced Identity Cloud SP:

  1. Accessing the SP.

    A user attempts to access a service and is redirected to PingOne Advanced 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.

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

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

    PingOne Advanced 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, PingOne Advanced 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 PingOne Advanced 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.

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

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

PingOne Advanced 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:

  • Configure PingOne Advanced Identity Cloud for SAML 2.0.

  • Create the IdP.

    • If PingOne Advanced Identity Cloud is the IdP, use the Advanced Identity Cloud admin UI with application management.

  • Create SPs.

  • Configure a circle of trust (CoT).

  • Configure PingOne Advanced Identity Cloud to support SSO.

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

PingOne Advanced Identity Cloud lets you extend SAML 2.0 functionality with scripts:

Script type Description

IdP attribute mapper

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

IdP adapter

Customize SAML responses and browser redirects.

SP adapter

Customize configuration in the hosted SP adapter environment.

NameID mapper

Customize the value of the NameID attribute in the SAML assertion.

IdP attribute mapper

Use an IdP attribute mapper script to map user-configured attributes to SAML attributes in 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 PingOne Advanced Identity Cloud attempts to retrieve them from the user’s session.

Learn about IdP attribute mapper scripts from the following resources:

Demonstrate an IdP attribute mapper

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

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

Create the script

  1. In the Advanced Identity Cloud admin UI, create a script of type SAML2 IDP Attribute Mapper.

  2. In the JavaScript field, 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. Save your changes and close the editor.

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>

IdP adapter

Use an IdP adapter script 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 PingOne Advanced 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 PingOne Advanced Identity Cloud prepares the response, but before it signs the response. This lets you customize the content of the SAML response.

preSendFailureResponse

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

Learn about IdP adapter scripts from the following resources:

Demonstrate an IdP adapter

Before you try the example, configure single sign-on using SAML v2.0 with PingOne Advanced 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. In the Advanced Identity Cloud admin UI, create a script of type SAML2 IDP Adapter.

  2. In the JavaScript field, paste the template saml2-idp-adapter.js script.

  3. Insert the following code in the preSendResponse function. The script causes PingOne Advanced 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. Save your changes and close the editor.

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

SP adapter

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 PingOne Advanced Identity Cloud sends the single sign-on request to the IDP.

preSingleSignOnProcess

Invoked before single sign-on processing begins on the SP side, when PingOne Advanced 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.

Learn about SP adapter scripts from the following resources:

Demonstrate an SP adapter

This task assumes your environment is already correctly configured for single sign-on using SAML v2.0, where PingOne Advanced 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. In the Advanced Identity Cloud admin UI, create a script of type SAML2 SP Adapter.

  2. In the JavaScript field, paste the template saml2-sp-adapter.js script.

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

  4. 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. Save your changes and close the editor.

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.

NameID mapper

Use a NameID mapper script to customize the value of the NameID attribute returned in the SAML assertion per SP.

Demonstrate a NameID adapter

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

The following example modifies the NameID attribute in the assertion on the remote SP:

Learn about NameID mapper scripts from the following resources:

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 NameID Mapper from the Script Type drop-down list, and click Create.

    The NameID mapper script type is a next-generation script only.

  3. In the JavaScript field, write a script to set a custom value for the NameID attribute. For example, the following script replaces instances of .com with .org in a user’s email address. Alternatively, uncomment the call to getIdentityNameID to set NameID to the user’s first and last name.

    /*
 * Retrieve nameID value from Java plugin and modify
*/
function getModifiedNameID() {
  var nameIDValue = nameIDScriptHelper.getNameIDValue();

  if (nameIDValue.includes(".com")) {
      return nameIDValue.replace(".com", ".org");
  }
  return nameIDValue;
}

/*
 * Use identity binding to gather attributes
*/
function getIdentityNameID() {
  var givenName = identity.getAttributeValues("givenName")[0];
  var lastName = identity.getAttributeValues("sn")[0];

  return givenName + "_" + lastName;
}

getModifiedNameID();
//getIdentityNameID();

  4. Save your changes and close the editor.

Configure the remote SP

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

  2. Under Account Mapper, select your script from the SAML2 NameID Mapper Script drop-down list.

  3. Save your changes.

Test the script

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

  2. Verify that the SAML 2.0 assertion shows an updated value, for example:

    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
             NameQualifier="idp"
             SPNameQualifier="sp">bjensen@example.org</saml:NameID>

Reference

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

Hosted IdP configuration

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, PingOne Advanced Identity Cloud uses the entity provider’s role-specific, default global secret IDs. Alternatively, set an identifier for the secret ID PingOne Advanced 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, PingOne Advanced 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, PingOne Advanced Identity Cloud Base64-encodes the profile attribute it adds to the assertion.

Authentication Context
Mapper

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

Don’t edit this field.

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

Authentication Context

The supported authentication context classes and any authentication mechanisms Advanced 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

Context Reference

Select from the following options to define a context reference:

  • Predefined Reference to choose from a list of supported context references.

  • Custom Reference to type your own reference to an authentication context.

Key

Select an authentication mechanism from the list for Advanced Identity Cloud to use when the SP specifies an authentication context class in a SAML 2.0 request.

Authentication mechanisms
Service

Set the Value to the authentication journey to use.

Module

Not supported.

User

Not supported.

Role

Not supported.

Authentication Level

Advanced 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, Advanced Identity Cloud presents the available options with a ChoiceCallback.

Value

Depends on the Key. For example, if you selected Service, enter the name of the journey.

Level

The order of precedence for supported context reference classes as a numeric value.

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, PingOne Advanced 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, PingOne Advanced 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.

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

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

PingOne Advanced 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, PingOne Advanced Identity Cloud applies the finder for all remote SPs.

Relay State URL List
Relay State URL List

List of accepted RelayState URLs.

PingOne Advanced Identity Cloud validates the RelayState redirection URLs against this list during SLO. PingOne Advanced 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 PingOne Advanced 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 IdP configuration

After you’ve set up a remote IdP, configure it under Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content

Signing and Encryption
Request/Response Signing

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

Encryption

  • NameID Encryption – When selected, the SP must encrypt NameID elements.

Algorithms

Select the signing, encryption and digest algorithms that the SP will use.

NameID Format
NameID Format List

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

Secrets

  • Secret Label Identifier – Identifier used to create a secret label for mapping to a secret in the secret store. PingOne Advanced Identity Cloud uses this label to create a specific secret label for this entity provider. The secret label takes the form am.applications.federation.entity.providers.saml2.identifier.basicauth where identifier is the value of Secret Label Identifier. The label can only contain characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

    If you change the Secret Label Identifier for a specific entity provider, any corresponding mappings are deleted, unless they’re referenced by other entity providers.

Basic Authentication

  • Enabled – Authenticate with the specified username and password when making requests to this entity provider’s SOAP endpoints.

  • User Name – The username with which to authenticate at SOAP endpoints.

  • Password – The password with which to authenticate at SOAP endpoints.

    If you set a value for Secret Label Identifier, and PingOne Advanced Identity Cloud finds a mapping to this secret label in the secret store, the value of this Password field is ignored. For example, if you set the Secret Label Identifier to demo and PingOne Advanced Identity Cloud finds a secret mapping to am.applications.federation.entity.providers.saml2.demo.basicauth, PingOne Advanced Identity Cloud uses this secret and ignores the value of the Password field. For basic authentication, there is no default secret label for the realm, or globally.
Client Authentication

These settings let an SP authenticate to the IdP using mutual TLS (mTLS).

When you enable client authentication for any request type in this section, you must configure a secret mapping from one of the following secret labels to a valid secret (ESV) in the secret store:

  • am.default.applications.federation.entity.providers.saml2.sp.mtls – the global or realm-specific mapping for hosted SPs

  • am.applications.federation.entity.providers.saml2.identifier.mtls – a mapping for a specific SP, where identifier is the value of the Secret Label Identifier you set in the Secrets panel in the SP configuration.

If you configure a global mapping, a realm-specific mapping, and a mapping for a specific SP, the order of precedence is as follows:

  • Hosted SP-specific mapping

  • Realm-level default

  • Global default

The certificates mapped to these labels are included in the SP metadata export with <KeyDescriptor use="signing">.

Currently, you can enable mTLS for the following request:

  • Artifact Resolve – For artifact resolution requests, the IdP instructs the SP to send a client certificate along with the request.

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

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, PingOne Advanced Identity Cloud uses the entity provider’s role-specific, default global secret IDs. Alternatively, set an identifier for the secret ID PingOne Advanced 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

The 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, PingOne Advanced 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, don’t 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, PingOne Advanced 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, PingOne Advanced 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 that implements the SPAuthnContextMapper interface and maps the incoming request parameters to an authentication context.

Don’t edit this field.

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

Authentication Context

The authentication context maps the URI references to the IdP’s supported authentication context classes to authentication levels set on the SP side.

Context Reference

Select from the following options to define a context reference:

  • Predefined Reference to choose from a list of supported context references.

  • Custom Reference to type your own reference to an authentication context.

Level

The order of precedence of the context reference classes as a numeric value.

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

Learn about authentication context classes in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.

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

Comparison Type

Used in conjunction with the default authentication context to specify the possible range of authentication mechanisms the IdP can choose from.

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

Default: exact

Include Request Authentication Context

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.

Client Authentication
Exclude Client Certificate from Metadata

When enabled, don’t export the client certificate in the SP metadata.

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.

Don’t 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, PingOne Advanced Identity Cloud appends query string parameters to this URL. The parameters contain details to let PingOne Advanced Identity Cloud continue the authentication journey.

In standalone mode, PingOne Advanced 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. PingOne Advanced 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 PingOne Advanced 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, PingOne Advanced Identity Cloud uses it to determine the SP’s endpoint URL.

If the URL does not match, the SAML 2.0 flow fails and PingOne Advanced 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, PingOne Advanced 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.

PingOne Advanced Identity Cloud validates the RelayState redirection URLs against this list during SLO. PingOne Advanced 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 SP configuration

After you’ve set up a remote SP, configure it under Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion Content

The following properties appear under the Assertion Content tab:

Signing and Encryption
Request/Response Signing

The requests and responses that the SP requires the IdP to sign digitally.

Encryption

The elements that the SP requires the IdP to encrypt.

  • Attribute Encryption – When selected, the IDP must encrypt SAML attributes.

  • Assertion Encryption – When selected, the IDP must encrypt SAML assertions.

  • NameID Encryption – When selected, IDP must encrypt NameID elements.

Algorithms

  • Signing Algorithm – The signing algorithm the SP will use.

  • Digest Algorithm – The digest algorithm the SP will use.

  • Encryption Algorithm – The encryption algorithm the SP will use.

NameID Format

  • NameID Format List – The supported name identifiers for users who are shared between providers for single sign-on.

  • NameID Value Map – Map the NameID format to a user profile attribute, for example:

    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress=mail or urn:oasis:names:tc:SAML:2.0:nameid-format:persistent=objectGUID;binary.

    • Key – The Name ID format to map, for example: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    • Value – The profile attribute, for example: mail.

    • Binary – Indicates that the profile attribute is binary and should be Base64-encoded when used as the NameID value.

    If the specified NameID format is used in the protocol, the corresponding profile attribute value is used as the NameID in the Subject assertion element. This mapping overrides all the values defined in the NameID Value Map on the hosted IdP. For example, if a NameID Value Map is defined for the SP and a request is made with a specific NameID Format that only exists on the IdP, it will fail.

  • Disable NameID Persistence Disables the storage of NameID values at the IdP when generating an assertion for this remote SP.

    Default value: false

Secrets

  • Secret Label Identifier – Identifier used to create a secret label for mapping to a secret in the secret store.

    PingOne Advanced Identity Cloud uses this label to create a specific secret label for this entity provider. The secret label takes the form am.applications.federation.entity.providers.saml2.identifier.basicauth where identifier is the value of Secret Label Identifier. The label can only contain characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

    If you change the Secret Label Identifier for a specific entity provider, any corresponding mappings are deleted, unless they’re referenced by other entity providers.

    If you specify a value for Secret Label Identifier, and PingOne Advanced Identity Cloud finds a mapping to this secret label in the secret store, the value of the Password field is ignored. For basic authentication, there is no default secret label for the realm, or globally.
Basic Authentication

  • Enabled – Require authentication with the specified username and password at SOAP endpoints.

  • User Name – The username used to authenticate at SOAP endpoints.

  • Password – The password used to authenticate at SOAP endpoints.

    If you specify a value for Secret Label Identifier, and PingOne Advanced Identity Cloud finds a mapping to this secret label in the secret store, the value of the Password field is ignored. For basic authentication, there is no default secret label for the realm, or globally.

Assertion Processing

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

The following properties appear under the 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 settings

Request Processing
Skip Endpoint Validation For Signed Requests

When enabled, PingOne Advanced Identity Cloud doesn’t 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 PingOne Advanced 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, PingOne Advanced 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, PingOne Advanced Identity Cloud uses the IDP finder service to determine the proxy IDP.

Proxy Count

The maximum number of proxy identity providers. PingOne Advanced 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.

Tree Name
Tree Name

If configured, Advanced Identity Cloud redirects the remote SP to the specified journey, ignoring the configured authentication context mapper and existing sessions. The redirect contains a transaction condition advice to ensure the journey is run.

You can access the requested authentication context and configured mappings by including a Scripted Decision node in the journey that queries the samlApplication script binding.

Learn about SAML 2.0 app journeys in Configure a SAML 2.0 application journey.

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.