Connectors

PingOne Authentication Connector

The PingOne Authentication connector lets you authenticate users and manage PingOne user authentication sessions in your PingOne DaVinci flow.

You can use the PingOne Authentication connector to:

  • Authenticate users by integrating DaVinci flows into your application using a browser redirect or the DaVinci widget

  • Authenticate users with external identity provider (IdP)s configured in PingOne

  • Create, update, or delete PingOne authentication sessions

  • Check whether a user has an active session

  • Verify a user’s code for device authorization flows

  • Authorize or decline device access to a user’s account

Setup

Resources

For information and setup help, see the following:

Requirements

To use the connector, you’ll need a PingOne license.

Configuring the PingOne Authentication connector

Add the connector in DaVinci as shown in Adding a connector, then configure it as follows.

The PingOne Authentication connector automatically communicates with the PingOne environment associated with your DaVinci environment.

Using the connector in a flow

Authenticating users by redirecting the browser to your DaVinci flow

This is the recommended method for integrating a DaVinci flow into your application. It allows you to authenticate users by redirecting the browser from your application, through PingOne, to your DaVinci flow. This method supports either OpenID Connect (OIDC), Security Assertion Markup Language (SAML), or Microsoft 365 applications.

The ability to use a flow to orchestrate authentication for Microsoft 365 applications is currently in limited release. To request access to these parameters, open a support case.

For detailed setup instructions, see Launching a PingOne flow with a redirect.

To use this method, end your flow with the following two capabilities:

  • Success path: Return a Success Response (Redirect Flows)

    You can optionally configure ID Token Custom Claims to add additional attributes to the OIDC ID Token, SAML assertion, or WS-Federation security token for Microsoft 365.

    For SAML assertions, the default attribute format is urn:oasis:names:tc:SAML:2.0:attrname-format:basic. For WS-Federation security tokens, the default attribute format is http://schemas.xmlsoap.org/ws/2005/05/identity/claims.

    To override the default attribute format, append the pipe character followed by the desired format to the attribute name. For example:

    • If you enter attr1 as the Claim Name value, the resulting attribute format is just the default value.

    • If you enter attr1|http://schemas.microsoft.com/ws/2008/06/identity/claims/5678 as the Claim Name value, the resulting attribute format is http://schemas.microsoft.com/ws/2008/06/identity/claims/5678.

    In addition to fulfilling an OIDC, SAML, or Microsoft 365 authentication request, this capability creates a PingOne user authentication session. If you don’t need session management capabilities, you can ignore the session that is created.

  • Error path: Return an Error Response (Redirect Flows)

Authenticating users by embedding the DaVinci widget in your web application

This is an alternate method for integrating a DaVinci flow into your application when a redirect is not possible. It allows you to authenticate users with your DaVinci flow by embedding a widget within your application. The browser stays on your organization’s domain throughout the transaction. This method only supports OIDC.

For detailed setup instructions, see Launching a flow with the widget.

To use this method, end your flow with the following two capabilities:

  • Success path: Return a Success Response (Widget Flows)

    In addition to fulfilling an OIDC authentication request, this capability creates a PingOne user authentication session. If you don’t need session management capabilities, you can ignore the session that is created.

  • Error path: Send Error JSON Response

    This capability is in the HTTP connector.

Authenticating users with an external identity provider

The connector allows you use an external identity provider that you have configured in PingOne to authenticate users in your flow.

You can use the Link with PingOne User setting to link the resulting user information to PingOne accounts to enable self-service features and centralize user management within your organization.

Attributes from the external provider are also made available in your flow as part of the output schema for the capability.

For more information about external identity providers in PingOne, see Identity Providers and Adding an external identity provider sign-on step.

There are two ways to do this:

Include the skIdP component in a Custom HTML Template

This approach allows you to build a custom HTML page with sign on buttons that are powered by DaVinci authentication connectors and identity providers configured in PingOne.

  1. In a flow, add the HTTP connector with the Custom HTML Template capability.

  2. In the HTML Template field, click {}, select SK-Components, and add the skIdP component.

  3. In the HTML Template field, click the skIdP component to open the configuration.

  4. From the Identity Provider Connector list, select your PingOne Authentication connector.

  5. From the PingOne External Identity Provider list, select an identity provider.

    To manage the identity providers on this list, go to * include::partial$davinci_rc_p1_menu_cascades.adoc[tags=p1.menucascade.integrations.externalidps]* in your PingOne environment.

  6. Complete the rest of the skIdP configuration according to the help text. Click Apply.

