Advanced Identity Cloud

PingOne Verify Evaluation node

The PingOne Verify Evaluation node leverages the PingOne Verify Service to initiate a new or continue an existing verification transaction.

It offers a range of delivery methods, such as a QR code, email, or SMS to start the identity verification process.

You can customize the verification types users can perform in the PingOne Verification Policy.

Learn more in Verify policies.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes 1

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

1 Currently available only in the rapid release channel.

Inputs

This node requires that the user has an account in the PingOne environment. It requires that the journey stored the PingOne user ID for the account in a shared state variable named pingOneUserId.

Use a PingOne Identity Match node to populate the shared state with the user’s PingOne ID.

If there’s a transaction ID in the shared state variable named pingOneVerifyTransactionId, this node continues that evaluation, rather than starting a new one.

Use a PingOne Verify Completion Decision node to determine the status of any previous transactions and populate the shared state with an in-progress transaction ID.

Dependencies

This node requires a PingOne Worker Service configuration so that it can connect to your PingOne instance and send it the necessary data to perform PingOne Verify evaluations as part of the journey.

You can find information on the properties used by the service in PingOne Worker service.

Configuration

Property Usage

PingOne Worker Service ID

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

Verify Policy ID

The ID of the policy to use for the PingOne Verify evaluation.

If not specified, the node uses the environment’s default Verify policy.

Verify URL delivery method

How the user will receive the URL they need to start a PingOne Verify evaluation.

Choose from:

QR Code

Display the URL as a QR code.

Email

Send an email containing the URL to the email address in the user’s PingOne Advanced Identity Cloud identity profile.

SMS

Send an SMS containing the URL to the phone number in the user’s PingOne Advanced Identity Cloud identity profile.

Redirect

Redirect the user to the PingOne Verify web app for identity verification.

On completion, redirect the user back to PingOne Advanced Identity Cloud to continue the authentication journey.

Default: QR Code

Allow user to choose the URL delivery method

When enabled, the node prompts the user to choose the URL delivery method.

Delivery method message

Add the text per locale to display when prompting the user to choose their delivery method:

  1. Click Add.

  2. In the Key field, enter the locale.1

    If the incoming HTTP request does not include the header or the preferred locales do not match any configured locales, the node uses the first text in the list.

  3. In the Value field, enter the text to display to the user.

    If you leave this blank, the node displays a localized version of the following text: Select the delivery method to start the identity verification process.

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

QR code message

Add the text per locale to display when you select QR code as the delivery method:

  1. Click Add.

  2. In the Key field, enter the locale.1

    If the incoming HTTP request does not include the header or the preferred locales do not match any configured locales, the node uses the first text in the list.

  3. In the Value field, enter the text to display to the user.

    If you leave this blank, the node displays a localized version of the following text: Scan the QR code to initiate the identity verification process.

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

Redirect message

Add the text per locale to display when you select Redirect as the delivery method, and the node redirects the user back to PingOne Advanced Identity Cloud to continue the journey:

  1. Click Add.

  2. In the Key field, enter the locale.1

    If the incoming HTTP request does not include the header or the preferred locales do not match any configured locales, the node uses the first text in the list.

  3. In the Value field, enter the text to display to the user.

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

Waiting message

Add the text per locale to display while waiting for the user to respond to the Verify transaction, when using the SMS or Email delivery methods:

  1. Click Add.

  2. In the Key field, enter the locale.1

    If the incoming HTTP request does not include the header or the preferred locales do not match any configured locales, the node uses the first text in the list.

  3. In the Value field, enter the text to display to the user.

    You can use the following variable in the Value field:

    {{verificationCode}}

    Replaced with a 6-digit code that the user can compare with the code displayed when they begin verification, to ensure it matches. For example, 981092.

    pingone verify verification code
    Figure 1. Compare the code displayed on screen with the code presented during verification.

    If you leave this blank, the node displays a localized version of the following text: Waiting for identity verification completion. Here is the code you will see on your device: {{verificationCode}}

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

Biographic Matching

Require that the specified data obtained from the user’s identity documents match the paired attribute in the user’s profile.

To create a pairing:

  1. Click Add.

  2. In the Key field, enter the biographic matching requirement.

    One of:

    referenceSelfie

    The photo the user took of themselves, in base64 encoded data form.

    phone

    The phone number obtained from the user’s identification.

    email

    The email address obtained from the user’s identification.

    given_name

    The first, or given name obtained from the user’s identification. For example, Babs.

    family_name

    The last, surname, or family name obtained from the user’s identification. For example, Jensen.

    name

    The full name obtained from the user’s identification. For example, Babs Jensen.

    address

    The address obtained from the user’s identification, as a single string. For example, 123 Any Street, London, United Kingdom, CH15 1EE.

    birth_date

    The date of birth obtained from the user’s identification.

  3. In the Value field, enter the attribute in the user’s PingOne Advanced Identity Cloud profile that should match.

    For example, you could pair the family_name biographic key to the sn profile attribute.

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

