Authentication nodes

PingOne Identity Match node

The PingOne Identity Match node checks that users that exist in PingOne Advanced Identity Cloud also exist in the PingOne platform.

Example

The following example journey integrates PingOne Verify to perform user identity verification.

Example PingOne Verify journey
Figure 1. Example PingOne Verify journey

  • The user enters their credentials and the Data Store Decision node matches them against the identity store.

  • a The PingOne Identity Match node checks PingOne for a matching user.

  • b If a user is found, the PingOne Verify Completion Decision node checks the user’s most recent verification transaction to determine the status:

    Success

    The user successfully completed the most recent PingOne Verify transaction, so the journey progresses directly to the Success node and authentication is successful.

    Not Completed

    The user has an existing PingOne Verify transaction in progress, so the journey resumes the existing verification transaction.

    The node adds the user’s existing transaction ID to the shared node state in a variable named pingOneVerifyTransactionId.

    Not Started / Failure / Expired

    • The user doesn’t have an existing PingOne Verify transaction (Not Started)

    • The user hasn’t successfully completed the most recent PingOne Verify transaction

    • The most recent PingOne Verify transaction has expired

    The journey continues to start a new verification transaction.

  • c If no matching user is found, the PingOne Create User node creates a new user in PingOne.

  • d The PingOne Verify Evaluation node starts a new PingOne Verify evaluation or continues an existing evaluation if pingOneVerifyTransactionId is present in the shared node state. The node either completes or fails the journey based on the result.

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Advanced Identity Software (self-managed)

Yes

Inputs

This node reads the username field from the shared node state to access the user’s identity profile.

Implement a Platform Username node earlier in the journey.

Dependencies

This node requires a PingOne Worker Service configuration so that it can authenticate to your PingOne instance.

Find more information in Set up PingOne product connections.

Configuration

Property Usage

PingOne Worker service ID

The ID of the PingOne worker service for connecting to PingOne.

AM identity attribute

The attribute from the user’s PingOne Advanced Identity Cloud profile that the node uses to match their account in PingOne.

Default: uid

PingOne identity attribute

The attribute from the user’s PingOne profile that the node uses to search for a matching account.

If there are multiple entries with the same attribute value in the PingOne directory server, ensure that this property is specific enough to retrieve only one entry.

Default: username

Capture failure

Capture the details in shared state if a failure occurs.

The node stores the details in a variable named pingOneIdentityMatchFailureReason.

Default: False

Example:

{
  "code": "ACCESS_TOKEN",
  "message": "Unable to get access token for PingOne Worker.",
  "exception": "",
}

Outputs

If the node was able to find a unique match in PingOne it stores the PingOne user identifier in a state variable named pingOneUserId. For example a648aaac-ch15-b357-457b-8d2e714180ff.

If you select Capture failure, the node stores any error response in a shared state variable named pingOneIdentityMatchFailureReason.

Callbacks

This node doesn’t send any callbacks.

Outcomes

True

The node found a unique matching account in PingOne.

False

The node didn’t find a unique match in PingOne.

Errors

The node can log the following errors when it can’t find a unique matching user in PingOne:

  • Could not get the username from the context.

    The username property isn’t available in the shared node state. Use a preceding node to collect or set the username.

  • Unable to get access token for PingOne Worker.

    The node couldn’t obtain an access token for the configured PingOne Worker Service. Check the worker service configuration and permissions.

  • Could not get the value for the configured user attribute.

    The configured AM Identity Attribute isn’t available in the user’s profile. Check the attribute name and ensure the profile contains a value.

  • Found multiple entries with the same key attribute value in PingOne.

    The configured Ping Identity Attribute isn’t unique in PingOne. Choose a more specific attribute or remove duplicate values.

  • Could not find the identity with username in the realm.

    The node couldn’t find the identity associated with the username in the realm. Check that the identity exists and that the username is correct.

  • Error communicating with PingOne.

    The node couldn’t communicate with PingOne. Check the network connection, worker service configuration, and PingOne availability.

  • An unexpected error occurred.

    An unexpected error prevented the node from matching the user. Check the exception details stored in pingOneIdentityMatchFailureReason when Capture failure is enabled.