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

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.

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 (All versions) 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 - https://idp.example.com:8443/am
• SP - https://sp.example.com:8443/am

Additionally, this example procedure assumes the following is true:

• An Agent is installed that protects your SP server (for example, https://sp.example.com:8443/am).
• 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 AM admin UI 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.

AM 6.x

1. Log in to the AM admin UI for the IdP and navigate 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 https://idp.example.com:8443/am/saml2/jsp/exportmetadata.jsp?entityid=https://idp.example.com:8443/am&realm=/See How do I export and import SAML2 metadata in AM (All versions)? for further information.
2. Log in to the AM admin UI 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.

AM 6.x

1. Log in to the AM admin UI for the SP and navigate 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: https://idp.example.com:8443/am/saml2/jsp/exportmetadata.jsp?entityid=https://idp.example.com:8443/am&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 https://sp.example.com:8443/am/saml2/jsp/exportmetadata.jsp?entityid=https://sp.example.com:8443/am&realm=/See How do I export and import SAML2 metadata in AM (All versions)? for further information.
2. Return to the AM admin UI 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.

AM 6.x

1. Return to the AM admin UI for the IdP.
2. Enter the following URL to indicate where the SP metadata is located: https://sp.example.com:8443/am/saml2/jsp/exportmetadata.jsp?entityid=https://sp.example.com:8443/am&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 admin UIs and compare details:
   • AM 7 and later admin UI: navigate to Realms > [Realm Name] > Applications > Federation > Circles of Trust
   • AM 6.x admin UI: navigate to Realms > [Realm Name] > Applications > Federation

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

1. Clear your browser cookies and enter the following SSO URL to log in: https://sp.example.com:8443/am/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/amThe browser will redirect to https://idp.example.com:8443/am
2. Log in with user1. The browser will redirect back to https://sp.example.com:8443/am
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: https://sp.example.com:8443/am/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/amor https://sp.example.com:8443/am/SPSloInit?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/amThe 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 AM admin UI for the IdP and navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers.
2. Click the name of the entity provider that is of type Remote SP. In my example, this is: https://sp.example.com:8443/am
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 (AM 6.x).
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: https://idp.example.com:8443/am
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 AM admin UI for the SP and navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers.
2. Click the name of the entity provider that is of type Hosted SP. In this example, this is: https://sp.example.com:8443/am
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 (AM 6.x).
4. Remove all values in the NameID Format List (AM 7 and later) or NameID Value Map (AM 6.x) 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: https://sp.example.com:8443/am/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/amThe browser will redirect to https://idp.example.com:8443/am
2. Log in with user2. The browser will redirect back to https://sp.example.com:8443/am 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: https://sp.example.com:8443/am/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/amThe SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the Agent to use federation

1. Log into the AM admin UI for the SP and navigate to the Realm which holds the Agent Profile:
   • AM 7.1.2 and later admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Web or Java > [Agent ID] > AM Services and modify the AM Login URL List value to point to the spSSOInit.jsp of the SP server:https://sp.example.com:8443/am/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/am
   • Pre-AM 7.1.2 admin UI: 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 per above example URL.
2. Navigate to Logout URL on the same page and modify OpenAM Logout URL value to point to spSingleLogoutInit.jsp https://sp.example.com:8443/am/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=https://idp.example.com:8443/am

Testing the Agent

1. Clear your browser cookies and enter the URL that the agent is protecting. The browser will redirect to https://idp.example.com:8443/am
2. Log in with user2. The browser will redirect back to the URL that the agent is protecting.​

See Also

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

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

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

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

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

SAML 2.0 federation in AM

SAML v2.0

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Related Issue Tracker IDs

N/A