Deployment considerations

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

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

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

For more information about AM keystores, including location and different types of keystores available and how to change the default keys, refer to 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 v2.0 profiles. For more information, refer to Session state considerations.
Consider increasing DS search size limits if you intend to create a large number of SAML v2.0 entities. To ensure searches of defined entities work as expected, configure the DS search properties ds-rlim-size-limit and ds-rlimit-time-limit (DS 7.2 and later) or ds-rlim-lookthrough-limit (pre DS 7.2).

Learn more in Important Considerations in the following Knowledge Base Article: Issues with upgrades, Amster imports or exports, or registering clients (OAuth 2.0, OIDC and RADIUS) or Agents with reference to sunserviceID in PingAM.

Session state considerations

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

This combination lets AM instances continue single sign-on flows that started at a different instance, without needing sticky load balancing in most scenarios.

Single sign-on progress is stored in a JSON web token (JWT) in the browser’s session storage. 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 v2.0 SSO with clients that do not 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.

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

settings.setDomStorageEnabled(true)

You cannot use session storage when using multiple WebView components simultaneously. For more information, refer to 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. For more information, refer to Secrets, certificates, and keys.

Performing single log out (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 v2.0 single logout (SLO). The SOAP binding is not supported.

In addition, browsers allow cookie sizes between 4,000 and 5,200 bytes, depending on the browser. If you are using client-side sessions, some SAML v2.0 features may cause the cookie to surpass the browser’s supported cookie size; such as:

In standalone mode, when performing single sign-on 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 v2.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 plugin that removes unwanted properties or attributes, at the realm level. Note that removing properties or attributes in a custom SAML v2.0 SP adapter is not supported.

For more information about post-authentication plugins, refer to Create post-authentication plugins for chains.

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

Task	Resources
Configure an SP, an IDP, and a CoT. The first step is deciding if AM is the SP, the IDP, or both, and/or what metadata you need to import from other providers. For example, if AM is the IDP for another service in your environment, you will have to import the metadata of the remote SP. Ensure the SPs and IDPs that work together share the same CoT.	Configure IDPs, SPs, and CoTs
Make sure your providers are secure 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, the IDP discovery service acts like a proxy between the SPs and the IPDs.	Deploy the IDP Discovery service
Configure your environment for SSO and SLO AM provides two options for implementing SSO and SLO: integrated mode, and standalone mode. There are several considerations to make before deciding which mode is more appropriate for your environment.	Implement SSO and SLO
Decide how to federate identities AM supports different ways to federate identities depending of the configuration, and whether they exist or not in the SP.	Federate identities
Configure AM as a SAML v2.0 Gateway for Legacy Applications Use AM Secure Attribute Exchange and PingGateway to integrate legacy applications into your SAML deployment.	Implement a SAML v2.0 gateway by using Secure Attribute Exchange
Use fedlets instead of SPs AM provides Fedlets, which are a small Java applications that can act as the SP without installing AM. They can redirect to AM for SSO, and to retrieve SAML assertions.	Implement SAML v2.0 service providers by using Fedlets

Task

Resources

Configure an SP, an IDP, and a CoT.

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

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

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

Configure IDPs, SPs, and CoTs

Make sure your providers are secure

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, the IDP discovery service acts like a proxy between the SPs and the IPDs.

Deploy the IDP Discovery service

Configure your environment for SSO and SLO

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

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

Implement SSO and SLO

Decide how to federate identities

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

Federate identities

Configure AM as a SAML v2.0 Gateway for Legacy Applications

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

Implement a SAML v2.0 gateway by using Secure Attribute Exchange

Use fedlets instead of SPs

AM provides Fedlets, which are a small Java applications that can act as the SP without installing AM. They can redirect to AM for SSO, and to retrieve SAML assertions.

Implement SAML v2.0 service providers by using Fedlets

PingAM 7.5.1

Deployment considerations

Session state considerations