Link identities for authentication

Identity providers and service providers must be able to communicate about users. Yet, in some cases, the identity provider chooses to communicate a minimum of information about an authenticated user; for example, a generated, opaque NameID that cannot directly be used to locate to an identity in the SP identity store.

AM can use these pseudonym identifiers for establishing 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 service provider:

Figure 1. First authentication to the SP flow

Accessing the SP

A user attempts to access a service and is redirected to the AM server acting as the service provider, specifying the SAML 2.0 service in the login URL. For example:
- An authentication chain containing the SAML2 Authentication Module.
  
  For example, https://www.sp.com:8443/openam/XUI/#login/&service=spSAMLChain.
- An authentication tree containing the SAML2 Authentication node.
  
  For example, https://www.sp.com:8443/openam/XUI/#login/&service=spSAMLTree.
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.
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.
Invocation of the linking chain, or equivalent authentication node(s)

As no link is found, AM does one of the following:
- (Authentication chains) Invokes a linking authentication chain to determine which local user account to use.
- (Authentication trees) Goes through a path in the authentication tree that lets the user authenticate on the SP.
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.

For more information on creating permanent links between identities, see Persistent or transient federation

For an example of an authentication tree that links identities, see SSO and SLO in Integrated Mode.

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:

Figure 2. Subsequent authentications to the SP flow

Accessing the SP

A returning user attempts to access their service and is redirected to the AM server acting as the service provider. Their login URL specifies the SAML 2.0 login service. For example:
- An authentication chain containing the SAML2 Authentication Module.
  
  For example, https://www.sp.com:8443/openam/XUI/#login/&service=spSAMLChain.
- An authentication tree containing the SAML2 Authentication node and the Write Federation Information node.
  
  For example, https://www.sp.com:8443/openam/XUI/#login/&service=spSAMLTree.
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.
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

To configure AM to link accounts, see the following options:

Link identities by using a linking authentication chain

This procedure demonstrates how to link identities by using a linking authentication chain on the SP to identify the local user.

Before attempting to configure a linking authentication chain, ensure that you have configured AM for SAML 2.0, created the identity and service providers, and configured a circle of trust. You must also have configured AM to support single sign-on. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

On the hosted service provider, log in to the AM admin UI.
Create an authentication chain; for example, named myLinkingChain.

This chain is used to identify the user account in the SP to link to the account in the IDP. The chain can use any of the available methods for authentication as required; for example, multi-factor authentication.

For more information on creating authentication chains, see Configure AM for authentication.
If you are using integrated mode SSO:
- Go to Realms > realm name > Authentication > Modules, and then select the module name of your SAML2 authentication module.
- In the Linking Authentication Chain field, enter the name of the authentication chain you created earlier; for example, myLinkingChain.
- Save your work.
If you are using standalone mode SSO:
- Go to Realms > realm name > Authentication > Settings > Core.
- In the Organization Authentication Configuration property, select the authentication chain you created earlier; for example, myLinkingChain.
- Save your work.
  
  For more information on setting the default chain for a realm, see Configure sensible default authentication services.
To test your work, initiate single sign-on; for example, as described in SP-initiated SSO JSP.

Authenticate to the IDP as the demo user. You will then be redirected to the SP and asked to authenticate using the linking authentication chain specified. If persistent linking is enabled (the default), then initiating single sign-on a second time will require authentication only to the IDP.

Link accounts using authentication trees (standalone AM)

If you are not using auto-federation, perform the steps in this procedure to configure a tree similar to the following to link accounts persistently:

Add a SAML2 Authentication node.

Integrated mode is SP SSO-initiated only, and SLO is not supported.

Ensure 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.
On the No Account Exists outcome, configure nodes to authenticate the user to the SP.
Add a Write Federation Information node.

Link accounts persistently

If you are not using auto-federation, perform the steps in this procedure to configure a tree similar to the following to link accounts persistently:

Add a SAML2 Authentication node.

Integrated mode is SP SSO-initiated only, and SLO is not supported.

Ensure 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 is not configurable, and this example adds nodes to process the userInfo object and match its contents to the managed user’s schema instead.

Add a Scripted Decision node to copy the information from the assertion to the authentication tree’s shared state.

Example script

Next-generation
Legacy

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");

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.

Add an Identify Existing User node to search the user with the appropriate attribute.

For example, userName.
Authenticate the user to the SP.
Add the Write Federation Information node to the successful outcome of the authentication process to create the link between the accounts.

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

PingAM