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 identity providers or service providers.
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
uidto your partner's
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, see Configuring 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, see "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 property
For more information, refer to Important Considerations in Issues with upgrades, Amster imports or exports, or registering clients (OAuth 2.0, OIDC and RADIUS) or Agents with reference to sunserviceID in AM in the ForgeRock Knowledge Base.
SAML v2.0 functionality 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 enables AM instances to continue single sign-on flows that started at a different instance, without the need for sticky load balancing in most scenarios.
Single sign-on 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 AM instances. You must configure sticky load balancing to support SAML v2.0 SSO with clients that do not support local storage, and on IdP proxy implementations.
You can enable local storage support in WebView components on Android by using the following property:
You cannot use local storage when using multiple WebView components simultaneously. For more information, see WebSettings - setDomStorageEnabled in the Android Developers documentation.
The JWT created in the browser's local storage is encrypted using the
am.global.services.saml2.client.storage.jwt.encryption secret ID, which by default is mapped to the
directenctest certificate alias. For more information, see Configuring Secrets, Certificates, and Keys.
Performing single log out (SLO) operations when there is more than a single 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-based 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 (
FullLoginURLproperty) 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-based 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 service provider adapter is not supported.
For more information about post-authentication plugins, see "Creating Post-Authentication Plugins for Chains".
The following table summarizes the high-level tasks required to configure SAML v2.0:
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.
|Configuring IDPs, SPs, and CoTs
Make Sure Your Providers Are Secure
Configure signing and encryption secrets for your environment.
|Signing and Encryption
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.
|Deploying 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.
|Implementing 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.
Configure AM as a SAML v2.0 Gateway for Legacy Applications
Use AM Secure Attribute Exchange and IG to integrate legacy applications into your SAML deployment.
|Implementing 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.
|Implementing SAML v2.0 Service Providers by Using Fedlets