Store Verification Metadata

When enabled, store the verification metadata returned from PingOne Verify in shared state under a key named pingOneVerifyMetadata.

Example verification metadata 
{
    "_links":{
        "self":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6/metaData"
        },
        "user":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94"
        },
        "environment":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "verifyTransaction":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6"
        }
    },
    "_embedded":{
        "metaData":[
            {
                "_links":{
                    "self":{
                        "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6/metaData/4ebb9165-4e5c-4270-94e4-d50d7b17ecb4"
                    }
                },
                "id":"4ebb9165-4e5c-4270-94e4-d50d7b17ecb4",
                "provider":"IDRND",
                "type":"LIVENESS",
                "status":"SUCCESS",
                "data":{
                    "score":6.4909873,
                    "probability":0.99848527,
                    "quality":0.94462675
                },
                "retry":{
                    "attempt":2
                }
            },
            {
                "_links":{
                    "self":{
                        "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6/metaData/546d3a8e-f606-4078-92f1-96a5c2d003e9"
                    }
                },
                "id":"546d3a8e-f606-4078-92f1-96a5c2d003e9",
                "provider":"AMAZON",
                "type":"FACIAL_COMPARISON",
                "status":"SUCCESS",
                "data":{
                    "similarity":99.37002,
                    "confidence":99.99767,
                    "quality":{
                        "brightness":36.77353,
                        "sharpness":20.92731
                    }
                }
            },
            {
                "_links":{
                    "self":{
                        "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6/metaData/96315a69-fb46-4d28-9b0d-c79927e59df1"
                    }
                },
                "id":"96315a69-fb46-4d28-9b0d-c79927e59df1",
                "provider":"BIOGRAPHIC_MATCHER",
                "type":"BIOGRAPHIC_MATCH",
                "status":"SUCCESS",
                "data":{
                    "biographic_match_results":[
                        {
                            "identifier":"address",
                            "match":"NOT_APPLICABLE"
                        },
                        {
                            "identifier":"given_name",
                            "match":"NONE"
                        },
                        {
                            "identifier":"family_name",
                            "match":"HIGH"
                        },
                        {
                            "identifier":"birth_date",
                            "match":"HIGH"
                        }
                    ]
                }
            },
            {
                "_links":{
                    "self":{
                        "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6/metaData/fba13756-8c24-49ff-9b42-ff1a3661d0ae"
                    }
                },
                "id":"fba13756-8c24-49ff-9b42-ff1a3661d0ae",
                "provider":"MITEK",
                "type":"DOCUMENT_AUTHENTICATION",
                "status":"SUCCESS",
                "data":{
                    "mitekVerifications":[
                        {
                            "name":"Document Ensemble Authenticator",
                            "judgement":"Authentic",
                            "verificationType":202,
                            "probability":753,
                            "version":"3.47.0.7114",
                            "documentId":"048f28f1-a7fe-42a5-9722-f10977606719"
                        },
                        {
                            "name":"Black And White Copy",
                            "judgement":"Authentic",
                            "verificationType":102,
                            "probability":717,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"Image Classification",
                            "judgement":"Authentic",
                            "verificationType":105,
                            "probability":1000,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"Data Comparison",
                            "judgement":"Authentic",
                            "verificationType":700,
                            "probability":1000,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"Ensemble Authenticator",
                            "judgement":"Authentic",
                            "verificationType":201,
                            "probability":753,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"ID Document Blacklist",
                            "judgement":"Authentic",
                            "verificationType":101,
                            "probability":1000,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"Generic Font",
                            "judgement":"Authentic",
                            "verificationType":104,
                            "probability":926,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"MRZ Check Digit",
                            "judgement":"Authentic",
                            "verificationType":601,
                            "probability":1000,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"MRZ Font Type Authentication",
                            "judgement":"Authentic",
                            "verificationType":600,
                            "probability":1000,
                            "version":"3.47.0.7114",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"Image Processing",
                            "judgement":"Authentic",
                            "verificationType":710,
                            "probability":1000,
                            "version":"1.0",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        },
                        {
                            "name":"Document Liveness",
                            "judgement":"Authentic",
                            "verificationType":108,
                            "probability":999,
                            "version":"1.0",
                            "documentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856"
                        }
                    ],
                    "frontImageDocumentId":"e290d74d-bf9c-4116-9fe7-9b6fb909c856",
                    "documentEvidenceId":"048f28f1-a7fe-42a5-9722-f10977606719",
                    "retry":{
                        "attempt":1
                    }
                }
            }
        ]
    },
    "previousAttempts":[
        {
            "_links":{
                "self":{
                    "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/03df72b1-b80b-4449-8eef-ee8f85f48d94/verifyTransactions/7668563d-0226-4ca5-8401-03f6dc5bcdc6/metaData/06aebfbd-0053-4860-8b59-4f3cb7371dcb"
                }
            },
            "id":"06aebfbd-0053-4860-8b59-4f3cb7371dcb",
            "provider":"IDRND",
            "type":"LIVENESS",
            "status":"FAIL",
            "data":{
                "score":2.4509223,
                "probability":0.40062885,
                "quality":0.40874674
            },
            "retry":{
                "attempt":1
            }
        }
    ],
    "size":4
}
The key is empty if the node is unable to retrieve the verification metadata from PingOne.

