Untitled | PingOne Advanced Identity Cloud Docs

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: Their attributes, such as pieces of information from the user’s profile. 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

An unauthenticated user attempts to access a SAML 2.0 SP.
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.
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.
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.
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.

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.

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

An administrative user configures Advanced Identity Cloud as the IdP as a custom application.
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.
The Google Workspace administrator enters the provided URLs and certificate into the Google Workspace Admin console for the domain being configured.
When the configuration is complete, users attempting to access a Google Workspace service are asked for their corporate email address:
Based on the domain of the email address, Google redirects the user to sign in to Advanced Identity Cloud, acting as the IdP:
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:

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

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

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

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

In 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 circle of trust

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

Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Circles of Trust, and click Add Circle of Trust.
Enter a name, and click Create.
On the Circle of Trust page, in the Entity Providers property, select at least one IdP and one SP.

Entity providers can be added at any time. This lets you create IdPs or SPs later on and add them.
Customize any other properties as required, and click Save Changes.

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

Create a hosted IdP or SP

A hosted IdP or SP is a provider hosted within 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:

Under Native Consoles > Access Management, go to Realms > Realm Name > Dashboard, and click SAML Applications.
Click Add Entity Provider > Hosted.

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

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.

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

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.
If you are adding a new attribute map, click Add. If you are updating an existing attribute map, click Update.
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:
- Hosted identity provider configuration properties
- Hosted service provider configuration properties
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 and configure 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:

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.
From the Advanced Identity Cloud admin UI, click Native Consoles > Access Management.
Go to Realms > Realm Name > Dashboard, and click SAML Applications.
Click the Add Entity Provider drop-down button, and click Remote.

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

Drag and drop the XML file into the dotted box.

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.

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.
Click Create.
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:

For in-depth information about remote entity provider properties, refer to:
- Remote identity provider configuration properties
- Remote service provider configuration properties

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.

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.

Import the metadata:

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

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.

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:

Advanced Identity Cloud retrieves the remote entity provider’s metadata, and examines the role-specific extensions for a configured digest method, or signing algorithm.
If there is no role-specific algorithm configured, Advanced Identity Cloud checks for algorithms configured in the entity provider-level extensions.
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.
If the entity provider does not specify supported signing and digest methods in the standard metadata, Advanced Identity Cloud uses the default algorithm settings.

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:

The IdP generates a random symmetric transport key using the transport key algorithm exposed in the SP’s metadata.
The IdP encrypts the assertion with the transport key.
The IdP encrypts the transport key with the public key of the SP (which is also exposed in its metadata).
The SP decrypts the transport key using its private key.
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:

Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.
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:

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`⁽¹⁾	✖

⁽¹⁾ 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:

Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.
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.
Save your changes.

Advanced Identity Cloud creates two new secret IDs, at the realm level, based on the value you specified.
Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.
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.
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`.⁽¹⁾	Use standalone mode.

⁽¹⁾ 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

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.
Advanced Identity Cloud runs any authentication nodes that precede the SAML2 Authentication node in the journey.
The SAML2 authentication node processing begins.
The authentication node requests an assertion from the IdP. The configuration of the SAML2 Authentication node determines the details of the request.
The IdP requests the user to authenticate if they’ve not already done so.
The user provides their credentials.
The IdP authenticates the user successfully.
The IdP responds to the SP with a SAML assertion.
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...
... 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.
... and a method of authenticating the user is available in the journey, Advanced Identity Cloud authenticates the user.
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.
The journey continues…
… 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:

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

If you haven’t already done so, configure SAML 2.0 by performing the tasks listed in Deployment considerations.
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.
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.
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:
  
  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:

Figure 5. Example journey to create accounts dynamically

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.

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.

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

