How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Sep 22, 2021

The purpose of this article is to create a persistent SAML federation between two AM servers in order to create federated Single Sign On (SSO) for accessing protected web content. It assumes you have set up two AM servers, the user attributes used for searching are different and therefore require mapping, you have at least two users created that exist on both servers and you have an Agent installed that protects your SP server. Importantly, you must have write access to the IdP's user data store to be able to save the mapping information.


1 reader recommends this article

Introduction

This example uses servers that have different unique identifiers, where the unique identifier is the attribute being used to identify and search for users, for example, uid or mail. Having different unique identifiers requires you to map the attributes used for searching and requires write access to the IdP's user data store. Sunkey values are used to store federation linking information when the two servers have different unique identifiers; by default, the two attributes used for storing this linking information are: sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey.

See How do I create persistent SAML federation between two AM servers where user attributes match? for further information about creating persistent SAML federation when you have servers with matching unique identifiers and/or do not have write access to the IdP's user data store.

Assumptions

Your URLs must be Fully Qualified Domain Names (FQDN), where one URL is for the SP and one is for the IdP.

The steps provided for creating a persistent federation use the following example URLs:

  • IdP - http://idp.acme.com:8080/openam
  • SP - http://sp.example.com:8080/openam

Additionally, these example steps assume the following is true:

  • An Agent is installed that protects your SP server (for example, http://sp.example.com:8080/openam).
  • Two Users have been created that exist on both servers; the steps provided for creating a persistent federation refer to example users: user1 and user2.
  • Both IdP and SP have AM schema.
  • You have write access to the IdP's user data store to be able to save the mapping information.

Create a hosted IdP and Circle of Trust on the IdP

AM 7 and later

  1. Log in to the console for the IdP.
  2. Navigate to Realms > [Realm Name] > Applications > Federation > Circles of Trust, click Add Circle of Trust and enter a name for the new COT, for example, COT1.
  3. Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Hosted and enter the required details including the new COT.
  4. Click Create to create the hosted IdP.

Pre-AM 7 

Note

The Signing Key has been left blank in this example, but you could use the built-in AM test key.

  1. Log in to the console for the IdP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new circle of trust (COT), for example, COT1.
  2. Click Configure to save your changes.
  3. Click the register a service provider link under the Register a Remote Service Provider section. You will need to return to this page once you have created the hosted SP provider.

Create a hosted SP and Circle of Trust on the SP

AM 7 and later

  1. Export the metadata for the IdP you just created. For example, you could use curl: $ curl --output metadata.xml http://idp.acme.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://idp.acme.com:8080/openam&realm=/See How do I export and import SAML2 metadata in AM (All versions)? for further information.
  2. Log in to the console for the SP.
  3. Navigate to Realms > [Realm Name] > Applications > Federation > Circles of Trust, click Add Circle of Trust and enter the name of the COT you created for the IdP, for example, COT1.
  4. Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Hosted and enter the required details including the new COT.
  5. Click Create to create the hosted SP.
  6. Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Remote, upload the IdP metadata you exported in step 1 and select the new COT.

Pre-AM 7  

  1. Log in to the console for the SP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider > New Circle of Trust and enter the name of the COT you created for the IdP, for example, COT1.
  2. Click Configure to save your changes.
  3. Click Yes when prompted to create a remote identity provider.
  4. Enter the following URL to indicate where the IdP metadata is located:  http://idp.acme.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://idp.acme.com:8080/openam&realm=/
  5. Click Configure to save your changes.
  6. Click OK when prompted that the identity provider has been configured.

Create a remote SP on the IdP

AM 7 and later

  1. Export the metadata for the SP you just created. For example, you could use curl: $ curl --output metadata.xml http://sp.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://sp.example.com:8080/openam&realm=/ See How do I export and import SAML2 metadata in AM (All versions)? for further information.
  2. Return to the console for the IdP.
  3. Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Remote, upload the SP metadata you exported in step 1 and select the new COT.

Pre-AM 7  

  1. Return to the console for the IdP.
  2. Enter the following URL to indicate where the SP metadata is located: http://sp.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://sp.example.com:8080/openam&realm=/
  3. Click Configure to save your changes.
  4. Click OK when prompted that the service provider has been configured.

Verifying COTs and providers

  1. Navigate as follows in both consoles and compare details:
    • AM 7 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Circles of Trust
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML

Both AM servers should have the same COT and entity providers that reference each other. Your Circle of Trust Configuration should look similar to this:

Testing federation

Note

Once federation has been established, you will only need to log in once (through the IdP) in future.

  1. Clear your browser cookies and enter the following SSO URL to log in: http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2FopenamThe browser will redirect to http://idp.acme.com:8080/openam
  2. Log in with user1. The browser will redirect back to http://sp.example.com:8080/openam
  3. Log in with user1. Federation is now established between your IdP and SP. The SP will confirm SSO by displaying the message “Single Sign-on succeeded.”
  4. Enter the following Single Logout (SLO) URL to log out: http://sp.example.com:8080/openam/SPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST The SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Checking user data store on directory servers (Optional)

You can optionally check the user data store on the directory servers for both servers to see the two attributes used for linking the user accounts:

sp.example.com (SP)

Actual Values:

  • sun-fm-saml2-nameid-info: http://sp.example.com:8080/openam|http://idp.acme.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV |http://idp.acme.com:8080/openam|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|null|http://sp.example.com:8080/openam|SPRole|false
  • sun-fm-saml2-nameid-infokey: http://sp.example.com:8080/openam|http://idp.acme.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV

idp.acme.com (IdP)

Actual Values:

  • sun-fm-saml2-nameid-info: http://idp.acme.com:8080/openam|http://sp.example.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV |http://idp.acme.com:8080/openam|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|null|http://sp.example.com:8080/openam|IDPRole|false
  • sun-fm-saml2-nameid-infokey: http://idp.acme.com:8080/openam|http://sp.example.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV

The NameID used to link the user from IdP to SP is: WyJW0z79g0UCvIbsOGhX8tdXcPEV

Map attributes on IdP

  1. Return to the console for the IdP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers.
  2. Click the name of the entity provider that is of type Remote SP. In this example, this is: http://sp.example.com:8080/openam
  3. Navigate to Assertion Processing > Attribute Mapper > Attribute Map and map the IdP user attribute to the SP user attribute. For example, if the attribute on the IdP is EmailAddress and the corresponding attribute on the SP is mail, you would enter EmailAddress=mail in pre-AM 7.
  4. Click Save to save your changes.

Enable auto federation on SP

  1. Return to the console for the SP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers.
  2. Click the name of the entity provider that is of type Hosted SP. In this example, this is: http://sp.example.com:8080/openam
  3. Navigate to: Assertion Processing > Auto Federation and select the Enabled option to enable auto federation.
  4. Enter the SP attribute specified in the previous section in the Attribute field. In this example, this is mail.
  5. Click Save to save your changes.

Testing federation

  1. ​Clear your browser cookies and enter the following SSO URL to log in: http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2FopenamThe browser will redirect to http://idp.acme.com:8080/openam
  2. Log in with user2. The browser will redirect back to http://sp.example.com:8080/openam but log in will not be required this time as federation is already established. The SP will confirm SSO by displaying the message “Single Sign-on succeeded.”
  3. Enter the following SLO URL to log out: http://sp.example.com:8080/openam/SPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POSTThe SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the Agent to use federation

  1. Return to the console for the SP:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or Java > [Agent ID] > AM Services and modify the AM Login URL value to point to the spSSOInit.jsp of the SP server: http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
  2. Navigate to Logout URL on the same page and modify OpenAM Logout URL value to point to SPSloInit: http://sp.example.com:8080/openam/SPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Testing the Agent

  1. Clear your browser cookies and enter the URL that the agent is protecting. The browser will redirect to http://idp.acme.com:8080/openam
  2. Log in with user2. The browser will redirect back to the URL that the agent is protecting.
Note

Federation was used to authenticate the user at the IdP and policy evaluation took place on the SP. 

See Also

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

FAQ: SAML federation in AM

How do I configure IdP or SP initiated Single Sign On in AM (All versions)?

How do I configure IdP or SP initiated Single Logout in AM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM (All versions)?

SAML Federation in AM

SAML v2.0 Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


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