Connectors

PingOne Protect Connector

This connector lets you use PingOne Protect in a PingOne DaVinci flow to improve the user experience, reduce multi-factor authentication (MFA) fatigue, lower the probability of unintentional push approvals, and issue challenges or deny access in high-risk situations.

PingOne Protect is a cloud-based service that applies machine learning and configurable, intelligent security policies to analyze user identity and detect potential threats. PingOne Protect combines multiple risk factors to calculate an overall risk score.

When you add a PingOne Protect connector in a flow, you can define different paths based on the recommended action (when available), the risk level, or the risk score calculated by PingOne Protect in a risk evaluation. For example:

  • Skip the MFA challenge for low risk.

  • Use a specific authentication method if user behavior data suggests medium or high risk.

  • Block access completely for high risk, such as when the recommended action is bot mitigation or if impossible user travel is detected.

Learn more in the PingOne Protect documentation.

Setup

Resources

Learn more in the following documentation:

Requirements

To use the connector, you’ll need:

  • A PingOne Protect license

  • A PingOne environment with PingOne Protect added. Learn more in Adding an environment.

  • A worker application configured in your PingOne environment. Learn more in Adding an application.

  • A PingOne Protect risk policy. You can use the default risk policy or create a custom risk policy. Learn more in Risk policies.

Setting up the connector

  1. Follow the instructions in Getting started with PingOne Protect.

  2. In DaVinci, add a PingOne Protect connector.

Connector configuration

Environment ID

The Environment ID from the Environment Properties page of the relevant environment in PingOne.

Client ID

The Client ID of the worker application you created in PingOne.

Client Secret

The Client Secret from the Configuration tab of your PingOne worker application.

Using the connector in a flow

Use the PingOne Protect connector to add risk evaluations to different types of flows, such as sign-on with MFA or passwordless sign-on. You can use the PingOne Protect connector in template flows available in the Integration Directory, such as:

Learn more about risk evaluations and how the response result affects the user flow in Reviewing risk evaluations.

The PingOne Protect connector provides these capabilities:

  • Create Risk Evaluation: Add in the flow where you want to base the next action on the risk score or level calculated. For example, show an MFA prompt for medium or high risk but automatically grant access for low risk.

  • Update Risk Evaluation: Add in the flow after authentication has been completed. This capability represents the system’s ability to learn over time to improve results and is essential for risk evaluation precision.

The following diagram shows an example user transaction flow with the two different PingOne Protect connector capabilities:

A diagram of an example DaVinci flow with the Create Risk Evaluation and Update Risk Evaluation connectors.

Create Risk Evaluation

Evaluate risk for a specific transaction based on predictors, such user location anomaly, IP reputation, and bot detection. Learn more in Predictors.