For example, userName.
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.
(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://forgerock.com:

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

idpSingleLogoutInit.jsp query parameters

binding: (Required) Use this parameter to indicate which binding to use for the operation. The full, long name format is required for this parameter to work.

The value must be one of the following:

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:bindings:SOAP

Consent

(Optional) Use this parameter to specify a URI that is a SAML consent identifier.

Destination

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

Extension

(Optional) Use this parameter to specify a list of extensions as string objects.

goto

(Optional) Use this parameter to specify where to redirect the user when the process is complete. RelayState takes precedence over this parameter.

logoutAll

(Optional) Use this parameter to specify that the identity provider should send SLO requests to service providers without indicating a session index.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value.

For example, RelayState=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, refer to the IDP advanced reference section.

SP-initiated SSO JSP

spSSOInit.jsp: Use this page to initiate SSO from the SP side.

Also mapped to the endpoint spssoinit under the context root.

URLs:

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

Example:

The following URL takes the user from the SP side to authenticate at the IDP, and then comes back to the end user profile page at the SP after successful SSO. Lines are folded to show you the query string parameters:
```
https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSSOInit.jsp
?metaAlias=/sp
&idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
&RelayState=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam%2FXUI%2F%23profile%2Fdetails
```

spSSOInit.jsp query parameters

idpEntityID

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

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

metaAlias

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

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

affiliationID

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

AllowCreate

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

AssertionConsumerServiceIndex

(Optional) Use this parameter to specify an integer that indicates the location to which the response message should be returned to the requester.

AuthComparison

(Optional) Use this parameter to specify a comparison method to evaluate the requested context classes or statements.

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 identity provider authenticates passively.

NameIDFormat

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

For example, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, or urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value.

For example, RelayState=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, refer to the SP advanced section.

RelayStateAlias

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

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

reqBinding

(Optional) Use this parameter to indicate the binding to use for the authentication request.

Valid values in include urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect (default) and urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

sunamcompositeadvice

(Optional) Use this parameter to specify a URL-encoded XML blob that specifies the authentication level advice.

For example, the following XML indicates a requested authentication level of 1. Notice the required : before the 1:

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

SP-initiated SLO JSP

spSingleLogoutInit.jsp: Used to initiate single logout from the SP.

Also mapped to the endpoint SPSloInit under the context root.

URLs:

https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSingleLogoutInit.jsp
https://<tenant-env-sp-fqdn>/am/SPSloInit

Example:

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

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

spSingleLogoutInit.jsp query parameters

binding: (Required) Use this parameter to indicate which binding to use for the operation. The full, long name format is required for this parameter to work.

For example, specify binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST to use HTTP POST binding with a self-submitting form, rather than the default HTTP redirect binding. You can also specify binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact.
idpEntityID: (Required for Fedlets) Use this parameter to indicate the remote identity provider. If the binding property is not set, then 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

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.	Choose persistent or transient federation
Link identities automatically Configure Advanced Identity Cloud to link identities automatically when they exist in both the IdP and the SP, or to create an account on the SP when the `NameID` that the IdP provides unequivocally identifies the identity.	Link identities automatically with auto-federation Create identities automatically with auto-federation
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 for authentication
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.	Link identities to a single, shared account

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.

Choose persistent or transient federation

Link identities automatically

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

Link identities using the authentication service

Configure Advanced Identity Cloud to link identities when the NameID that the IdP provides is not enough to unequivocally identify the identity.

Link identities for authentication

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.

Link identities to a single, shared account

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:

Create a journey that contains the SAML2 Authentication node.

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

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.

Save your work.
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:

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

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.

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:

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

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

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:

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.
In the NameID Format field, specify the value urn:oasis:names:tc:SAML:2.0:nameid-format:transient.
Save your work.
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:

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

Authenticate to the IdP as the user you want to link temporarily.

On success, you are redirected to the SP.
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):

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:

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.

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.
To test your work, initiate SSO; for example, as described in IdP-Initiated SSO JSP.

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

Create identities automatically with auto-federation

In many instances there isn’t an identity to link with on the SP. For example, if it is the first time a user is attempting to access the service, and they do not have an account in the SP identity store, then there is no way to link from the IdP to the SP.

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

Create and link identities based on attribute values

Before you configure auto-federation to create identities based on attribute values:

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.

To create missing identities on the SP dynamically:

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:

On the hosted IdP:

Go to the Assertion Processing tab.

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

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

