How To

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

Last updated Aug 10, 2020

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.


The SAML functionality in IG is based on the AM Fedlet, which is detailed in SAML v2.0 Guide › 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 7 and later - All NameID formats are supported. See Gateway Guide › Using a Non-Transient NameID Format for further information.
  • Pre-IG 7 - 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 7

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">

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:
  2. Configure IG as the SP per the documentation: Gateway Guide › 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 federation in IG/OpenIG

SAML federation in IG/OpenIG

Gateway Guide › 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)

OPENIG-409 (Fedlet should support nameid-format:persistent)

Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.