Use the Sign On with External Identity Provider capability in a flow

  1. In a flow, add the PingOne Authentication connector with the Sign On with External Identity Provider capability.

  2. In the capability configuration, from the Identity Provider list, select an identity provider.

  3. Complete the rest of the capability configuration according to the help text.

    In the Authentication Context Reference field, select whether to pass the requested authentication context via the AuthnContextClassRef or AuthenContextDeclRef element based on your agreement with the SAML IdP.

  4. Click Apply.

Checking whether a user has an active session

The Check a User’s Session Status capability lets you check whether a user has an active authentication session that matches the authentication method and time period you define.

This lets you create detailed sign on policies. For example, you could skip reauthentication when a user has already signed on with MFA in the past 8 hours.

No special configuration is needed. Add the capability and populate its properties according to the help text.

Check session is not currently supported within subflows.

Creating or updating a session

The Create or Update a Session capability lets you capture information in your flow and use it to create a PingOne user authentication session.

When creating the session, you can include the authentication method or methods that the user used to sign on. This information is associated with the session, and it allows you to create detailed sign on policies that branch based on the authentication method. For details, see Checking whether a user has an active session.

No special configuration is needed. Add the capability and populate its properties according to the help text.

You don’t need to add this capability in flows that end with the Return a Success Response (Redirect Flows) or Return a Success Response (Widget Flows) capability. Those capabilities already create sessions.

Deleting a session

The Delete a Session capability allows you to sign a user out and optionally delete their PingOne user authentication session.

No special configuration is needed. Add the capability and populate its properties according to the help text.

Managing device authorization with a user code

The Verify User Code (Device Auth Flows) capability allows you to grant device access to a user’s PingOne account.

Once the user code is verified in the flow, you can use the following capabilities to authorize or decline device access:

  • Authorize User Code (Device Auth Flows)

  • Decline User Code (Device Auth Flows)

Capabilities

Return Success Response (Redirect Flows)

Create a PingOne session and redirect back to the source of the authentication request. Use this to complete flows that are initiated by a redirect to PingOne.

Show details
Properties
User ID textField required

The user’s PingOne user ID.

Authentication Methods dropdownWithCreate required

The authentication method that the user signed on with. For a dynamic value, select Use Custom Authentication Method and enter a value in the Custom Authentication Method field.

  • Password-based authentication (pwd) (Default)

  • Multiple-factor authentication (mfa)

  • Use Custom Authentication Methods

  • One-time password (otp)

  • Risk-based authentication (rba)

  • Confirmation using SMS (sms)

Custom Authentication Methods textField

The authentication method that the user signed on with, such as "pwd". Use the abbreviations from the Authentication Methods list or enter a custom value. Separate multiple values with a space, such as "pwd geo fpt".

Reduced Scopes textField

The scopes to request for the user, such as "openid email". This field allows you to request a limited subset of the original scopes. You cannot add any scopes that are not part of the original request. Separate multiple scopes with a space. Leave this blank to pass along all of the scopes from the original request.

idTokenClaims selectNameValueListColumn
accessTokenClaims selectNameValueListColumn
Idle Timeout timeInterval

The amount of time that the session will remain valid after the user becomes inactive.

Default:

43200
Input Schema
default object
userId string required
authenticationMethods string required
customAuthenticationMethods string
scopes string
idTokenClaims array
accessTokenClaims array
idleTimeout number

Return Success Response (Widget Flows)

Create a PingOne session and return the OIDC tokens to the originating web application. Use this to complete flows that are initiated within a widget in a web application.

Show details
Properties
PingOne Application dropDown

The PingOne OIDC application to use to create the session in PingOne. For a dynamic value, select Use Application ID and enter a value in the Application ID field.

  • Use Application ID (Default)

Application ID textField required

The unique identifier for the application.

User ID textField required

The user’s PingOne user ID.

Authentication Methods dropdownWithCreate required

The authentication method that the user signed on with. For a dynamic value, select Use Custom Authentication Method and enter a value in the Custom Authentication Method field.

  • Password-based authentication (pwd) (Default)

  • Multiple-factor authentication (mfa)

  • Use Custom Authentication Methods

  • One-time password (otp)

  • Risk-based authentication (rba)

  • Confirmation using SMS (sms)

Custom Authentication Methods textField

The authentication method that the user signed on with, such as "pwd". Use the abbreviations from the Authentication Methods list or enter a custom value. Separate multiple values with a space, such as "pwd geo fpt".

