---
title: Link identities for authentication
description: Link identities across identity providers and service providers using SAML 2.0 authentication trees and persistent federation
component: pingam
version: 8
page_id: pingam:am-saml2:linking-auth-tree
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/linking-auth-tree.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-07-02T16:13:42Z
keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Authentication", "Accounts", "Nodes & Trees", "Scripts"]
page_aliases: ["saml2-guide:linking-auth-tree.adoc"]
superseded_by: https://docs.pingidentity.com/pingam/8.1/am-saml2/linking-auth-tree.html
section_ids:
  first_authentication_to_the_sp: First authentication to the SP
  subsequent_authentications_to_the_sp: Subsequent authentications to the SP
  configure-authentication-linking: Configure authentication mechanisms to link accounts
  saml2-integrated-mode-sso-persistent-standard: Link accounts persistently (standalone AM)
  saml2-integrated-mode-sso-persistent-platform: Link accounts persistently (Ping Advanced Identity Software deployment)
---

# Link identities for authentication

IdPs and SPs must be able to communicate information about users. Sometimes the IdP chooses to share a minimum amount of information about an authenticated user.

For example, the IdP can return a generated, opaque `NameID` that can't directly be used to locate an identity in the SP identity store.

AM can use these pseudonym identifiers to establish links between otherwise unrelated accounts, by requiring that the user authenticates to the SP using a linking authentication mechanism.

## First authentication to the SP

The following flow shows the sequence of events that occurs when a user first attempts to authenticate to the AM SP:

![Sequence diagram: first authentication to the SP](_images/linking-auth-tree-first-auth.svg)Figure 1. First authentication to the SP flow

1. **Accessing the SP**

   A user attempts to access a service and is redirected to the AM server acting as the SP.

   The redirect URL specifies an authentication tree containing the [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/8/saml2.html). For example, `https://www.sp.com:8443/am/XUI/#login/&service=spSAMLTree`.

2. **Authentication at the IdP**

   AM redirects the user to the IdP. The user authenticates successfully at the IdP. The IdP returns a SAML assertion to AM.

3. **SP attempts to access a federated identity**

   AM attempts to locate the identity in its user store but finds no link between the IdP identity and a local identity.

4. **Invocation of the linking authentication node(s)**

   Because no link is found, AM uses the configured authentication tree to authenticate the user.

5. **Identity federation**

   After successfully authenticating the user, AM writes the name ID from the assertion into the user's local profile, creating a permanent link between the two identities.

   Find information on creating permanent links between identities in [Persistent or transient federation](persistent-or-transient-federation.html).

   Find an example of an authentication tree that links identities in [SSO and SLO in Integrated Mode](saml2-integrated-mode.html).

## Subsequent authentications to the SP

The following flow shows the sequence of events that occurs during subsequent authentication attempts after the user's identities on the IdP and SP have been federated:

![Sequence diagram: subsequent authentications to the SP](_images/linking-auth-tree-subsequent-auth.svg)Figure 2. Subsequent authentications to the SP flow

