Connectors

PingID Connector

PingID is a cloud-based multi-factor authentication (MFA) service that protects an organization’s network, applications, and data resources while providing secure and seamless experiences for your customers and users.

The PingID connector supports the use of:

  • Customer-friendly authentication flows to increase security without adding unnecessary friction to the end user experience.

  • User enrollment flows:

    • Automatically: Allow customers to automatically enroll an authentication method for users during the authentication process.

    • One-time device authentication: Include device details within an authentication request. Enables a user to authenticate for one session only, without pairing the device.

Setup

Resources

Requirements

To use the connector, you’ll need:

Setting up PingID

For instructions on how to setup PingID, see the PingID documentation

Setting up the connector

In DaVinci, add a PingID connector. For help, see Adding a connector.

Connector settings

Environment ID

Your PingOne Environment ID. In PingOne, go to Settings → Environment Properties.

Client ID

The Client ID for your PingOne Worker application. In PingOne, go to your application Applications → Applications → Configuration.

Client Secret

The Client Secret for your PingOne Worker application. In PingOne, go to your application Applications → Applications → Configuration.

Region

Your PingOne environment region. In PingOne, go to Settings → Environment Properties.

Using the connector in a flow

Enrolling a device

To seamlessly add MFA for your users and increase MFA adoption, use the PingID connector. You can include device enrollment as part of user registration, or as a just-in-time (JIT) registration within an authentication flow.

The user can select an authentication method for MFA from a list of methods defined by the PingID configuration. This list can include traditional methods, such as email and SMS, and more secure and frictionless methods, such as FIDO2 biometrics and PingID mobile app.For help, see the Creating an authentication flow guide.

Authenticating users

Use the PingID connector to increase security by adding an authentication factor that requires the user to prove their identity using a trusted device.

For help, see the Creating an authentication flow guide.

PingID flow templates

Ping Identity provides out-of-the-box DaVinci subflows that you can add to a main flow to register authentication devices and to use those devices to authenticate with PingID.

The following PingID flows are available:

  • PingID registration sub-flow

    Use this subflow to register a new authentication method for use with PingID.

    The variable pingIdUserId represents the ID attribute from PingOne and must be provided when triggering the flow.

  • PingID authentication sub-flow

    Use this subflow to add PingID as a secondary authentication factor to a main flow, as part of an authentication process.

    • Customize PingID authentication sub-flow variables.

    Click the Variables node to customize any of the following options:

    • AdminMessage: The administrative message you want to display during authentication.

    • SMSBackup: Use the user’s mobile number as a backup authentication method, so they can receive a one-time passcode by SMS, if the user forgets their registered authentication device.

    • phoneBackup: Use the user’s mobile number as a backup authentication method, to receive a one-time passcode by voice message, if the user forgets their registered authentication device.

    • emailBackup: Use the user’s email address as a backup authentication method, to receive a one-time passcode by email, if the user forgets their registered authentication device.

    • useCode: When set to true, the user can click a Use Code button to enter an OTP, rather than waiting for a push notification to arrive.

    • OTP Fallback: When set to true, user’s can authenticate with a one-time passcode in the event that the PingID server cannot reach their device, or the push response cannot be completed.

      • Define a list of mandatory authentication devices

        You can define a list of mandatory authentication methods. If defined, users are forced to register all of the required authentication methods in order to access their resources.

        1. In the relevant PingID authentication subflow, click the Flow Settings node.

        2. In the Variable Name field, select mandatoryAuthenticationMethods, and then enter the authentication methods that the user must register with their account. Valid authentication methods include:

          • PINGID_DESKTOP

          • PINGID_MOBILE

          • SMS

          • VOICE

          • EMAIL

          • TOTP

          • SECURITY_KEY

          • PLATFORM

          • YUBIKEY

          • OATH_TOKEN

          This field is empty by default. Authentication methods must be entered in upper case, with a space between each entry. If no authentication method is defined, the user is not required to pair a specfic device.

          Example:

          SMS VOICE EMAIL

          The next time the user attempts to authenticate, even if they have one of the mandatory methods paired with their account, they are forced to register all of the authentication methods specified in the mandatoryAuthenticationMethods list, before they can access their resources.

          Mandatory Devices information window, listing all of the devices that the user must pair in order to access their resources. Devices that are already paired with their account display a green checkmark and the word Paired next to the entry

          • This flow requires the PingID - registration welcome page flow. The variable pingIDUserId must be provided when triggering the flow.

          • The following PingID Connector variables override the equivalent values in the PingID admin console Configuration tab:

          PingID PingIDconnector variable PingID PingIDadmin console location

          SMSBackup, phoneBackup, emailBackup

          Alternate Authentication Methods, Backup Authentication (SMS, Voice, or Email checkbox).

          OTP Fallback

          Mobile App Authentication, One-time Passcode Fallback

          useCode

          Mobile App Authentication, Direct Passcode Usage

          It is recommended that you review the PingID connector limitations section.

          Search for the relevant flow in the DaVinci flow library.

PingID connector limitations

This section describes the known limitations relating to the PingID Connector, and evaluation of PingID policy.