Steps

  1. In your flow, add a PingOne Protect connector and select the Create Risk Evaluation capability.

  2. On the General tab, enter the following information:

    • User Name

    • User ID

    • IP

    • Risk Policy ID (optional): If you’ve created custom risk policies beyond the default risk policy, you can enter the ID of the risk policy you want to use in the flow.

      You can find the ID for a risk policy on the Risk Policies page in your environment in PingOne. If you don’t provide a risk policy ID, the connector uses the default risk policy.

    • Custom Attributes (optional): If you’re using a policy that includes one or more custom predictors that require external data, use the Custom Attributes field to enter the names of the custom attributes and their values.

      For example:

      {"managedDevice" : isManaged, "transactionValue" : transactionValueVar}

      The attribute names must match the attribute names you used in the custom predictors that you created and included in the risk policy. Learn more in Adding custom predictors and Using third-party risk scores with PingOne Protect.

      A screen capture of the Custom Attributes field in the Protect connector.

  3. Click Apply.

  4. To improve risk analysis, include the data for additional risk-related variables provided by the Signals (Protect) SDK.

    Risk evaluation can be performed without the Signals (Protect) SDK payload if there’s no way to provide the payload. However, some predictors require the SDK payload and won’t return a risk level if the payload is missing. Learn more in Predictors.

    • Manual deployment

    • skrisk component

    • PingOne Forms connector

    You can manually deploy the Signals (Protect) SDK when integrating using the DaVinci APIs. For mobile applications or integrating your webpage with DaVinci using APIs instead of redirecting, you’ll:

    • Deploy the Signals (Protect) SDK.

    • Send the SDK payload and the rest of the required data, such as username, user ID, IP address, and any custom attributes to DaVinci using the API.

    • Include a variable in your flow that represents the data obtained.

    To manually deploy the SDK:

    1. Follow the PingOne Protect Native SDKs documentation to implement the SDK in your mobile app or webpage.

    2. Set global variables using the SDK to pass risk-related information from the SDK and map the information into the risk evaluation in DaVinci.

    3. In DaVinci, click the applicable PingOne Protect connector with the Create Risk Evaluation capability in your flow to open its settings.

      1. On the Device Configurations tab, for Risk input from device, enter the name of the variable that represents the data obtained from the SDK in your manual implementation.

      2. In the User Agent field, enter the user agent string for the browser, if available.

        User Agent is included in the SDK payload by default.

      3. To improve risk analysis, use the Cookie field to provide the value of a persistent cookie, if available.

      4. If you want to maintain your own device IDs, you can assign external device IDs that are not managed by the SDK, such as device serial number or mobile application installation ID. External IDs can be sent to DaVinci using the API.

        For example, in a workforce user flow, you can use the Google Chrome Device Trust connector to map the user device serial number when using the Chrome browser.

      5. To pass the risk information from the SDK to DaVinci, map the global variables that you set with the SDK into DaVinci:

        1. On the Log Fields Mapping tab, click + Field.

        2. Select and enter the global variables you set with the SDK.

    You can include the skrisk component in your flow to collect device and user behavioral data from user interactions with custom HTML templates in HTTP connectors, such as an HTTP sign-on or password reset flow. Learn more about skrisk in SK-Components.

    With this approach, the information from the Signals Web SDK is obtained automatically. However, for the Signals Mobile SDK, you must implement the steps in the SDK documentation manually.

    The skrisk component must be added to the following:

    Adding the skrisk component to multiple connectors in a flow allows the SDK to collect additional data throughout the flow and improves bot detection.

    1. Add an HTTP connector with the Custom HTML Template capability to your flow.

    2. On the General tab, in the HTML Template field, click {}, click SK-Component, and then select skrisk in the list.

      The skrisk component should always be at the beginning of the HTML template. Make sure that all HTML tags you add appear below the skrisk component in the HTML Template field.

    3. Double-click the skrisk component that you added to open its properties.

    4. Enter the Environment ID for your PingOne environment.

    5. The Collect behavior data setting collects device and user behavioral data. By default, Collect behavioral data is set to True.

      Set Collect behavior data to False if this connector doesn’t require interaction from the user.

    6. (Optional) Change the default Risk Property Name as needed.

    7. If you want the device data in the SDK payload to be provided as a signed JSON Web Token (JWT), set Enable Universal Device Identification to True.

    8. Click Save.

    9. On the General tab of the HTTP connector, scroll down to the Output Fields List and add a field to represent the output provided by the skrisk component.

      1. For Property Name, enter the same name that you used for Risk Property Name. In the PingOne Protect connector, you’ll select this property name as one of the inputs.

      2. Add a Display Name.

      3. Click Apply.

    10. Click the PingOne Protect connector with the Create Risk Evaluation capability in your flow.

    11. On the Device Configurations tab, configure Risk input from device as follows:

      1. Click {}.

      2. Click to enable the Show all nodes toggle.

      3. Select the HTTP connector in the list.

      4. Under output, select the name that you provided previously for the output of the skrisk component.

        In the following image, <output> represents the output from step 9.

        A screen capture of the Risk input from device configuration.

    You can enable device profiling to collect device information and user data from user interactions with PingOne Forms connectors in your flow. Learn more in Forms.

    Enable device profiling in any user-facing forms as follows:

    • The first PingOne Forms connector in your flow

    • Any subsequent PingOne Forms connectors in the flow, including any in a subflow or parent flow

    To enable device profiling in a PingOne Forms connector:

    1. Add a PingOne Forms connector to your flow.

    2. On the General tab, click the Enable Device Profiling toggle to enable the SDK to collect device information from user interactions with the form.

    3. (Optional) Click the Include Behavioral Data toggle to identify non-human activity through behavioral data collection.

      To enable Include Behavioral Data, you must first turn on Enable Device Profiling.

    4. If you want the device data in the SDK payload to be provided as a signed JWT, set Enable Universal Device Identification to True.

    5. Click Apply.

