How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I configure IG (All versions) as a SAML2 SP to work with a third-party IdP?

Last updated Jan 11, 2023

The purpose of this article is to provide information on configuring IG as a SAML2 service provider (SP) for federation with a third-party IdP. Typically, IG is configured with AM as the IdP. This article assumes you already have the metadata from the IdP.

2 readers recommend this article


The SAML functionality in IG is based on the AM Fedlet, which is detailed in Implementing SAML v2.0 Service Providers by Using Fedlets. As a result, IG needs the following files in the $HOME/.openig/SAML directory in order for SAML2 federation to work:

  • fedlet.cot
  • idp-extended.xml
  • idp.xml
  • sp-extended.xml
  • sp.xml

The third-party IdP will have shared the standard metadata with you (equates to the idp.xml file), but you will need to create the extended metadata for the IdP plus the other files, as detailed in the following section. The extended metadata includes the extra configuration details such as signing, encryption and plugins.

NameID Formats

Support for NameID formats varies by version as follows:

  • IG 6.5.3 and later - All NameID formats are supported. See Using a Non-Transient NameID Format for further information.
  • Pre-IG 6.5.3 - only Transient NameID formats are supported by default. See below for information on using a non-Transient NameID format.

Using a non-Transient N ameID Format in pre-IG 6.5.3

If the IdP you are federating with supports a different NameID format (for example, Persistent), you should update the SP extended metadata (sp-extended.xml) to include the following property under the <SPSSOConfig... property:

<Attribute name="useNameIDAsSPUserID">    <Value>true</Value> </Attribute>

This useNameIDAsSPUserID attribute means that when the user is not found in the user store (which it never will be for IG), the default SP account mapper is triggered to use the NameID value from the IdP instead.

Additionally, you will need to do an IdP initiated SSO because an SP initiated SSO is hard-coded to only accept the Transient nameID. SLO is not affected by this hard-coding, so you can do an IdP or SP SLO as required.

Configuring IG as a SP

The following process details how to configure federation when you are using an IdP other than AM:

  1. Generate the necessary files. You can do this using one of the following approaches:
    • Use AM to generate the metadata files and create a fedlet configuration (you can either use a fresh install or an existing install):
      1. Import the third-party IdP standard metadata into the root realm as a remote IdP. See How do I export and import SAML2 metadata in AM (All versions)? for further information.
      2. Create a hosted SP in AM against the third-party IdP (this hosted SP represents IG). See Configuring IDPs, SPs, and CoTs for further information.
      3. Configure the SP and IdP as required in AM (ensure the extra configuration details such as signing/encryption and plugins match the requirements of both IDP/SP as these options will be stored in the extended metadata).
      4. Create a fedlet configuration per step 3 in Set Up SAML 2.0 SSO and Federation.
    • Create your own metadata, COT and property files using the following documentation links for reference; you should ensure you use the correct filenames as outlined in the Overview:
  2. Configure IG as the SP per the documentation: Set Up SAML 2.0 SSO and Federation :
    • If you used AM to generate the files in step 1, you must update the SP metadata to change all the AM based URLs to IG ones for the various endpoints.
    • If you created your own files in step 1, you should create the $HOME/.openig/SAML directory and copy the files into this new directory before proceeding with the remaining steps in the documentation.
  3. Pass the SP metadata files to your third-party IdP.

Each time you update your SP configuration in IG, you must pass the updated metadata file to your third-party IdP.

Conversely, if the IdP updates their metadata, those changes need to be reflected in the $HOME/.openig/SAML directory and may also require updates to the extended metadata for changes such as attribute mappings or signing.

See Also

How do I generate more detailed debug logs to diagnose an issue in IG (All versions)?

FAQ: SAML 2.0 federation in IG

SAML 2.0 federation in IG

Acting As a SAML 2.0 Service Provider

Related Training


Related Issue Tracker IDs

OPENIG-3525 (SamlFederationHandler should support other NameID formats options other than just transient)

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