Connectors

PingOne Protect Connector

You can use the PingOne Protect connector as part of a PingOne DaVinci flow in order to improve user experience, reduce MFA fatigue, and lower the probability of unintentional push approvals, while still issuing challenges or even denying access altogether in high-risk situations.

For example, you can use a risk evaluation connector before an MFA step, and then define different paths based on the risk score calculated: skip the MFA challenge if low risk, use a specific authentication method if user behavior data suggests medium risk, and block access completely in a high risk situation such as the detection of impossible user travel.

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.

For more information, see the PingOne Protect documentation.

Setup

Setting up the connector

In DaVinci, add a PingOne Protect connection. For help, see Adding a connector.

Connector settings

Environment ID

The Environment ID from the 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.

Region

The region for your PingOne environment.

Using the connector in a flow

You can use the PingOne Protect connector to add risk evaluation to different types of flows, such as sign-on with MFA or passwordless sign-on.

For examples of use of the PingOne Protect connector in different types of flows, see the following templates in the Flow Library:

  • PingOne - Sign On and Adaptive MFA

  • PingID - MFA flow + Risk

  • PingID - FIDO2 Passwordless + Risk

When a risk connector is added, the flow also takes into account the risk score (LOW, MEDIUM, HIGH) calculated by PingOne Protect on the basis of predictors such as user behavior, IP reputation, and user location anomalies.

Points to take into account when using the PingOne Protect connector:

  • In each flow, two different risk connectors should be added:

    • A risk connector with the Create Risk Evaluation capability should be added at a point in the flow where you would like to base the next action on the risk score assigned, for example, show an MFA prompt for MEDIUM or HIGH, but automatically grant access if the risk is deemed LOW.

    • A risk connector with the Update Risk Evaluation capability should be placed in the flow at a point after authentication has been completed. This capability represents the system’s ability to learn over time in order to improve results. You should always include an update connector in your flows because the learning mechanism is essential for risk evaluation precision.

  • For risk evaluation connectors:

    • The IP field on the General tab is a required field.

    • The General tab includes a Risk Policy ID field. If you have defined risk policies beyond the default risk policy, you can enter the ID of the risk policy that you want to use in the flow. The IDs for risk policies can be found on the Risk Policies page for your environment in PingOne. If you do not provide a risk policy ID, the default risk policy is used.

  • If you are using a policy that includes one or more custom predictors that requires external data, use theCustom Attributes field (on the connector’s General tab) to enter the names of the custom attributes and their values, for example, {"managedDevice" : isManaged, "transactionValue" : transactionValueVar}. The attribute names should match the attribute names that you used in the custom predictors that you created and included in the risk policy.

    Custom attributes field in Protect connector

  • In addition to the standard risk factors included in risk evaluations, you can improve risk analysis by including the data for additional risk-related variables that is provided by the Signals (Protect) SDK. There are two ways to include the information from the SDK:

    • You can manually write the code required to obtain the information from the SDK and then include in your flow a variable that represents the data obtained. For details on this approach, see the documentation for PingOne Protect Native SDKs.

    • You can include the skrisk component in your flow. When you use this approach, there is no need to write the code for obtaining the information from the Signals Web SDK. This is handled automatically. Note, however, that this approach can only be used for web applications. For iOS or Android apps, you must manually implement the steps described in the SDK documentation.

To use the information provided by the Signals SDK, follow these steps in Davinci:

  1. If you are including the skrisk component in your flow:

    1. Add an HTTP connector somewhere before the risk evaluation connector in the flow.

    2. Select the Custom HTML Template capability for the HTTP connector.

    3. In the HTML Template field, click {}, click SK-Component, and then select skrisk.

      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.

    4. Double-click the skrisk component that you added to view its properties.

    5. Enter the ID for your PingOne environment.

    6. To collect device and user behavioral data, set Collect behavioral data to True. If this connector doesn’t require interaction from the user, set to False to disable data collection.

    7. Enter a meaningful name for Risk Property Name, such as riskSDKOutput.

    8. Set Enable Universal Device Identification to True if you want the device data in the SDK payload to be provided as a signed JWT.

    9. Click Save.

    10. When you are returned to 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. Fill in the Property Name field with the same name that you used for Risk Property Name and add a Display Name. (In the risk evaluation connector, you will select the property name as one of the inputs.)

  2. Open the settings for the risk evaluation connector, and on the Device Configurations tab, set the following:

    • If you used the skrisk component in your flow, fill in Risk input from device as follows:

      1. Click {}.

      2. Turn on Show all nodes.

      3. Select the HTTP connector.

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

        If you did not use the skrisk component, fill in Risk input from device by entering the name of the variable that represents the data obtained from the SDK via your manual implementation.

    • Use the User Agent field to provide the user agent string for the browser.

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

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

If you are having issues with the PingOne Protect connector, you can try the following:

  • For each connector in the flow, make sure that all of the mandatory inputs have been provided.

  • If you are using the skrisk component to include the data provided by the Signals (Protect) SDK, make sure that you have carried out all of the necessary steps.

  • Use the Analytics feature to see where the flow stopped.

  • Select the Options icon, and turn on Show Node ID. This will make it easier to identify the source of inputs and outputs.