Update Risk Evaluation

Update an existing risk evaluation to include the flow completion status for the risk evaluation. Updating the completion status allows PingOne Protect to refine and improve the accuracy of future risk evaluations. Always include a PingOne Protect connector with the Update Risk Evaluation capability in your flows to allow PingOne Protect to learn over time. The Update Risk Evaluation event includes one of the following flow completion statuses for the risk evaluation:

  • SUCCESS when the user was granted access or passed the MFA challenge

    Only events with completionStatus=SUCCESS allow the predictors to learn.

  • FAILED when the user was denied access or failed the MFA challenge

    If a user is unable to successfully complete an event, such as if their authentication failed, the risk evaluation for the event is updated as completionStatus=FAILED.

If completionStatus isn’t updated, the status remains completionStatus=IN_PROGRESS, and the predictor can’t learn from the event and stays in training mode.

Steps

  1. Add a PingOne Protect connector with the Update Risk Evaluation capability in your flow at the end of each possible path.

  2. Update the risk evaluation completion status for SUCCESS and FAILED events.

    Learn more in Updating completion status for risk evaluations.

Capabilities

Create Risk Evaluation

Evaluate risk for a specific transaction. Risk results are based on predictors like user behavior anomalies, IP reputation analysis, Geo velocity and other risk models.

Show details
Properties
User ID textField

The ID of the user whose risk is being evaluated.

User Name textField

The username of the user whose risk is being evaluated.

User Type dropDown

Indicates whether the user exists in the PingOne directory or in an external directory.

  • EXTERNAL (Default)

  • PING_ONE

Password textField

The password entered by the user.

Password Hash Algorithm dropDown

Password hashing method.

  • SHA_256 (Default)

  • SHA_384

IP textField

The IP address of the user who initiated the flow.

Application ID textField

The ID for the application or resource the user wants to access.

Application Name textField

The name of the application or resource the user wants to access.

Flow Type textField

The type of flow in which risk is evaluated.

Default:

AUTHENTICATION
Flow Subtype textField

The subtype of the flow.

Session ID textField

The unique session ID associated with the event.

Risk input from device textField
User Agent textField

The user agent of the browser/device that triggered the flow.

Cookie textField

The cookie of the browser/device that triggered the flow.

External ID textField

A unique device identifier generated and managed independently of the Signals SDK (SKrisk).

Risk Policy ID textField

The risk policy set used during risk evaluation.

Custom Attributes textField

Your Custom Atributes defined at Ping.

Input Schema
default object
clientId string required minLength: 0 maxLength: 100

Client ID

clientSecret string required minLength: 0 maxLength: 100

Client Secret

envId string required
userId string minLength: 0 maxLength: 100

User ID

userName string minLength: 0 maxLength: 100

User Name

userType string minLength: 0 maxLength: 100

User Type

password string

Password

passwordAlgorithm string

Password Hash Algorithm

ipAddress string minLength: 0 maxLength: 100

IP Address

completionStatus string minLength: 0 maxLength: 50

Completion Status

targetResourceId string minLength: 0 maxLength: 100

Target Resource ID

targetResourceName string minLength: 0 maxLength: 100

Target Resource Name

flowType string minLength: 0 maxLength: 50

Flow Type

subtype string minLength: 0 maxLength: 50