Default: Disabled

Store Verified Data

When enabled, store a list of the verified data submitted by the user in shared state under a key named pingOneVerifyVerifiedData.

Example verified data 
{
    "_links":{
        "self":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a27dec16-1e80-4f10-a261-2cac46a12b78/verifyTransactions/0e2ed48f-6c3a-46c4-bcb5-3a6bd791348b/verifiedData/34613a50-672c-428f-8db9-c67fe09fc4cc"
        },
        "environment":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "user":{
            "href":"https://api.pingone.com/v1/users/a27dec16-1e80-4f10-a261-2cac46a12b78"
        },
        "transaction":{
            "href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a27dec16-1e80-4f10-a261-2cac46a12b78/verifyTransactions/0e2ed48f-6c3a-46c4-bcb5-3a6bd791348b"
        }
    },
    "id":"84170421-62c6-49a5-b343-496bee93c206",
    "type":"GOVERNMENT_ID",
    "createdAt":"2022-02-23T15:51:01.603Z",
    "data":{
        "addressCity":"this city",
        "addressState":"this state",
        "addressZip":"11111",
        "birthDate":"1970-01-01",
        "country":"USA",
        "expirationDate":"1970-01-01",
        "firstName":"given",
        "gender":"",
        "idNumber":"11111",
        "issueDate":"1970-01-01",
        "issuingCountry":"",
        "lastName":"surname",
        "nationality":"",
        "weight":""
    },
    "retry":{
        "attempt":1
    }
}
The key is empty if the node is unable to retrieve the verified data from PingOne.

Default: Disabled

Capture failure

Capture the details in shared state if a failure occurs.

The node stores the details in a variable named pingOneVerifyEvaluationFailureReason.

Default: False

Example:

{
  "code": "IDENTITY_VERIFICATION_FAILED",
  "message": "Identity verification failed.",
  "exception": "",
}

1 Specify a locale that Java supports, such as en-gb. Otherwise, the node throws a configuration exception with an Invalid locale provided message.

Outputs

  • If Allow user to choose the URL delivery method is selected, the node sends the following callbacks:

    TextOutputCallback

    Contains the Delivery method message.

    ConfirmationCallback

    Contains the options available to the client application.

  • When using the QR Code URL delivery method, the node sends the following callbacks:

    TextOutputCallback

    Contains the QR Code message.

    ScriptTextOutputCallback

    Contains JavaScript script to run to display the QR code.

    HiddenValueCallback

    Contains the actual URL to start the verification. The client might display this to users on a mobile device that cannot scan a QR code, or to render their own QR code, for example.

    PollingWaitCallback

    Waits for the user to complete the verification, and the Waiting message.

  • When using the Email or SMS URL delivery method, the node sends the following callbacks:

    PollingWaitCallback

    Waits for the user to complete the verification, and contains the Waiting message.

  • When using the Redirect delivery method, the node sends the following callbacks:

    RedirectCallback

    Contains the URI to redirect the user to for identity verification, using the PingOne Verify web application.

  • If you select Store Verification Metadata, the node outputs the verification metadata JSON in a state variable named pingOneVerifyMetadata.

    To learn more about verification metadata, refer to Read All Verification Metadata.

  • If you select Store Verified Data, the node outputs the verified information gathered from the user’s ID in a state variable named pingOneVerifyVerifiedData.

    To learn more about verified data, refer to Read One User Verified Data.

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

Outcomes

Success

The user successfully completed the PingOne Verify evaluation.

Failure

The user did not successfully complete the PingOne Verify evaluation, or an error occurred.

Time Out

The node did not receive a response from the user performing the verification before the timeout specified in the Verify Transaction Timeout property.

Example

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

Example PingOne Verify journey
Figure 2. Example PingOne Verify journey

  • The user enters their credentials, which the Data Store Decision node then verifies against the identity store.

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

  • 2 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 continue directly to the Success node, completing the authentication journey.

    Not Completed

    The user has an existing PingOne Verify transaction in progress, so continue the journey to resume 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 either does not have an existing transaction (Not Started), or did not successfully complete the most recent PingOne Verify transaction, or it expired, so continue the journey to start a new verification transaction.

  • 3 If a user is not found, the PingOne Create User node creates a new user in PingOne.

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

Copyright © 2010-2024 ForgeRock, all rights reserved.