The default IdP mapping implementation allows you to add static values in addition to values taken from the user profile. You add a static value by enclosing the profile attribute name in double quotes ("), as in the following example:

Example of Static Attribute Mapping. The static value is enclosed in double quotes.

Save your work.

On the hosted SP:
- Go to the Assertion Processing tab.
- Review the Attribute Map configuration. The attribute mappings on the IdP are represented in the map.
  Tips to configure the attribute map on the SP
  The value of Key is a SAML attribute sent in an assertion. The value of Value is a property in the user’s session or an attribute of the user’s profile.
  
  By default, the SP maps the SAML attributes it receives to equivalent-named session properties. However, when the SP is configured to create identities during auto-federation and the identity doesn’t exist yet, the SP maps the SAML attributes to their equivalents in the newly-created user profile.
  
  The special mapping Key: *, Value: * means that the SP maps each attribute it receives in the assertion to equivalent-named properties or attributes. For example, if the SP receives mail and firstname in the assertion, it maps them to mail and firstname respectively.
  
  Remove the special mapping and add key pairs to the map if:
  
  During auto-federation the attributes in the IdP and SP’s identity stores do not match.
  
  You need control over the names of the session properties.
  
  You need control over which attributes the SP should map, because the IdP adds too many to the assertion.
  
  For example, if the SAML attribute is firstname and you want the SP to map it to a session property/user profile attribute called cn, create a mapping similar to Key: firstname, Value: cn.
- Enable auto-federation. In the Attribute property, enter the SAML attribute name the SP will use to link accounts, as configured in the Attribute Map.
  
  The value of the named attribute is used as the username of the created user when auto-federation is enabled.
- Save your work.
- Navigate to Realms > Realm Name > Authentication > Settings.
- On the User Profile tab in the User Profile field, select Dynamic or Dynamic with User Alias.
  
  For more information the user profile property, refer to User profile.
- Save your work.
To test your work:
- Create a new user on the IdP, including values for any attributes you mapped in the providers.
- Log out of the UI and initiate SSO; for example, as described in IdP-Initiated SSO JSP.
- Authenticate as the new user you created in the IdP.
- On success, check https://<tenant-env-sp-fqdn>/enduser/?realm=realm_name/profile and click Edit Personal Info to see the new user account created on the SP, and the attributes that were copied from the assertion.

Link identities for authentication

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

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:

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

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

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.

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.

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

For example, userName.
Authenticate the user to the SP.
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.

Link identities to a single SP account

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:

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

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.

IdP attribute mapper

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

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

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

Demonstrate an IdP attribute mapper

Before you try the example, configure single sign-on using SAML v2.0 with 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
Configure the IdP
Test the script

Create the script

In the Advanced Identity Cloud admin UI, create a script of type SAML2 IDP Attribute Mapper.
In the JavaScript field, paste the template saml2-idp-attribute-mapper.js script.

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

Save your changes and close the editor.

Configure the IdP

Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted IDP Name > Assertion Processing.
In the Attribute Mapper Script field, select your script.
Save your changes.

Test the script

Perform a SAML v2.0 flow.

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

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

Available objects

PingOne Advanced Identity Cloud injects the following objects into the execution context of an IdP attribute mapper script:

Binding Information

Binding	Information
`hostedEntityId`	The entity ID for the hosted IdP.
`idpAttributeMapperScriptHelper`	An object with methods for IdP attribute mapping. For details, refer to IdpAttributeMapperScriptHelper.
`logger`	Write a message to the PingOne Advanced Identity Cloud `am-core` log source. The logger identifier takes the form `scripts.script-type.script-id`. For details, refer to Debug.
`realm`	The realm the user authenticates to.
`remoteEntityId`	The remote entity ID.
`session`	Represents the user’s single sign-on session object. For details, refer to SSOToken.

hostedEntityId

The entity ID for the hosted IdP.

idpAttributeMapperScriptHelper

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

logger

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

realm

The realm the user authenticates to.

remoteEntityId

The remote entity ID.

session

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

IdP adapter

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

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

Processing phase Description

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.

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.

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

Demonstrate an IdP adapter

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

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

Configure a policy
Create the script
Configure the IdP
Test the script

Configure a policy

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)
Go to Policy Sets and create a new policy set with the following settings:

Id

saml

Name

saml

Resource Types

SAML SP Access
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

In the Advanced Identity Cloud admin UI, create a script of type SAML2 IDP Adapter.
In the JavaScript field, paste the template saml2-idp-adapter.js script.

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

Save your changes and close the editor.

Configure the IdP

Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted IDP Name > Advanced.
In the IDP Adapter Script field, select your script.
Save your changes.

