Deployment considerations

Before you set up SAML 2.0 in AM, you should:

Know which providers will participate in circles of trust (CoTs).
Know how AM installations act as IdPs or SPs.
Define how to map shared user attributes in identity information exchanged with other participants in a CoT. Local user profile attribute names should map to user profile attribute names at other providers.

For example, if you exchange user identifiers with your partners, and you call it uid, but your partner calls it userid, then you map your uid to your partner’s userid.
Import the keys used to sign assertions into the keystore in your AM configuration directory. Use the Java keytool command.

You can find more information about AM keystores, including location and different types of keystores available and how to change the default keys, in Secrets, certificates, and keys.
Agree with other providers on a synchronized time service.
Determine whether your session state configuration limits your usage of certain SAML 2.0 profiles. Learn more in Session state considerations.
Consider increasing DS search size limits if you intend to create many SAML 2.0 entities. To ensure searches for defined entities work as expected, configure the DS search properties ds-rlim-size-limit and ds-rlimit-time-limit appropriately.

Learn more in Enforce limits in the DS documentation.

Session state considerations

SAML 2.0 uses a combination of the CTS and browser-based data to store the progress of SAML 2.0 single sign-on (SSO) operations. This combination lets AM instances continue SSO flows that started at a different instance, without needing sticky load balancing in most scenarios.

SSO and session storage

SSO progress is stored in a JSON web token (JWT) in the browser’s session storage.

The JWT created in the browser’s session storage doesn’t expire. Instead, the time allowed to complete the SSO flow is determined by the configurable maximum duration of the journey session.

The browser must support the sessionStorage API to handle SSO without the need for sticky load balancing of AM instances. You must configure sticky load balancing to support SAML 2.0 SSO with clients that don’t support session storage and on IdP proxy implementations.

Session storage is similar to local storage but is more limited:

Session storage exists only within the current browser tab.
Another tab that displays the same page will have a different session storage.
Session storage is shared between frames in the same tab (assuming they come from the same origin).
Session storage data survives a page refresh, but not closing and opening the tab.

To enable session storage support in WebView components on Android, set the following property:

settings.setDomStorageEnabled(true)

You can’t use session storage when using multiple WebView components simultaneously. Learn more in WebSettings - setDomStorageEnabled in the Android Developers documentation.

The JWT created in the browser’s session storage is encrypted using the am.global.services.saml2.client.storage.jwt.encryption secret label, which by default is mapped to the directenctest certificate alias. Learn more in Secrets, certificates, and keys.

Single log out (SLO)

Performing SLO operations with more than one AM instance has the following caveats:

AM instances cache information about SLO progress in memory. After the initial request, you must send each subsequent request in an SLO flow to the same instance; for example, by enabling sticky load balancing.
Use the HTTP-POST or HTTP-Redirect bindings for SAML 2.0 SLO. The SOAP binding isn’t supported.

Client-side sessions and cookie size limits

Browsers allow cookie sizes between 4,000 and 5,200 bytes, depending on the browser. When using client-side sessions, some SAML 2.0 features can cause the session cookie to exceed the browser’s cookie size limit. This can occur in the following situations:

In standalone mode, when performing SSO, the IdP adds the full login URL (FullLoginURL property) to the session cookie, which includes the authentication request data, adding to cookie size.
In integrated mode, AM adds to the session those SAML 2.0 attributes mapped to AM attributes.

If a client-side session cookie exceeds the supported size in any of these cases, you can configure a custom post-authentication tree hook to remove unwanted properties or attributes, at the realm level. Removing properties or attributes in a custom SAML 2.0 SP adapter isn’t supported.

You can find more information about post-authentication tree hooks in Create post-authentication hooks for trees.

Configure SAML 2.0

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

Task	Resources
Configure an SP, an IdP, and a CoT Decide if AM will be an SP, an IdP, or both, and determine what metadata you need to import from other providers. For example, if AM is the IdP for another service, you must import the metadata of the remote SP. Ensure that SPs and IdPs that work together are in the same CoT.	Set up IdPs and SPs in a CoT
Secure your providers Configure signing and encryption secrets for your environment.	Sign and encrypt messages
Deploy the IdP discovery service If you have more than one IdP in your CoT, use the IdP discovery service as a proxy between SPs and IdPs.	Deploy the IdP Discovery service
Configure your environment for SSO and SLO AM provides integrated and standalone modes for implementing SSO and SLO. Choose the mode that’s most appropriate for your environment.	Implement SSO and SLO
Decide how to federate identities AM supports different ways to federate identities, depending on the configuration and whether user profiles already exist in the SP.	Federate identities
Configure AM as a SAML 2.0 Gateway for Legacy Applications Use AM Secure Attribute Exchange and PingGateway to integrate legacy applications into your SAML 2.0 deployment.	Implement a SAML 2.0 gateway by using Secure Attribute Exchange
Use fedlets as lightweight SPs AM provides Fedlets, which are small Java applications that can act as SPs without a full AM installation. Fedlets redirect to AM for SSO and to retrieve SAML assertions.	Implement SAML 2.0 SPs by using Fedlets

Task

Resources

Configure an SP, an IdP, and a CoT

Decide if AM will be an SP, an IdP, or both, and determine what metadata you need to import from other providers.

For example, if AM is the IdP for another service, you must import the metadata of the remote SP.

Ensure that SPs and IdPs that work together are in the same CoT.

Set up IdPs and SPs in a CoT

Secure your providers

Configure signing and encryption secrets for your environment.

Sign and encrypt messages

Deploy the IdP discovery service

If you have more than one IdP in your CoT, use the IdP discovery service as a proxy between SPs and IdPs.

Deploy the IdP Discovery service

Configure your environment for SSO and SLO

AM provides integrated and standalone modes for implementing SSO and SLO.

Choose the mode that’s most appropriate for your environment.

Implement SSO and SLO

Decide how to federate identities

AM supports different ways to federate identities, depending on the configuration and whether user profiles already exist in the SP.

Federate identities

Configure AM as a SAML 2.0 Gateway for Legacy Applications

Use AM Secure Attribute Exchange and PingGateway to integrate legacy applications into your SAML 2.0 deployment.

Implement a SAML 2.0 gateway by using Secure Attribute Exchange

Use fedlets as lightweight SPs

AM provides Fedlets, which are small Java applications that can act as SPs without a full AM installation. Fedlets redirect to AM for SSO and to retrieve SAML assertions.

Implement SAML 2.0 SPs by using Fedlets