PingAM 8.0.0

SSO and SLO in integrated mode

Authentication nodes and trees support SSO in integrated mode only. The SAML2 Authentication node handles the SAML v2.0 authentication flow, but relies on other nodes.

Integrated mode flow
SAML v2.0 Integrated Mode Flow
Figure 1. SAML v2.0 Integrated Mode Flow

  1. An unauthenticated user initiates authentication to an AM SAML v2.0 SP. The login URL references an authentication tree that includes a SAML2 authentication node. For example, https://am.example.com:8443/am/XUI/?service=mySAM2LTree.

  2. If there are any authentication nodes that precede the SAML2 Authentication node, AM executes them.

  3. The SAML2 authentication node processing begins.

  4. The authentication node requests an assertion from the IdP. The configuration of the SAML2 Authentication node determines the details of the request.

    If the user is not authenticated in the IdP, the IdP will request them to authenticate.

  5. The IdP responds to the SP with a SAML assertion.

  6. If the SAML assertion contains a non-transient name ID, AM searches the identity store, attempting to locate a user with the same name ID.

    If the name ID for the account exists, the tree ends in the success node.

    If the name ID does not exist…​

  7. ... and a Create Object node (or a Provision Dynamic Account node for standalone AM environments) is configured in the tree, it creates a new account in the SP using auto-federation, including the name ID in the user profile.

  8. ... and method of authenticating the user is available in the tree, a Write Federation Information node writes the persistent name ID in the user profile.

    For more information about linking when autofederation is not configured, see Link identities for authentication.

Implement SAML v2.0 single sign-on in integrated mode

The following list is an overview of the activities you perform when implementing SAML v2.0 single sign-on in integrated mode:

  1. Preparing entity providers and a circle of trust, and changing several endpoints in the SP configuration.

    See Configure AM for integrated mode.

  2. Configuring a tree that contains, at least, the SAML2 authentication node.

    See Create accounts dynamically during federation (standalone AM) and Create accounts dynamically during federation.

Configure AM for integrated mode

  1. If you have not already done so, configure SAML v2.0 by performing the tasks listed in Deployment considerations.

  2. In the AM admin UI, create a hosted SP by following the steps in Create a Hosted Entity Provider.

    Ensure that you have configured the attribute map (Assertion Processing > Attribute Mapper). It determines how AM will map assertion attributes coming from the IdP to the user’s profile on the SP.

    During the authentication process, the mapping is used to find existing users on the SP, and to create or update user accounts on the SP.

  3. Configure a remote IdP by following the steps in Import and Configure a Remote Entity Provider.

    When you specify the circle of trust for the IdP, use the Add to Existing option and specify the circle of trust that you created when you created the hosted SP.

  4. Change the Assertion Consumer Service locations in the hosted SP configuration.

    The default locations support standalone mode. Therefore, you must change the locations when implementing integrated mode.

    Change the locations as follows:

    • In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > SP Name > Services > Assertion Consumer Service.

    • Change the location of the HTTP-Artifact consumer service to use AuthConsumer, rather than Consumer. For example, if the location is https://www.sp.com:8443/am/Consumer/metaAlias/sp, change it to https://www.sp.com:8443/am/AuthConsumer/metaAlias/sp.

    • Similarly, change the location for the HTTP-POST consumer service to use AuthConsumer rather than Consumer.

      Note that you do not need to change the location for the PAOS service because integrated mode does not support the PAOS binding.

    • The results will resemble the following:

      Editing the Consumer Service URLs for Integrated Mode.

      Save your changes. Now you are ready to configure authentication trees.

Create accounts dynamically during federation (standalone AM)

In integrated mode, the SP can use authentication trees to tailor the authentication experience to users. You can create very complicated trees, or even multiple trees to satisfy the requirements of your organization.

The example shown in this procedure uses the SAML v2.0 node to request an assertion from the IdP, and then creates an account for the user in the SP, if one does not exist.

If you are not using auto-federation, you can also use authentication trees to create persistent links between user accounts.

Perform the following steps to configure a tree similar to the following:

Example Tree with SAML2 Authentication Node
Figure 2. Example tree with SAML2 Authentication node

  1. Add a SAML2 Authentication node.

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

    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. Add a Provision Dynamic Account node to the No account exists outcome.

  3. (Optional) If you have not configured auto-federation, you can add the Write Federation Information node to create a persistent link between the accounts.

    For examples, see Link identities by using authentication trees.

Create accounts dynamically during federation

In integrated mode, the SP can use authentication trees to tailor the authentication experience to users. You can create very complicated trees, or even multiple trees to satisfy the requirements of your organization.

The example shown in this procedure uses the SAML v2.0 node to request an assertion from the IdP, and then creates an account for the user in the SP if one does not exist.

If you are not using auto-federation, you can also use authentication trees to create persistent links between the user accounts.

Perform the steps in this procedure to configure a tree similar to the following:

Example Tree to Create Accounts Dynamically
Figure 3. Example tree to create accounts dynamically

  1. Add a SAML2 Authentication node.

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

    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.

  2. 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("objectAttributes", {"userName":userName,"sn":sn,"mail":mail});
}
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.

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

    For example, userName.

  4. Complete the tree adding the required nodes to create the new account if it does not exist on the SP.

    The scripted decision node that you created before gathering the attributes that are now available to create the account. However, these may not be enough to satisfy your managed user rules. To ensure that the required attributes are available, use the Required Attributes Present node to check them, and the Attribute Collector node to collect the ones missing.

    Finally, to create the account, use the Create Object node.

    Ensure that you configure the appropriate identity resource in this node. For example, managed/alpha_user.

  5. (Optional) If you have not configured auto-federation, you can add the Write Federation Information node to create a persistent link between the accounts.

    For examples, see Link identities by using authentication trees.