---
title: Link identities for authentication
description: 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.
component: pingam
version: 8.1
page_id: pingam:am-saml2:linking-auth-tree
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/linking-auth-tree.html
keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Authentication", "Accounts", "Nodes & Trees", "Scripts"]
page_aliases: ["saml2-guide:linking-auth-tree.adoc"]
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 list describes the sequence of events that occurs the first time a user attempts to authenticate to the AM SP:

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.1/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 the SP.

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

   AM attempts to locate the identity in its own user store. No link between the IdP identity and a local one is found.

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

   Because no link is found, AM follows the route through the authentication tree that lets the user authenticate on the SP.

5. **Identity federation.**

   After successful authentication at the SP, AM writes the name ID from the assertion into the local user's 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 [Create accounts dynamically during federation](saml2-integrated-mode.html#saml2-integrated-mode-sso-dynamic-standard).

## Subsequent authentications to the SP

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

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.1/saml2.html) and the [Write Federation Information node](https://docs.pingidentity.com/auth-node-ref/8.1/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 the SP.

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 log in to the SP 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.1/saml2.html).

   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.1/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.1/saml2.html).

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

   The node processes the assertion, makes its contents available to the 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` outcome. Otherwise, the tree continues through the `No Account Exists` outcome.

   Regardless of the outcome, because the node's `nameID` mapping isn't configurable, this example adds nodes to process the `userInfo` object and match it to the managed user's schema.

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

   > **Collapse: Example next-generation script**
   >
   > ```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");
   > ```
   >
   > |   |                                                                                       |
   > | - | ------------------------------------------------------------------------------------- |
   > |   | You can also query the `samlApplication` binding on the SP side to get the assertion. |

3. Add an [Identify Existing User node](https://docs.pingidentity.com/auth-node-ref/8.1/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.1/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.