Flow Subtype

sessionId string
sharingType string minLength: 0 maxLength: 100

Sharing Type

userAgent string minLength: 0 maxLength: 8190

User Agent

riskPolicySetId string
customAttributes string
skRiskFP string
cookie string
externalId string
Output Schema
output object
rawResponse object
properties object
id string
environment object
properties object
id string
createdAt string
updatedAt string
event object
properties object
completionStatus string
targetResource object
properties object
id string
name string
ip string
flow object
properties object
type string
subtype string
session object
properties object
id string
user object
properties object
id string
name string
type string
groups array
items array
type object
properties
required name
sharingType string
browser object
properties object
userAgent string
cookie string
origin string
device object
properties object
externalId string
riskPolicySet object
properties object
id string
name string
result object
properties object
level string
type string
score number
source string
recommendedAction string
details object
properties object
anonymousNetworkDetected boolean
country string
impossibleTravel boolean
ipAddressReputation object
properties object
level string
score integer
type string
domain object
properties object
asn integer
sld string
tld string
organization string
isp string
ipRisk object
properties object
level string
reason string
type string
ipVelocityByUser object
properties object
level string
reason string
type string
threshold object
properties object
high integer
medium integer
source string
calculatedAt string
expiresAt string
velocity object
properties object
distinctCount integer
during integer
userVelocityByIp object
properties object
level string
reason string
type string
threshold object
properties object
high integer
medium integer
source string
calculatedAt string
expiresAt string
velocity object
properties object
distinctCount integer
during integer
estimatedSpeed number
estimatedDistance number
state string
city string
longitude number
latitude number
device object
properties object
browser object
properties object
name string
os object
properties object
name string
id string
externalId string
estimatedDistance number
lastSeen string
externalLastSeen string
previousSuccessfulTransaction object
properties object
anonymousNetworkDetected boolean
country string
state string
city string
ip string
timestamp string
userBasedRiskBehavior object
properties object
level string
reason string
type string
userRiskBehavior object
properties object
level string
reason string
type string
geoVelocity object
properties object
level string
reason string
type string
anonymousNetwork object
properties object
level string
reason string
type string
userLocationAnomaly object
properties object
level string
reason string
type string
status string
botDetection object
properties object
level string
reason string
type string
detected object
properties object
rule object
properties object
id integer
suspiciousDevice object
properties object
level string
reason string
type string
detected object
properties object
rule object
properties object
id integer
newDevice object
properties object
level string
reason string
status string
type string

Update Risk Evaluation

Update an existing risk evaluation to refine future results.

Show details
Properties
Risk Evaluation ID textField

ID of the Risk Evaluation

Risk Evaluation status textField

status of the Risk Evaluation

Input Schema
default object
clientId string required minLength: 0 maxLength: 100

Client ID

clientSecret string required minLength: 0 maxLength: 100

Client Secret

envId string required
completionStatus string minLength: 0 maxLength: 50

Completion Status

riskId string required minLength: 0 maxLength: 100

Risk Evaluation ID

Output Schema
output object
rawResponse object
properties object
completionStatus string
ip string
flow object
properties object
type string
subtype string
session object
properties object
id string
user object
properties object
id string
name string
type string
groups array
items array
type object
properties
required name
sharingType string
origin string

Troubleshooting

To start troubleshooting issues with the PingOne Protect connector, try the following:

  • Test your implementation. Learn more in the PingOne Protect Integration Testing knowledgebase article.

  • For each connector in the flow, make sure you provided all required inputs.

  • For mobile applications, if you’re using the skrisk component to include the data provided by the Signals (Protect) SDK, make sure that you followed the steps in the PingOne Protect Native SDKs documentation.

  • To use the DaVinci Analytics feature to see where the flow stopped, open your flow and click Analytics in the lower-left corner of the flow editor. Learn more in Debugging and analytics.

  • Open your flow, click the More Options (⋮) icon, and click the Show Node ID toggle. This makes it easier to identify the source of inputs and outputs.