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:
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.
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:
- 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):
- 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/OpenAM (All versions)? for further information.
- Create a hosted SP in AM against the third-party IdP (this hosted SP represents IG). See SAML v2.0 Guide › Configuring Identity Providers, Service Providers, and Circles of Trust for further information.
- 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).
- Create a fedlet configuration per step 3 in Gateway Guide › Configuring AM As an IDP.
- 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:
- Use AM to generate the metadata files and create a fedlet configuration (you can either use a fresh install or an existing install):
- 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.
- 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.