Test the script

Perform an SP-initiated flow.
Verify the user is redirected to the redirect_uri from the policy (https://example.com).

Available objects

PingOne Advanced Identity Cloud injects the following objects into the execution context of an IdP adapter script:

Binding Information

Binding	Information
`authnRequest`	The original authentication request from the SP. For details, refer to AuthnRequest. Not available to the `preSendFailureResponse` function.
`faultCode`	The fault code in the SAML response. Only available to the `preSendFailureResponse` function.
`faultDetail`	The details of the fault in the SAML response. Only available to the `preSendFailureResponse` function.
`hostedEntityId`	The entity ID for the hosted IdP.
`idpAdapterScriptHelper`	An object with methods to provide context when customizing the IdP adapter plugin points. For details, refer to IdpAdapterScriptHelper.
`logger`	Write a message to the PingOne Advanced Identity Cloud `am-core` log source. The logger identifier takes the form `scripts.script-type.script-id`. For details, refer to Debug.
`realm`	The realm the user authenticates to.
`relayState`	A String representing the `relayState` in the redirect. Not available to the `preSingleSignOn` or `preSendFailureResponse` functions.
`reqId`	The identifier to continue processing if the adapter redirects. Not available to the `preSignResponse` or `preSendFailureResponse` functions.
`request`	The `HttpServletRequest` object.
`res`	The SAML response. For details, refer to Response. Only available to the `preSignResponse` function.
`response`	The `HttpServletResponse` object. Not available to the `preSignResponse` function.
`session`	Represents the user’s single sign-on session object. For details, refer to SSOToken. Not available to the `preSingleSignOn` or `preSendFailureResponse` functions.

authnRequest

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

Not available to the preSendFailureResponse function.

faultCode

The fault code in the SAML response.

Only available to the preSendFailureResponse function.

faultDetail

The details of the fault in the SAML response.

Only available to the preSendFailureResponse function.

hostedEntityId

The entity ID for the hosted IdP.

idpAdapterScriptHelper

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

logger

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

realm

The realm the user authenticates to.

relayState

A String representing the relayState in the redirect.

Not available to the preSingleSignOn or preSendFailureResponse functions.

reqId

The identifier to continue processing if the adapter redirects.

Not available to the preSignResponse or preSendFailureResponse functions.

request

The HttpServletRequest object.

res

The SAML response. For details, refer to Response.

Only available to the preSignResponse function.

response

The HttpServletResponse object.

Not available to the preSignResponse function.

session

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

Not available to the preSingleSignOn or preSendFailureResponse functions.

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

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.

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.

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
Configure the SP
Test the script

Create the script

In the Advanced Identity Cloud admin UI, create a script of type SAML2 SP Adapter.
In the JavaScript field, paste the template saml2-sp-adapter.js script.

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

Save your changes and close the editor.

Configure the SP

Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted SP Name > Assertion Processing.
In the Adapter Script field, select the script you created.
Save your changes.

Test the script

Test your changes using an SP-initiated flow.
Verify that the SAML2.0 request contains the updated value (SPNameQualifier="mySP-Updated") and that the user is redirected to https://example.com on successful login.

Available objects

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

Binding Information

authnRequest

The original authentication request sent from the SP.

Only available to single sign-on functions.

Refer to AuthnRequest.

binding

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

Not available to single sign-on functions.

failureCode

The failure code associated with the error that has occurred.

Possible values

Constant	Value
`SUCCESS`	0
`INVALID_RESPONSE`	1
`FEDERATION_FAILED_WRITING_ACCOUNT_INFO`	3
`SSO_FAILED_SESSION_ERROR`	4
`SSO_FAILED_ATTRIBUTE_MAPPING`	5
`SSO_FAILED_NO_USER_MAPPING`	6
`SSO_FAILED_AUTH_USER_INACTIVE`	7
`SSO_FAILED_AUTH_USER_LOCKED`	8
`SSO_FAILED_AUTH_ACCOUNT_EXPIRED`	9
`SSO_FAILED_SESSION_GENERATION`	10
`SSO_FAILED_META_DATA_ERROR`	11

Only available to preSendFailureResponse.

hostedEntityId

The entity ID for the hosted IdP.

idpEntityID

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

idRequest

The ManageNameIDRequest object for the name identifier request.

Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

idResponse

The ManageNameIDResponse object for the name identifier request.

Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

isFederation

A boolean indicating whether federation is used, otherwise false.

Only available to the postSingleSignOnSuccess function.

logger

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

logoutRequest

The single logout LogoutRequest.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

logoutResponse

The single logout LogoutResponse.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

out

The PrintWriter for writing to.

Only available to postSingleSignOnSuccess.

profile

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

Available to preSingleSignOnProcess, postSingleSignOnSuccess, and postSingleSignOnFailure.

realm

The realm the user authenticates to.

request

The HttpServletRequest object.

Always present.

response

The HttpServletResponse object.

Always present.

Session

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

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

Only available to postSingleSignOnSuccess.

SpAdapterScriptHelper

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

Always present.

SsoResponse

The SSO response received from the IdP.

Available to preSingleSignOnProcess, postSingleSignOnSuccess, and postSingleSignOnFailure.

userId

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

Not available to single sign-on functions.

Reference

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

Hosted identity provider

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

Assertion Content tab

Signing and Encryption

Request/Response Signing

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

Encryption

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

Secret ID and Algorithms

Secret ID Identifier

By default, 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:
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 implementing the IDPAuthnContextMapper interface to set up the authentication context.

Do not edit this field.

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

Authentication Context

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

The Predefined Reference specifies the list of context references.
The Key specifies the authentication mechanism PingOne Advanced Identity Cloud uses when an SP specifies the class in a SAML 2.0 authentication request:

Service

Set the Value to the authentication journey to use.

Module

Not supported.

User

Not supported.

Role

Not supported.

Authentication Level

PingOne 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, PingOne Advanced Identity Cloud presents the available options with a ChoiceCallback.
The Value depends on the Key.
The Level specifies precedence for supported context reference classes.

Higher numbers are stronger than lower numbers.

Assertion Time

Not-Before Time Skew: Grace period in seconds for the NotBefore time in assertions.
Effective Time: Assertion validity in seconds.

Basic Authentication

Enabled, User Name, Password: When enabled, authenticate with the specified credentials at SOAP endpoints.

Assertion Cache

Enabled: When enabled, cache assertions.

Assertion Processing tab

Attribute Mapper

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

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

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

Default: com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper
Attribute Mapper Script: A JavaScript implementation of an attribute mapper.

Select a Saml2 IDP Attribute Mapper script from this realm.

For an example, refer to saml2-idp-attribute-mapper.js.
Attribute Map: Maps SAML attributes to user profile attributes or session properties.

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

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

After you’ve set up a remote identity provider, 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 service provider

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

Assertion Content tab

Signing and Encryption

Request/Response Signing

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

Encryption

When selected, the IdP must encrypt the selected elements.

Secret ID and Algorithms

Secret ID Identifier

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:
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 implementing the SPAuthnContextMapper interface to set up the authentication context.

Don’t edit this field.

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

Authentication Context

The supported authentication context classes and any authentication mechanisms PingOne Advanced Identity Cloud uses when an IdP specifies the class in a SAML 2.0 authentication request. Learn more in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0.

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

The Predefined Reference specifies the list of context references.
The Key specifies the authentication mechanism PingOne Advanced Identity Cloud uses when an IdP specifies the class in a SAML 2.0 authentication request:

Service

Set the Value to the authentication journey to use.

Module

Not supported.

User

Not supported.

Role

Not supported.

Authentication Level

PingOne 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, PingOne Advanced Identity Cloud presents the available options with a ChoiceCallback.
The Value depends on the Key.
The Level specifies precedence for supported context reference classes.

Higher numbers are stronger than lower numbers.

Comparison Type

Sets the range of authentication mechanisms the IdP can choose.

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

Default: Exact

Include Request Authentication Context

When enabled, include the authentication context class as the requested authentication context in the SAML 2.0 authentication request.

Default: Enabled

Assertion Time

Assertion Time Skew: Grace period in seconds for the NotBefore time in assertions.

Basic Authentication

Enabled, User Name, Password: When enabled, authenticate with the specified credentials at SOAP endpoints.

Assertion Processing tab

Attribute Mapper

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

Attribute Mapper

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

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

After you’ve set up a remote service provider, 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.

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.

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.