ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: SAML2 federation in AM

Last updated Jan 16, 2023

The purpose of this FAQ is to provide answers to commonly asked questions regarding SAML2 federation in AM.

2 readers recommend this article

Frequently asked questions

Q. What is metadata?

A. The metadata file is an XML document that contains the information required to transmit an agreement between Identity and Service providers on how they want to set up the federation (through NameID) and where to reach the various services. This file contains settings such as endpoint URLs, supported bindings, identifiers and public keys.

Typically one metadata file will be generated by the service provider and sent to all identity providers they want to enable single sign-on with. Likewise, each identity provider will generate metadata to import into the service provider's application. Once they are imported, they can be changed through the AM admin UI or ssoadm. But if an element needed by the third party is modified, the third party must change its configuration accordingly. Similarly, if the third party were to change the service definition for example, you would need to delete the entity and reload it through the metadata file (you can also change it directly in the AM admin UI).

See How do I update metadata for an IdP or SP in AM (All versions) using ssoadm? for further information on changing metadata via ssoadm.


For a simplified overview of metadata specification with examples see SAML V2.0 Metadata. This non-normative document provides a consolidated overview of frequently used elements and attribute based on the normative specifications.

Q. What is the difference between standard and extended metadata?

A. The standard metadata is the information detailed in the Q. What is metadata? above; that is, the configuration information required by both parties to create the federation. The information contained within this file is defined by the SAML metadata XSD and only allows a very limited set of settings to be included, hence the majority of the signing/encryption related options are stored in the extended metadata for the given entity.

The extended metadata contains further configuration settings (outside of the SAML metadata XSD) that are nothing to do with the third party and are not shared with them. This includes custom authentication contexts, the majority of the signing / encryption related options, information such as the name of the COT an entity belongs to, whether a custom IdP adapter is implemented and any attribute mapping.


If you delete an entity provider, the configuration settings contained in the extended metadata will be lost; you should always back up your extended metadata file using ssoadm before you delete an entity provider. See How do I export and import SAML2 metadata in AM (All versions)? for further information.

Q. How do I share update metadata data with an entity provider?

A. When you update your metadata, you need to share it with other entity providers in the COT. You can do this by exporting it. See How do I export and import SAML2 metadata in AM (All versions)? for further information.

Q. Do I need to update the metadata for a hosted entity provider if I change the AM hostname?

A. No you do not. When you change the AM hostname as per Change host names, the hosted IdP or SP would be included in these changes. However, if you have any corresponding remote entity providers on a different AM instance, you would need to update them for SAML federation to continue working.

See How do I change the hostname for a remote IdP or SP entity in AM (All versions)? for further information.

Q. Can I change the metaAlias for an existing IdP or SP?

A. Yes, you can change the metaAlias for an existing IdP or SP by manually updating metadata.

See How do I change the metaAlias for an existing IdP or SP in AM (All versions)? for further information.


The metaAlias value for an entity provider must be unique within a deployment.

Q. How do I investigate metadata issues?

A. It is very important that your metadata is correct. If there is an issue, you will see errors such as the following when creating your entity provider or importing metadata:

Unexpected element {}:[attributename] Invalid metadata

You can increase debug logging to Message level as described in Debug logging (AM 7 and later) or How do I enable Message level debugging in AM 6.x debug files? and use the Federation and Configuration debug logs to help you find out more about the issue and correct your metadata. See How do I update metadata for an IdP or SP in AM (All versions) using ssoadm? for further information on updating your metadata.

If there is corruption in the XML file (such as junk or invisible characters), you will see an error like this in the Configuration debug log:

ERROR: XMLUtils.fatalError org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.

This error is typically caused by either non UTF-8 encoded characters, or 'invisible characters' before the XML document type declaration (before <?xml version="1.0" encoding="UTF-8"?>) which is not allowed in xml. You can use a hex editor to check if any characters come before the declaration.

Q. What format should SAML assertions use?

A. All SAML assertions should use the format as specified by the SAML standard.

Q. What EncryptionMethod algorithms are supported for encrypting assertions in AM?

A. AM supports the following algorithms for encrypting assertions:

Using any other algorithms will result in the following error when trying to federate:

HTTP Status 400 - Error processing AuthnRequest. Unsupported data encryption algorithm.

Q. How do I decrypt SAML assertions for troubleshooting?

A. When assertions are encrypted, the Federation debug log does not contain decrypted assertion details by default. However, you can configure AM to log decrypted messages to debug logs for troubleshooting purposes as follows.

AM 7 and later

In AM 7 and later, you can set the advanced openam.saml.decryption.debug.mode property. See SAML v2.0 advanced properties for further information.

AM 6.x