Reduced Scopes textField

The scopes to request for the user, such as "openid email". Leave this blank to request all scopes configured in the PingOne application, or enter a subset of the application scopes. Separate multiple scopes with a space.

idTokenClaims selectNameValueListColumn
accessTokenClaims selectNameValueListColumn
Idle Timeout timeInterval

The amount of time that the session will remain valid after the user becomes inactive.

Default:

43200
Additional Properties selectNameValueListColumn

Define any additional information to include in the response.

Additional Properties Name textField

The name of the property that contains the information defined in Additional Properties, such as "additionalProperties".

Default:

additionalProperties
Input Schema
default object
application string required
applicationId string
userId string required
authenticationMethods string required
customAuthenticationMethods string
widgetScopes string
idTokenClaims array
accessTokenClaims array
idleTimeout number
Output Schema
success boolean
type boolean
access_token string
type string
token_type string
type string
expires_in number
type number
scope string
type string
id_token string
type string
sessionToken string
type string
sessionTokenMaxAge number
type number
additionalProperties object
type object

Return Error Response (Redirect Flows)

Return error information to the source of the authentication request. Use this to complete flows that are initiated by a redirect to PingOne.

Show details
Properties
Custom Error Message toggleSwitch

When enabled, you can provide detailed error information in the fields below.

Error Message dropdownWithCreate

Returned in error field in query parameter

  • invalid_request

  • invalid_client

  • invalid_grant

  • unauthorized_client

  • unsupported_grant_type

  • invalid_scope

errorCode textField
errorDescription textField
errorReason textField

Check Session

Check whether the user has an active session in PingOne.

Show details
Properties
Valid Authentication Method dropdownWithCreate required

The check only passes if the user signed on with the selected authentication method. For a custom value, enter your authentication method reference value in the field, such as "kba" or "mca". This field does not support multiple values.

  • Password-based authentication (pwd) (Default)

  • Multiple-factor authentication (mfa)

  • Any authentication method

  • One-time password (otp)

  • Risk-based authentication (rba)

  • Confirmation using SMS (sms)

Last Sign On Was Within…​ timeInterval

The check only passes if the user signed on within this period of time.

Default:

480
Input Schema
default object
checkSessionAuthenticator string required
authenticationMethodLastUsedIn number
Output Schema
output object
session object
properties object
id string
environment object
properties object
id string
user object
properties object
id string
createdAt string
activeAt string
idleTimeoutInMinutes number
lastSignOn object
properties object
remoteIp string
authenticators array
expiresAt string

Create or Update Session

Create or update an authentication session.

Show details
Properties
User ID textField required

The user’s PingOne user ID.

Authentication Methods dropdownWithCreate required

The authentication method that the user signed on with. For a dynamic value, select Use Custom Authentication Method and enter a value in the Custom Authentication Method field.

  • Password-based authentication (pwd) (Default)

  • Multiple-factor authentication (mfa)

  • Use Custom Authentication Methods

  • One-time password (otp)

  • Risk-based authentication (rba)

  • Confirmation using SMS (sms)

Custom Authentication Methods textField

The authentication method that the user signed on with, such as "pwd". Use the abbreviations from the Authentication Methods list or enter a custom value. Separate multiple values with a space, such as "pwd geo fpt".

Idle Timeout timeInterval

The amount of time that the session will remain valid after the user becomes inactive.

Default:

43200
Input Schema
default object
userId string required
authenticationMethods string required
customAuthenticationMethods string
idleTimeout number
Output Schema
output object
session object
properties object
id string
environment object
properties object
id string
user object
properties object
id string
createdAt string
activeAt string
idleTimeoutInMinutes number
lastSignOn object
properties object
remoteIp string
authenticators array
expiresAt string

Delete Session

Delete an authentication session.

Show details
Properties
Soft Delete toggleSwitch

When enabled, PingOne signs the user out but does not delete the session.

Input Schema
default object
softDelete boolean

Sign On with External Identity Provider

Authenticate the user using an external identity provider configured in PingOne.

Show details
Properties
PingOne External Identity Provider dropDown

Select an external identity provider from your PingOne environment.

  • Use Identity Provider ID (Default)

PingOne External Identity Provider ID textField

The ID of an external identity provider from your PingOne environment, such as “df417355-adc4-2846-41f1-6f4b0b9bd12c”.

Link with PingOne User toggleSwitch

