Linking 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.

The following list describes the sequence of events that occurs the first time a user attempts to authenticate to the AM service provider:

  1. Accessing the service provider.

    A user attempts to access a service and is redirected to the AM server acting as the service provider, specifying the SAML v2.0 service in the login URL. For example:

    • An authentication tree containing the SAML2 Authentication Node.

      For example, https://www.sp.com:8443/openam/XUI/#login/&service=spSAMLTree.

  2. Authentication at the identity provider.

    AM redirects the user to the identity provider. The user authenticates successfully at the identity provider. The identity provider returns a SAML assertion to the SP.

  3. Service provider 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. Authenticating the user to the SP

    AM goes through a path in the authentication tree that lets the user authenticate on the SP.

  5. Identity federation.

    After successful authentication at the SP, AM then writes the name ID from the assertion into the local user’s 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.

The following list describes the sequence of events that occurs during subsequent authentication attempts, after the user’s identities on the identity and service providers have been federated:

  1. Accessing the service provider.

    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 v2.0 login service. For example:

  2. Authentication at the identity provider.

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

  3. Service provider attempts to access a federated identity.

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

    As there is a match, the user does not need to log in to the SP, and is given access to the service.

Configure Authentication Mechanisms to Link Accounts

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

To 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:

Example Tree to Link Accounts Persistently
  1. 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.

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

    Example Script
    outcome = "true";
    if (sharedState.get("userInfo")) {
    if (sharedState.get("objectAttributes")) {
    sharedState.remove("objectAttributes");
    }
    var userName=null,sn=null,mail=null;
    
        try { userName=sharedState.get("userInfo").get("attributes").get("uid").get(0).toString(); } catch (e) {}
        try { sn=sharedState.get("userInfo").get("attributes").get("sn").get(0).toString(); } catch (e) {}
        try { mail=sharedState.get("userInfo").get("attributes").get("mail").get(0).toString(); } catch (e) {}
    
      sharedState.put("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
    }

    For more information, see Scripted Decision Node API Functionality.

  3. Add a {Identify Existing User Node 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 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.