PingAM

SSO in integrated mode

The SAML2 Authentication node handles the SAML 2.0 authentication flow but relies on other nodes to support the authentication experience.

Integrated mode supports SSO only.

SP-initiated SSO in integrated mode

This flow uses a SAML2 Authentication node in a tree on the SP. The node handles the SAML 2.0 protocol details for you.

When an end user initiates a SAML SSO flow, for example, by clicking a link to a resource on the SP’s website, they’re redirected to the IdP for authentication. On successful authentication, the flow returns to the SP for completion of the authentication journey.

Example SP-initiated SSO flow in integrated mode
In this diagram, AM is configured as a SAML 2.0 SP. A user requests authentication to an AM authentication tree that contains the SAML2 Authentication node.
Figure 1. SAML 2.0 SP-initiated SSO integrated mode flow

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

  2. AM runs the authentication tree until it reaches the SAML2 Authentication node, which it then starts to process.

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

  4. If the user isn’t authenticated in the IdP, the IdP will request them to authenticate.

    The user provides their credentials for validation.

  5. Authentication is successful.

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

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

  8. If the name ID for the account exists, the tree continues.

  9. If the name ID doesn’t exist and the tree has a Create Object node (or a Provision Dynamic Account node for standalone AM environments), it creates a new account in the SP using auto-federation, including the name ID in the user profile.

  10. If the name ID doesn’t exist, and the following is configured:

    • The name ID format is persistent

    • The tree has a method of authenticating the user

    • The tree has a Write Federation Information node

    Then the node authenticates the user...

  11. ... and writes the persistent name ID in the user profile.

    Learn more about linking when auto-federation isn’t configured in Link identities for authentication.

  12. AM continues to process the remaining nodes in the tree...

  13. ... and authentication is successful.

IdP-initiated SSO in integrated mode

In an IdP-initiated SSO flow using integrated mode, an end user authenticates with the IdP and is redirected to the SP. When the SP receives the SAML response, the flow continues to the authentication tree configured on the hosted SP. If no tree is set, the flow results in an error.

You still need to trigger IdP-initiated SSO using a URL.

Example IdP-initiated SSO flow in integrated mode
In this diagram, AM is configured as a SAML 2.0 SP. An authenticated user is redirected to an AM authentication tree.
Figure 2. SAML 2.0 IdP-initiated SSO integrated mode flow

  1. An end user initiates authentication to a third-party SAML 2.0 remote IdP.

  2. If the user isn’t authenticated in the IdP, the IdP requests their credentials.

    The user provides their credentials for validation.

  3. Authentication is successful.

  4. The IdP creates a SAML response containing a signed SAML assertion and sends it to the SP’s assertion consumer service URL, typically using the HTTP POST binding.

  5. The SP processes the assertion and redirects the SAML flow to the URL set as Redirect Tree Name or Local Authentication URL in the hosted SP configuration.

  6. If the tree has a Scripted Decision node, AM runs the script, including any logic to validate the assertion.

    You can use the getAssertion method of the samlApplication binding to check details in the assertion.

  7. If the tree has a SAML2 Authentication node, it checks whether the IdP entity ID in the assertion matches the one set in configuration.

  8. The SAML2 Authentication node can also use the nameID to locate a user in the identity store.

    You can also temporarily federate accounts with an SP account mapper script.

  9. AM continues to process the remaining nodes in the tree...

  10. ... and authentication is successful.

Implement SAML 2.0 SSO in integrated mode

Complete the following tasks to implement SAML 2.0 SSO in integrated mode:

  1. Prepare entity providers and a circle of trust, and update endpoints in the SP configuration.

    Learn more in Configure AM for integrated mode.

  2. Configure a tree that includes the SAML2 authentication node.

    Learn more in Create accounts dynamically during federation.

Configure AM for integrated mode

  1. If you haven’t already done so, configure SAML 2.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 IdP or SP.

    Make sure you have configured the attribute map (Assertion Processing > Attribute Mapper). It determines how AM maps assertion attributes 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.

    For IdP-initiated SSO, you must configure a redirect tree for the hosted SP to run after validating the IdP response.

  3. Configure a remote IdP by following the steps in Import a remote IdP or SP.

    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 only, so you must update them when implementing integrated mode:

    • In the AM admin UI, go to Realms > realm name > Applications > Federation > Entity Providers > hosted SP > 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.

      You don’t need to change the location for the PAOS service because integrated mode doesn’t support the PAOS binding.

    • The results will resemble the following:

      Editing the Consumer Service URLs for Integrated Mode.

      Save your changes.

You can now configure authentication trees for your SAML flow, for example, to dynamically create end user accounts.

Create accounts dynamically during federation

For SP-initiated flows, you can use trees to create an account for the user in the SP if one doesn’t exist.

If you aren’t using auto-federation, you can also use trees to create persistent links between user accounts.

Configure a tree similar to the following to create accounts dynamically:

  • Standalone AM

  • Ping Advanced Identity Software

Example tree with SAML2 Authentication node
Figure 3. Example tree with SAML2 Authentication node

  1. Add a SAML2 Authentication node.

    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.

    To verify or inspect the SAML flow, place a Scripted Decision node after the SAML node and query the samlApplication binding.

  2. Add a Provision Dynamic Account node to the No account exists outcome.

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

    Find examples in Link identities by using authentication trees.

Example tree for creating accounts dynamically
Figure 4. Example tree to create accounts dynamically

  1. Add a SAML2 Authentication node.

    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 to copy the information from the assertion to the authentication tree’s shared state.

    Example next-generation script 
    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");

    To verify or inspect the SAML flow, query the samlApplication binding from a Scripted Decision node placed after the SAML node.

  3. Add an Identify Existing User node to search for the user with the appropriate attribute, for example, userName.

    If AM finds an existing matching user, the tree succeeds and the user is authenticated.

  4. Add nodes to create the new account if AM doesn’t find a matching user on the SP.

    The Scripted Decision node adds the attributes collected from the SAML assertion to the tree’s shared state. If additional attributes are required to create an account, use the Required Attributes Present node to identify missing ones and the Attribute Collector node to collect them.

    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 haven’t configured auto-federation, you can add the Write Federation Information node to create a persistent link between the accounts.

    Find examples in Link identities by using authentication trees.