Advanced Identity Cloud

PingOne Protect Initialization node

The PingOne Protect Initialization node instructs the SDK to initialize the embedded PingOne Protect SDK on the client device using the configuration provided by the node properties.

Learn more in Threat Protection using PingOne Protect.

You can only initialize the PingOne Protect SDK on the client device once. Attempting to initialize the SDK with a different configuration will not override the initial settings.

You should initialize the PingOne Protect SDK on the client device as early as possible so that it can gather sufficient contextual information to make risk evaluations.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node has no required predecessor nodes.

It does not read from the shared node state.

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 make risk evaluations as part of the journey.

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

The client application must be using ForgeRock SDK 4.4.0 or later.

Configuration

Property Usage

PingOne Worker Service ID

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

Enable SDK Logs

When enabled, output SDK log messages in the developer console.

Default: Disabled

Device Attributes To Ignore

A list of device attributes you want to exclude from the results when collecting device signals. These attributes will not be sent to PingOne to perform evaluations, which might limit its ability to create accurate results.

Some examples of attributes the client might obtain from the device include:

  • BATTERY_LEVEL

  • CPU_ARCHITECTURE

  • DEVICE_MODEL

  • DEVICE_VENDOR

  • GPS_SUPPORTED

  • HAS_CHROME_APP

  • IS_ACCEPT_COOKIES

  • NAVIGATOR_USER_AGENT

  • OS_NAME

  • OS_VERSION

  • RESOLUTION

  • TOUCH_SUPPORT

The attributes collected vary depending on the OS of the client.

For example, an Android device might provide different attributes to a JavaScript app running on Windows.

Custom Host

Deprecated. We recommend that you do not change this property.

Lazy Metadata

When enabled, calculate metadata on demand.

When not enabled, metadata is calculated automatically after initialization.

Default: Disabled

Collect Behavioral Data

When enabled, collect behavioral data.

When not enabled, behavioral data is not collected.

Default: Enabled

Disable Hub

When selected, the client stores device data in the browser’s localStorage only.

When not selected, an iframe is used.

Default: Not selected

Device Key Rsync Intervals (days)

Number of days that device attestation can rely upon the device fallback key.

Default: 14

Enable Trust

Tie the device payload to a non-extractable crypto key stored in the browser for content authenticity verification

Disable Tags

When selected, the client does not collect tag data. Tags are used to record the pages the user visited, forming a browsing history.

Default: Not selected

Outputs

The node sends a PingOneProtectInitializeCallback to the client application.

The ForgeRock SDKs consume this callback and initialize the PingOne Protect functionality so it can start gathering the data it needs to make risk evaluations.

Outcomes

True

The client application confirmed successful receipt of the configuration.

False

The client application did not confirm successful receipt of the configuration or returned a client error.

Example

The following example journey leverages PingOne Protect functionality to perform a risk evaluation on a client app. The client app is built using the ForgeRock SDKs.

Example PingOne Protect journey
Figure 1. Example PingOne Protect journey

  • 1 The PingOne Protect Initialization node instructs the SDK to initialize the PingOne Protect Signals API with the configured properties.

    Initialize the PingOne Protect Signals API as early in the journey as possible, before any user interaction.

    This enables it to gather sufficient contextual data to make an informed risk evaluation.

  • The user enters their credentials, which are verified against the identity store.

  • 2 The PingOne Protect Evaluation node performs a risk evaluation against a risk policy in PingOne.

    The example journey continues depending on the outcome:

    High

    The journey requests that the user respond to a push notification.

    Medium or Low

    The risk is not significant, so no further authentication factors are required.

    Exceeds Score Threshold

    The score returned is higher than the configured threshold and is considered too risky to complete successfully.

    Failure

    The risk evaluation could not be completed, so the authentication attempt continues to the Failure node.

    BOT_MITIGATION

    The risk evaluation returned a recommended action to check for the presence of a human, so the journey continues to a CAPTCHA node.

    AITM_MITIGATION

    The risk evaluation returned a recommended action regarding the possible presence of an adversary-in-the-middle attack, so the journey continues to the Failure node.

    ClientError

    The client returned an error when attempting to capture the data to perform a risk evaluation, so the authentication attempt continues to the Failure node.

  • 3 An instance of the PingOne Protect Result node returns the Success result to PingOne, which can be viewed in the console to help with analysis and risk policy tuning.

  • 4 A second instance of the PingOne Protect Result node returns the Failed result to PingOne, which can be viewed in the console to help with analysis and risk policy tuning.