How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Sep 22, 2021

The purpose of this article is to demonstrate how to create 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 match, you have at least two users created that exist on both servers and you have an Agent installed that protects your SP server. This example uses SP initiated SSO.


1 reader recommends this article

Introduction

By default, to establish persistent federation AM writes two attributes to the users entry in each repository: sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info. The sun-fm-saml2-nameid-infokey contains a unique Identifier used to link the two accounts, by default this a randomly generated key that is common between the IdP and SP. After the initial Federation link is established, only a single login (on the IdP) will be required. These Sunkey values used to store federation linking information require write access to the IdP's user data store.

Note

In situations where one or both of the user data stores are read-only and/or no schema modifications are allowed, you can also achieve persistent federation using transient federation if required. In contrast to persistent federation, transient federation has no user mapping. All users authenticated by an IdP map to a single pre-determined or anonymous user account on the SP; this option is less common as most SPs will want to know the identity of users accessing their systems. Transient federation uses nameid-format:transient instead of nameid-format:unspecified. This article gives you both the persistent federation option and the transient federation option at the relevant points in the procedure for you to pick the required one to use.

In the example procedure in this article, we link two accounts that share unique identifiers, where the unique identifier is the naming attribute used to find the users account, for example, uid or cn. Having the same unique identifier is simpler as it does not require you to map these attributes. 

See How do I create a persistent SAML federation between two AM servers where user attributes are different (and need mapping)? for further information about creating persistent SAML federation if you do need to map these attributes.

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, this example procedure assumes 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. (See Transient option if data stores are read-only and/or no schema modifications are allowed).

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://idp.acme.com:8080/openamThe 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.” After the initial Federation link is established, only a single login (on the IdP) will be required.
  4. Enter one of the following Single Logout (SLO) URLs to log out:  http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openamor  http://sp.example.com:8080/openam/SPSloInit?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openamThe SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the IdP to prevent sunkey values being used

  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 my example, this is: http://sp.example.com:8080/openam
  3. Navigate to: Assertion Content > NameID Format and enable the Disable NameID persistence option (AM 7 and later) or select the Disable Federation persistence if NameID Format is unspecified option (pre-AM 7).
  4. Click Save to save your changes and return to the list of Entity Providers.
  5. Click the name of the entity provider that is of type Hosted IdP. In my example, this is: http://idp.acme.com:8080/openam
  6. Navigate to: Assertion Content > NameID Format > NameID Value Map and remove the urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified= value if it's there. Add one of the following new values:
    • Persistent federation - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified=uid
    • Transient federation - urn:oasis:names:tc:SAML:2.0:nameid-format:transient=uid
  7. Click Save to save your changes.

Modifying the SP to prevent sunkey values being used

  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 Content > NameID Format and enable the Disable NameID persistence option (AM 7 and later) or select the Disable Federation persistence if NameID Format is unspecified option (pre-AM 7).
  4. Remove all values in the NameID Format List (AM 7 and later) or NameID Value Map (pre-AM 7) apart from one; leave only one of the following values:
    • Persistent federation - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    • Transient federation - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  5. Click Save to save your changes.
  6. Navigate to: Assertion Processing > Account Mapper and enable/select the Use Name ID as User ID option.
  7. 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://idp.acme.com:8080/openamThe 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/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openamThe SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the Agent to use federation

  1. Log into the console for the SP and navigate to the Realm which holds the Agent Profile:
    • 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://idp.acme.com:8080/openam
    • 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 spSingleLogoutInit.jsp http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam

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 a persistent SAML federation between two AM servers where user attributes are different (and need mapping)?

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.