In AM 6.x, you can enable debug logging for unencrypted SAML assertions as follows:

  1. Log into the SP instance of AM as amAdmin.
  2. Navigate to: <protocol>://host.fqdn:port/am/Debug.jsp, for example: https://am.example.com:8443/am/Debug.jsp.
  3. Select Federation from the Category field, select Message from the Level field and then click Submit to change the debug level.
  4. Click TURN ON for the Debug encrypted SAML communications option, observing the warning that this outputs sensitive data to your logs.
  5. Click Confirm to save these debug settings. The decoded assertion XML from the IDP will now be output to the Federation debug log on the SP.

Please note the following caveats:

  • Using Debug.jsp is the only way to output decrypted assertions in debug logs in AM 6.x.
  • This setting only decrypts SAML assertions when enabled on the SP, and AM is both the SP and IdP.
  • The Debug.jsp page always shows the debug level as Error, regardless of its actual setting.
  • This setting is reset when you restart the server to ensure it is not left enabled permanently and therefore exposing sensitive information in the logs; it should only be enabled temporarily for troubleshooting purposes.

Q. How does AM determine if an attribute should be added?

A. All attributes are added to the assertion if they are available to the IdP and have been configured for a specific SP or IdP federation, otherwise they are omitted. Therefore, the addition of attributes depends on the specific federation.

Q. Which binding should I use for SAML federation?

A. This depends on the following factors:

  • Technical considerations, such as: Is there a direct path of communication between the two servers or is a user-agent needed?
  • Security considerations, such as: Is exposing the full content of the response through the user-agent considered acceptable or is encryption possible?

See How do I know which binding to use for SAML2 federation in Identity Cloud or AM (All versions)? for further information. You should also consult SAML bindings; in particular, you should look at sections: SAML SOAP Binding, HTTP Redirect Binding, HTTP POST Binding and HTTP Artifact Binding to understand the available options.

Q. Why can I only see the SAML request XML and not the response XML?

A. When you use the HTTP-Artifact binding, the SP only receives the artifact from the browser. The artifact is then sent directly to the IdP to retrieve the assertion. This process is done without the knowledge of the browser to prevent sensitive information being exposed through the browser.

If you need to see the SAML response XML, you can do one of the following:

  • Increase debug logging on your SP or IdP to Message; this will show the response XML in the Federation log.
  • Use the HTTP-POST binding instead of the HTTP-Artifact binding; this will show the response XML in the HTTP Trace.

Q. What do the permitted AuthComparison parameter values mean?

A. The AuthComparison parameter allows you to specify a comparison method to evaluate the requested context classes or statements. This parameter can be included in the RequestedAuthnContext sent by the SP and you can set this parameter in the SPssoInit.jsp page. The permitted values are:

  • better: the authentication context statement in the assertion must be better (stronger) than any of the other authentication contexts specified.
  • exact: the authentication context statement in the assertion must exactly match at least one of the authentication contexts specified.
  • maximum: the authentication context statement in the assertion must not be stronger than any of the other authentication contexts specified.
  • minimum: the authentication context statement in the assertion must be at least as strong as one of the authentication contexts specified.

Q. How do I exclude the SPNameQualifier from the AuthnRequest?

A. You can exclude the SPNameQualifier from the AuthnRequest by writing a custom SAML2ServiceProviderAdapter and implementing preSingleSignOnRequest. To get you started, you would need to do something like this:

public void preSingleSignOnRequest(String hostedEntityID, String idpEntityID, String realm, HttpServletRequest request, HttpServletResponse response, AuthnRequest authnRequest) throws SAML2Exception { authnRequest.getNameIDPolicy().setSPNameQualifier(null); }

Writing a custom SAML2ServiceProviderAdapter is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Q. Is there a limit to the number of remote IdPs I can have in a Circle of Trust (COT)?

A. No. The only potential limit is what your web application container can support; however, the impact of each remote IdP in a COT is minimal, so you should be able to easily add hundreds of remote IdPs to your COT if desired.

Q. Can I use the same IdP in multiple COTs?

A. Yes, you can use the same IdP in different COTs, but you must ensure the entity ID is unique. This is true regardless of whether the COTs are in the same or different realms.

Q. Can I have an IdP and SP on the same AM instance?

A. No, this is not recommended. When AM is used for SAML federation, it creates a session specific to the entity's role, which causes one session to be overwritten with another if you have both an IdP and SP on the same AM instance. For example, when you authenticate to the IdP, a session is created for the IdP role; as soon as the assertion is processed by the SP, the IdP session is overwritten with the SP session.

However, you can have an IdP and SP on the same AM instance if you use different cookie domains for each entity, for example:

sp.example.com idp.example.com