When enabled, DaVinci creates or updates a linked PingOne user account using attributes from the external IdP.

PingOne Population dropDown

The PingOne population to use when authenticating the user.

  • Use Population ID (Default)

Population ID textField

The ID of the PingOne population to use when authenticating the user, such as “aa4b3e81-cf7e-8685-4b7b-7ec89cfcf7c8”.

ACR Values textField

Enter the space-separated list of values to pass context to the IdP via OIDC.

Login Hint textField

Username to prepopulate at the external IdP.

Application Return to Url textField

When using the embedded flow player widget and an IdP/Social Login connector, provide a callback URL to return back to the application.

Requested Authentication Context textField

Enter the space-separated list of values to pass context to the IdP via SAML 2.0.

Authentication Context Reference radioSelect

Select the reference element to pass the context based on your agreement with the SAML IdP. The Requested Authentication Context field must be populated beforehand.

  • AuthnContextClassRef

  • AuthnContextDeclRef

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

Identity Provider

identityProviderId string minLength: 0 maxLength: 100

Identity Provider ID

population string minLength: 0 maxLength: 100

Population

populationId string minLength: 0 maxLength: 100

Population ID

linkWithP1User boolean

Link with PingOne User

acrValues string minLength: 0 maxLength: 300

ACR Values

loginHint string minLength: 0 maxLength: 100

Login Hint

returnUrl string minLength: 0 maxLength: 300

Return URL

requestedAuthenticationContext string minLength: 0

Requested Authentication Context

authenticationContextReference
Output Schema
output object
isLinkedUser boolean
user object
properties object
preferredLanguage string
timezone string
lastSignOn object
properties object
at string
remoteIp string
title string
type string
locale string
enabled boolean
identityProvider object
properties object
id string
type string
lifecycle object
properties object
status string
createdAt string
verifyStatus string
nickname string
mfaEnabled boolean
id string
email string
updatedAt string
memberOfGroupIDs string
address object
properties object
streetAddress string
locality string
region string
postalCode string
countryCode string
externalId string
photo object
properties object
href string
memberOfGroupNames string
population object
properties object
id string
primaryPhone string
accountId string
mobilePhone string
name object
properties object
formatted string
given string
middle string
family string
honorificPrefix string
honorificSuffix string
account object
properties object
canAuthenticate boolean
status string
lockedAt string
secondsUntilUnlock string
unlockAt string
username string
rawIdpAttributes object
statusCode integer

Verify User Code (Device Auth Flows)

Verify that a given user code exists.

Show details
Properties
User ID textField required

The user’s PingOne user ID.

User Code textField required

The user code provided by the end user

Input Schema
default object
userId string required
userCode string required
Output Schema
output object
scope string
appId string
remoteIp string

Authorize User Code (Device Auth Flows)

Grant a device access to a user’s account. Should be done only after the user code has been verified and the scopes have been accepted by the user.

Show details
Properties
User Code textField required

The user code provided by the end user

User ID textField required

The user’s PingOne user ID.

Authentication Methods dropdownWithCreate required

The authentication method that the user signed on with. For a dynamic value, select Use Custom Authentication Method and enter a value in the Custom Authentication Method field.

  • Password-based authentication (pwd) (Default)

  • Multiple-factor authentication (mfa)

  • Use Custom Authentication Methods

  • One-time password (otp)

  • Risk-based authentication (rba)

  • Confirmation using SMS (sms)

Custom Authentication Methods textField

The authentication method that the user signed on with, such as "pwd". Use the abbreviations from the Authentication Methods list or enter a custom value. Separate multiple values with a space, such as "pwd geo fpt".

Reduced Scopes textField

The scopes to request for the user, such as "openid email". This field allows you to request a limited subset of the original scopes. You cannot add any scopes that are not part of the original request. Separate multiple scopes with a space. Leave this blank to pass along all of the scopes from the original request.

idTokenClaims selectNameValueListColumn
accessTokenClaims selectNameValueListColumn
Idle Timeout timeInterval

The amount of time that the session will remain valid after the user becomes inactive.

Default:

43200
Input Schema
default object
userCode string required
userId string required
authenticationMethods string required
customAuthenticationMethods string
scopes string
idTokenClaims array
accessTokenClaims array
idleTimeout number

Decline User Code (Device Auth Flows)

Deny a device access to a user’s account. This should be done after the user code has been verified if the user does not consent to the requested scopes.

Show details
Properties
User Code textField required

The user code provided by the end user

Input Schema
default object
userCode string required