PingID Connector limitations

  • The PingID Devices page is not available when using the PingID Authentication sub-flow. The Settings button is therefore not displayed on the Authentication screen.

  • The PingID connector only support the English language. Localization is not currently supported.

  • Backup authentication: If a backup authentication configuration is defined in the PingID authentication sub-flow, it overrides any backup configuration defined in a PingID policy.

  • Authentication success message: When authenticating successfully, the Authentication Successful screen appears by default, even if the Show Approved Authentication check box is not selected in PingID policy. This behavior can only be modified by editing the flow.

  • PingID policy rule evaluation: The Evaluate Policy capability does not enforce the following policy rules:

    • Limit push notifications rule

    • Mobile OS version rule

    • Recent authentication from office rule

    • Authentication from company network rule: authenticating device in company offices section

    • Recent authentication from company network rule: authenticating device in company offices section

  • IPv6 address support: If you only have an IPv6 address configured on your local machine, PingID policy is not evaluated.

  • PingID policy log entries: Log entries do not support multiple users authenticating from the same browser. Log entries for transaction details such as IP address, transaction time, and geolocation are overwritten by the last user that authenticates.

  • If you want to disable the OTP fallback or Direct passcode Usage (Use Code button) features, you must disable the relevant feature in the flow settings node in DaVinci, and the Admin portal.

PingID Legacy Connector

You can use the PingID connector to add MFA (multi-factor authentication) to flows, including passwordless login flows.

PingID is a cloud-based authentication service that allows your users to carry out MFA (multi-factor authentication) using a variety of methods, including the PingID mobile app, security keys, and biometrics.

Setup

Resources

Setting up the connector

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

After creating the connector, configure it by going to its General tab and pasting in the content of the PingID properties file that you downloaded.

PingID connector configuration

Using the connector in a flow

MFA flows

For examples of using the PingID connector in basic MFA flows, see the following templates in the Flow Library:

  • PingID - Basic MFA flow (username/password + MFA)

  • PingID - MFA flow + Risk (username/password + risk evaluation, MFA according to risk score generated for user)

In flows of this type, a connector using the Initialize MFA capability should be placed in the flow at the point where you want an MFA challenge to be issued, for example, after the user has entered their password.

MFA in passwordless flows

For examples of using the PingID connector to combine MFA with passwordless login, see the following templates in the Flow Library:

  • PingID - FIDO2 Passwordless (FIDO2 username, no password required)

  • PingID - FIDO2 Passwordless + Risk (FIDO2 username, no password + risk evaluation, action based on risk score generated for user)

In passwordless login flows, two PingID connectors should be added to the flow:

  • A connector using the Initialize Passwordless Authentication capability

  • Later in the flow, a second connector using the Finalize Passwordless Authentication capability and using as input the passwordlessContext that was returned by the initialize step. The username must also be provided as input.

Capabilities

Initialize MFA (initializeMfa)

Multi-Factor Authentication and on-the-fly registration.

Show details
Properties
Username textField

The username for the user in PingOne.

First Name textField

User’s first name.

Last Name textField

User’s last name.

User Groups textField

The groups to which the user belongs. Used for applying PingID policies that have been defined.

Mobile Number textField

User’s mobile phone number.

Landline Number textField

User’s landline number.

Application Name textField

The name of the application the user is trying to access.

Application ID textField

The ID of the application the user is trying to access. Used for applying PingID policies that have been defined.

Application Icon (URL) textField

The URL of the icon that is used for the application the user is trying to access.

IP of accessing device textField

The IP of the device trying to access the application. Used for applying PingID policies that have been defined.

Attributes selectNameValueListColumn

Use this section to add attribute to the request

Initialize Passwordless Authentication (initializePasswordlessAuthentication)

Passwordless authentication using FIDO2 supported devices.

Show details
Properties
Attributes selectNameValueListColumn

Use this section to add attribute to the request

Finalize Passwordless Authentication (finalizePasswordlessAuthentication)

Policy evaluation to complete the Passwordless Authentication.

Show details
Properties
Username textField

The username for the user in PingOne.

Passwordless Context textField

Information returned by the initializePasswordlessAuthentication capability of the connector. Required to continue the passwordless session.

First Name textField

User’s first name.

Last Name textField

User’s last name.

User Groups textField

The groups to which the user belongs. Used for applying PingID policies that have been defined.

Mobile Number textField

User’s mobile phone number.

Landline Number textField

User’s landline number.

Application Name textField

The name of the application the user is trying to access.

Application ID textField

The ID of the application the user is trying to access. Used for applying PingID policies that have been defined.

Application Icon (URL) textField

The URL of the icon that is used for the application the user is trying to access.

IP of accessing device textField

The IP of the device trying to access the application. Used for applying PingID policies that have been defined.

Attributes selectNameValueListColumn

Use this section to add attribute to the request

Troubleshooting

If you are having trouble with the PingID connector, you can try the following:

  • Verify that when you created and configured the connector on the Connections page, you pasted correctly the contents of your PingID properties file.

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

  • 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.