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
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) or Security Assertion Markup Language (SAML).
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)
In addition to fulfilling an OIDC or SAML 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.
-
In a flow, add the HTTP connector with the Custom HTML Template capability.
-
In the HTML Template field, click {}, select SK-Components, and add the skIdP component.
-
In the HTML Template field, click the skIdP component to open the configuration.
-
From the Identity Provider Connector list, select your PingOne Authentication connector.
-
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.
-
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
-
In a flow, add the PingOne Authentication connector with the Sign On with External Identity Provider capability.
-
In the capability configuration, from the Identity Provider list, select an identity provider.
-
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
orAuthenContextDeclRef
element based on your agreement with the SAML IdP. -
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
- access_token
- type
string
-
- token_type
string
- token_type
- type
string
-
- expires_in
number
- expires_in
- type
number
-
- scope
string
- scope
- type
string
-
- id_token
string
- id_token
- type
string
-
- sessionToken
string
- sessionToken
- type
string
-
- sessionTokenMaxAge
number
- sessionTokenMaxAge
- type
number
-
- additionalProperties
object
- additionalProperties
- 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
- id
- user
object
- properties
object
-
- id
string
- id
- createdAt
string
- activeAt
string
- idleTimeoutInMinutes
number
- lastSignOn
object
- properties
object
-
- remoteIp
string
- authenticators
array
- remoteIp
- 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
- id
- user
object
- properties
object
-
- id
string
- id
- createdAt
string
- activeAt
string
- idleTimeoutInMinutes
number
- lastSignOn
object
- properties
object
-
- remoteIp
string
- authenticators
array
- remoteIp
- 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
- at
- title
string
- type
string
- locale
string
- enabled
boolean
- identityProvider
object
- properties
object
-
- id
string
- type
string
- id
- lifecycle
object
- properties
object
-
- status
string
- status
- 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
- streetAddress
- externalId
string
- photo
object
- properties
object
-
- href
string
- href
- memberOfGroupNames
string
- population
object
- properties
object
-
- id
string
- id
- primaryPhone
string
- accountId
string
- mobilePhone
string
- name
object
- properties
object
-
- formatted
string
- given
string
- middle
string
- family
string
- honorificPrefix
string
- honorificSuffix
string
- formatted
- account
object
- properties
object
-
- canAuthenticate
boolean
- status
string
- lockedAt
string
- secondsUntilUnlock
string
- unlockAt
string
- canAuthenticate
- 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