1. **Accessing the SP**

   A returning user attempts to access their service and is redirected to the AM server acting as the SP.

   Their login URL specifies the authentication tree containing the [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/8/saml2.html) and the [Write Federation Information node](https://docs.pingidentity.com/auth-node-ref/8/write-federation-information.html). For example, `https://www.sp.com:8443/am/XUI/#login/&service=spSAMLTree`.

2. **Authentication at the IdP**

   AM redirects the user to the IdP, and the user authenticates successfully at the IdP. The IdP returns a SAML assertion to AM.

3. **SP attempts to access a federated identity**

   AM attempts to locate the name ID in its user store. The search for the name ID succeeds.

   Because there's a match, the user doesn't need to authenticate to AM and can access the service.

## Configure authentication mechanisms to link accounts

If you aren't using auto-federation, configure AM to link accounts in one of the following ways, depending on whether AM is standalone or part of an integrated Ping Advanced Identity Software deployment.

### Link accounts persistently (standalone AM)

Configure a tree similar to the following:

![Example tree to link accounts persistently](../am-authentication/_images/trees-node-write-federation-information-example.png)

1. Add a [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/8/saml2.html).

   Integrated mode is SP SSO-initiated only. SLO isn't supported.

   Make sure that the NameID Format specified is `persistent`.

   The node processes the assertion, makes its contents available to the authentication tree's state in the `userInfo` object, and tries to map the assertion's nameID using the `uid` mapping in the SP's assertion map.

   If the node finds a match, the tree continues through the `Account Exists` output. Otherwise, the tree continues through the `No Account Exists` output.

2. On the `No Account Exists` outcome, configure nodes to authenticate the user to the SP.

3. Add a [Write Federation Information node](https://docs.pingidentity.com/auth-node-ref/8/write-federation-information.html).

### Link accounts persistently (Ping Advanced Identity Software deployment)

Configure a journey similar to the following:

![Example tree to link accounts persistently](_images/link-accounts-platform-example.png)

1. Add a [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/8/saml2.html).

   Integrated mode is SP SSO-initiated only. SLO isn't supported.

   Make sure that the NameID Format specified is `persistent`.

   The node processes the assertion, makes its contents available to the authentication tree's state in the `userInfo` object, and tries to map the assertion's nameID using the `uid` mapping in the SP's assertion map.

   If the node finds a match, the tree continues through the `Account Exists` output. Otherwise, the tree continues through the `No Account Exists` output.

   Note that the attribute the node uses to map the nameID isn't configurable, and this example adds nodes to process the `userInfo` object and match its contents to the managed user's schema instead.

2. Add a [Scripted Decision node](https://docs.pingidentity.com/auth-node-ref/8/scripted-decision.html) to copy the information from the assertion to the authentication tree's shared state.

   > **Collapse: Example script**
   >
   > * Next-generation
   >
   > * Legacy
   >
   > ```javascript
   > if (nodeState.get("userInfo")) {
   >   if (nodeState.get("objectAttributes")) {
   >     nodeState.remove("objectAttributes");
   >   }
   >   var userName=null,sn=null,mail=null;
   >
   >   try {
   >     var attribs = nodeState.get("userInfo")["attributes"];
   >
   >     userName=attribs["uid"][0];
   >     sn=attribs["sn"][0];
   >     mail=attribs["mail"][0];
   >
   >   } catch (e) {
   >     logger.error("Error getting userInfo: " + e);
   >   }
   >   nodeState.putShared("username", userName);
   >   nodeState.putShared("objectAttributes", {"userName":userName,"sn":sn,"mail":mail, "givenName": userName});
   > }
   > action.goTo("true");
   > ```
   >
   > ```javascript
   > var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);
   >
   > if (nodeState.get("userInfo")) {
   >   if (nodeState.get("objectAttributes")) {
   >     nodeState.remove("objectAttributes");
   >   }
   >   var userName=null,sn=null,mail=null;
   >
   >   try {
   >     var attribs = nodeState.get("userInfo").get("attributes");
   >
   >     userName=attribs.get("uid").get(0).asString();
   >     sn=attribs.get("sn").get(0).asString();
   >     mail=attribs.get("mail").get(0).asString();
   >
   >   } catch (e) {
   >     logger.error("Error getting userInfo: " + e);
   >   }
   >   nodeState.putShared("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
   > }
   > action = fr.Action.goTo("true").build();
   > ```
   >
   > For more information, see [Scripted Decision node API](../am-scripting/scripting-api-node.html).

3. Add an [Identify Existing User node](https://docs.pingidentity.com/auth-node-ref/8/identify-existing-user.html) to search the user with the appropriate attribute.

   For example, `userName`.

4. Authenticate the user to the SP.

5. Add the [Write Federation Information node](https://docs.pingidentity.com/auth-node-ref/8/write-federation-information.html) to the successful outcome of the authentication process to create the link between the accounts.

   If a transient link exists, it is converted into a persistent one.