How To

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

Last updated May 10, 2019

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.


Overview

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 Using the Fedlet. As a result, IG needs the following files in the $HOME/.openig/SAML directory in order for SAML2 federation to work:

  • FederationConfig.properties
  • 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

By default, IG only supports Transient nameID formats although an RFE exists to change this: OPENIG-3525 (SamlFederationHandler should support other NameID formats options other than just transient). 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:
  2. Configure IG as the SP per the documentation: Gateway Guide › Configuring IG As an SP:
    • 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.
Note

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 collect debug logs in IG/OpenIG (All versions) for troubleshooting?

FAQ: SAML federation in IG/OpenIG

SAML federation in IG/OpenIG

Gateway Guide › Acting As a SAML 2.0 Service Provider

Related Training

N/A

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 © 2019 ForgeRock, all rights reserved.
Loading...