Q. Can I deploy an IdP proxy on the same AM instance that hosts the IdP?

A. Deploying the IdP proxy and the IdP on the same AM instance can work in some contexts and with some constraints, however, it is recommended that you avoid such a configuration as it adds complexity and can cause unexpected problems. It is preferable to use the same physical server and install two separate AM instances with different DNS; this setup works well in a test environment. In a production environment, there may be other considerations around sharing resources and you may need to have two separate servers.

If you do decide to deploy an IdP proxy and IdP on the same instance, you must be aware of the following constraints:

  • The IdP must be on a different realm to the IdP proxy since you cannot have two entities with the same entityID within one realm (as that would mean they were also in the same COT).
  • The cookie domains of the IdP proxy and IdP must be different. This is because a session is created both on the IdP proxy and the IdP during federation; since both are on the same AM instance, they cannot use a different cookie name; the only way for AM to distinguish between the two sessions is if the entities are on different cookie domains.

The only way to get different cookie domains is by creating a DNS Alias / Realm Alias for the relevant realm so the domain is presented as unique within an AM instance. See Realms for further information.

Q. How does the IdP Discovery Service determine which IdP to direct the user to?

A. The IdP Discovery Service uses the common domain cookie to determine where to send the user. If the common domain cookie does not exist, an error page is displayed.

To create the common domain cookie, at least one round trip must be completed with both the SP and IdP entities specified. This enables a mapping from the preferred IdP to the SP to be made (via an IdP initiated SSO request). After this, an SP initiated SSO request can be made without specifying the IdP entity ID; the value set in the common domain cookie from the first round trip will be used to redirect the user to the correct IdP.

See How do I configure IdP or SP initiated Single Sign On in Identity Cloud or AM (All versions)? for further information on IdP and SP initiated SSO requests.

Q. Can the integrated SAML2 authentication module derive the NameId format if it's not specified?

A. Yes, you can set the NameId format (forgerock-am-auth-saml2-name-id-format) to blank and it will be derived as follows:

  • If the IdP NameID Format list is empty: the first entry on the SP NameID Format list is used. If the SP list is also empty, then the default (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) is used.
  • If the IdP NameID Format list is not empty: the first entry on the SP NameID Format list that is also on the IdP NameID Format list is used. If the SP list is empty, then the first entry on the IdP NameID Format list is used.

See SAML2 authentication module properties for further information.

Q. Can I configure federation between AM and Active Directory Federation Services (ADFS)?

A. Yes you can. You can either configure AM or ADFS as the IdP as per your requirements. See How do I integrate ADFS with AM (All versions) using SAML2 federation? for further information on configuring this federation and correcting the metadata supplied by ADFS as it includes additional sections that are not supported by AM. You should remove these unsupported sections (ds: Signature, RoleDescriptor and SPSSODescriptor) leaving only the IDPSSODescriptor section.

Q. Is it possible to integrate a SP with AM if it does not support SAML?

A. You have the following options for integrating with AM if your SP does not support SAML:

Q. Why is the RelayState URL and SAML request ID the same for SAML requests generated by the AM fedlet?

A. AM fedlets store the actual RelayState URL in its memory cache. This RelayState cache is stored as a key:value pair, where key=SAML request ID and value=RelayState URL. The fedlet creates this RelayState cache when it sends the SAML request to the IdP (AM) with the RelayState URL as the SAML request ID. The IdP then sends back the SAML assertion with this RelayState URL, and the fedlet retrieves the actual value from its cache.

The example below shows the SAML request, where you can see that the SAML request ID and RelayState URL have the same value:

SAMLRequest: <samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="s23f07afde1d08f98011a2c0e8028a6fced006c9ea" Version="2.0" IssueInstant="2016-02-11T19:22:53Z" Destination="https://am.example.com:8443/am/SSORedirect/metaAlias/employees/idp" ForceAuthn="false" IsPassive="false" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="http://hrapp.external.net:8001/HR_App/fedletapplication" > <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">HR_App</saml:Issuer> </samlp:AuthnRequest> RelayState: s23f07afde1d08f98011a2c0e8028a6fced006c9ea

See Also

FAQ: SAML certificate management in AM 6.x

How does AM (All versions) use account mapping to identify the end user from a SAML Assertion?

How do I create a custom SAML2 IdP account mapper in AM (All versions)?

How do I create a custom SAML2 SP account mapper in AM (All versions)?

How do I create a hosted IdP or SP in AM (All versions) using ssoadm?

How do I create persistent SAML federation between two AM servers (All versions) where user attributes match?

How do I create a persistent SAML federation between two AM servers (All versions) where user attributes are different (and need mapping)?

What federation standards does AM support?

SAML 2.0 federation in AM

SAML v2.0

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.