PingOne DaVinci

Launching a PingOne flow with a redirect

You can configure PingOne and DaVinci so that you can invoke specifically-configured flows through PingOne.

This approach lets you launch your flows from PingOne and lets you reference and modify user data from PingOne within the flow.

To switch between using a flow for a DaVinci widget integration and an integration using a PingOne redirect, see Switching between PingOne and DaVinci widget integrations.

Configuring a DaVinci flow for invocation

Update a DaVinci flow to enable it to be launched through PingOne.

About this task

This procedure assumes that the flow already exists or is in progress, and only specifies the necessary nodes and settings for invocation through PingOne. For more information about creating flows, see Getting started with DaVinci.

Steps

  1. Sign on to DaVinci and click the Flows tab.

  2. Select the flow tile for the flow that you plan to launch through PingOne.

  3. Click More options ( ) → Flow Settings to show the flow settings.

  4. Select the PingOne Flow option.

  5. Click Save, then close the Flow Settings pane.

  6. End the flow with the following two PingOne Authentication nodes, one for success and one for failure.

    A screen capture of a flow ending with a success and failure path.
    Node Purpose

    Return a Success Response (Redirect Flows)

    This creates a PingOne session for the user and redirects the browser back to the source of the authentication request. This response provides the requested scopes as well as an access token, ID token, or SAML assertion.

    Return an Error Response (Redirect Flows)

    This redirects the browser back to the source of the authentication request. This response provides information about the error that occurred.

  7. Click Save, then click Deploy.

Using PingOne connectors

Add PingOne connectors to your environment to use PingOne capabilities in your flows.

For information about the available PingOne connectors, see Core connectors. If you plan to launch flows through PingOne, you must add the PingOne Authentication connector to your environment.

Referencing PingOne data in the flow

You can reference data from PingOne within your flow.

The format for this information is global.parameters.<parameter name>. Some parameters depend on the protocol used to launch the flow, while others are supplied by the PingOne application.

OIDC parameters

Property Description

authorizationRequest

An object that specifies all the parameters from the OIDC authorization request.

authorizationRequest.<customParameter>

A string that specifies a custom URL parameter added to the OIDC authorization request. Replace <customParameter> with the name of the custom URL parameter.

authorizationRequest.client_id

A string that specifies the client ID of the application associated with this authorize request.

authorizationRequest.redirect_uri

A string that specifies the URL of the return entry point of the application.

authorizationRequest.response_type

A string that specifies the code or token type returned by an authorization request. Options are token, id_token, and code.

authorizationRequest.scope

A string that specifies the permissions that determine the resources that the application can access.

authorizationRequest.state

A string that maintains the state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.

authorizationRequest.nonce

A string that is used to associate a client session with a token to mitigate replay attacks. The value is passed through unmodified from the authentication request to the token. This is an optional property for authorization requests that return a code.

authorizationRequest.acr_values

A string that is used by the flow designer to pass in useful information.

authorizationRequest.login_hint

A string that is used to designate a login identifier to pre-fill the username field of the sign-on screen.

authorizationRequest.max_age

A string that specifies the maximum amount of time allowed (in seconds) since the user last authenticated. If the max_age value is exceeded, the user must re-authenticate. If the max_age value is set to 0 (max_age=0), the user is always required to re-authenticate.

authorizationRequest.prompt

A string that specifies whether the user is prompted to sign on for re-authentication. The prompt parameter can be used as a way to check for existing authentication, verifying that the user is still present for the current session.

authorizationRequest.response_mode

A string that specifies the mechanism for returning authorization response parameters from the authorization endpoint. Options are query, fragment, and form_post.

authorizationRequest.code_challenge

A string that is computed from the code_verifier that is used in a Proof Key for Code Exchange (PKCE) authorization request.

authorizationRequest.code_challenge_method

A string that specifies the computation logic used to generate the code_challenge string. The token endpoint uses this method to verify the code_verifier for PKCE authorization requests. Options are plain and S256.

authorizationRequest.code_verifier

A string that is used to create the code_challenge value passed to the authorization server in the request.

authorizationRequest.mobileRequest

An object that specifies OIDC/OAuth2 request parameters.

For example, the following code references the login hint in a flow launched using OIDC:

global.parameters.authorizationRequest.login_hint

SAML parameters

Property Description

samlRequest

A string that specifies all the parameters from the SAML request.

samlRequest.spEntityId

A string that specifies the service provider entity ID used to look up the application. This is a required property and is unique within the environment.

samlRequest.forceAuthn

A boolean that, when set to true, specifies that the identity provider must authenticate the presenter directly rather than rely on a previous security context. If a value is not provided, the default value is false.

samlRequest.passive

A boolean that, when set to true, specifies that the identity provider and the user agent itself must not visibly take control of the user interface from the requester and interact with the presenter in a noticeable fashion. If a value is not provided, the default value is false.

samlRequest.signed

A boolean that specifies whether the SAML assertion should be signed. The default value is false.

samlRequest.subject

A string that specifies the SAML subject ID.

samlRequest.requestedAuthnContext

A string that specifies the authentication methods for the request.

For example, the following code references the subject ID in a flow launched using SAML:

global.parameters.samlRequest.subject

WS-Federation parameters

Property Description

wsFedRequest.wfresh

The maximum age of authentication in minutes. If the value is 0, the user should be prompted for authentication before a token is issued.

wsFedRequest.wauth

The required authentication level.

wsFedRequest.wctx

An opaque context value that can be passed in the request.

When the invoked DaVinci flow completes successfully and returns to PingOne, PingOne echoes this value back to the service provider with the issued token if it was included by the service provider in the originating request.

wsFedRequest.whr

The account partner realm of the client.

The WS-Federation parameters are currently in limited release. To request access to these parameters, open a support case.

Application parameters

Property Description

application

An object that specifies the configuration information about the PingOne application that initiated the authentication request.

application.homePageUrl

A string that specifies the custom home page URL for the application.

application.id

A string that specifies the application ID.

application.name

A string that specifies the application name.

application.protocol

A string that specifies the protocol for the application. Options are OPENID_CONNECT and SAML.

application.type

A string that specifies the application type. Valid values are WEB_APP, NATIVE_APP, SINGLE_PAGE_APP, SERVICE, CUSTOM_APP, WORKER, PING_ONE_SELF_SERVICE, PING_ONE_ADMIN_CONSOLE, PING_ONE_PORTAL, TEMPLATE_APP, and PORTAL_LINK_APP.

For example, the following code references the application ID in a flow, regardless of the protocol used to launch the flow:

global.parameters.application.id

Universal parameters

Property Description

loginHint

A string that specifies an identifier to pre-fill the username field of a sign-on screen.

maxSecondsSinceLastSignOn

An integer that specifies the maximum amount of time allowed (in seconds) since the user last authenticated. If the user’s last sign on in the session is greater than the integer value specified in this property, then existing session information cannot be used to skip authentication or influence any authentication logic. This value is set automatically to 0 if prompt=login is set for an OIDC application or if ForceAuthn=true is set for a SAML application. Otherwise, this value is set to the max_age property value for OIDC applications, if present, or omitted otherwise.

For example, the following code references the login hint, regardless of the protocol used to launch the flow:

global.parameters.loginHint

Configuring a DaVinci flow policy for invocation

Configure a flow policy to specify which flow and which version of the flow you want to launch.

About this task

Flows in DaVinci flows often have multiple versions as administrators make changes, and not all of these versions should be presented to users. A flow policy ensures that users see the correct version of the correct flow.

Steps

  1. Sign on to DaVinci and click the Applications tab.

  2. Find the application and click Edit.

  3. Click the Flow Policy tab.

  4. Click Add Flow Policy.

  5. In the Name field, enter a name for the flow policy.

  6. Select PingOne Flow Policy.

  7. Add one or more PingOne flows to the policy.

    PingOne flow policies can only include flows and flow versions that have the PingOne Flow setting enabled. Flows and versions without this setting cannot be selected.

    1. In the Flows section, select a flow.

    2. In the Version section, select one or more versions of the flow.

      The Latest Version option always uses the latest version.

    3. Optional: Repeat the previous steps to add additional flows.

  8. Click Create Flow Policy.

    The Edit Your Weight Distribution modal opens.

  9. Add weight distribution and analytics information for each flow and flow version:

    1. In the Distribution field for each flow version, enter or select a distribution weight from 1 to 100.

      The weight is used if the flow policy is invoked without a flow ID. You can use the weight to perform A/B testing.

    2. Optional: Click Add IP Whitelist.

    3. Optional: In the Whitelist IP field, enter one or more IP addresses.

      If a request comes from an allowed IP address, the weight is ignored, and the specified flow is triggered.

    4. Optional: In the Analytics - Select Success Nodes list, select one or more nodes that, when run, indicate that the flow run was successful.

      This information is used to calculate the flow policy’s success rate.

  10. Click Save Flow Policy.

Configuring PingOne for flow invocation

Configure an application in PingOne to launch flows.

About this task

The properties of the PingOne application are used as part of the URL that launches the flow.

Steps

  1. Sign on to PingOne and go to Applications > Applications.

  2. Click the icon.

  3. In the Application Name field, enter a name for the application.

  4. In the Application Type section, select OIDC Web App or SAML Application.

  5. If you selected SAML Application, provide the SAML configuration.

    1. Click Configure.

    2. Select a method for providing the application metadata.

      Choose from:

      • Import Metadata: Import the configuration details from an XML metadata file. Click Select a File and then select an XML metadata file on your system. Click Open.

        If the metadata file does not specify all the configuration values, you must enter the missing values manually.

      • Import From URL: Import the configuration details from a metadata URL. Enter the URL and then click Import.

        The URL must be a valid absolute URL.

      • Manually Enter: Enter the configuration details manually. In the ACS URLs field, enter the Assertion Consumer Service (ACS) URLs. You must specify at least one URL, and the first URL in the list is used as the default. In the Entity ID field, enter the service provider entity ID used to look up the application.

  6. Click Save.

  7. Click the Policies tab.

  8. Click Add Policies.

  9. Click the DaVinci Policies tab.

  10. Select one or more flow policies to add to the application.

    Only flow policies with the PingOne Policy option are displayed.

  11. Click Save.

  12. Click the Configuration tab.

  13. Click the Pencil icon.

  14. In the CORS Settings section, select Allow specific origins.

  15. In the Allowed Origins field, enter the domain from which you plan to launch the flow.

  16. Click Save.

Invoking the flow

To launch the flow, construct a link with the PingOne details and add it to the resource that will launch the flow.

Steps

  1. In the resource that will launch the flow, such as your organization’s web application, add a call to your PingOne application using the following format:

    https://auth.pingone.com/<Environment ID>/as/authorize?response_type=<response type>
     &client_id=<client ID>
     &redirect_uri=<redirect URI>
     &scope=<scope>
     &acr_values=<Flow Policy ID>
     &<other parameter>=<value>

    The following parameters are used in the call:

    Table 1. Parameters
    Parameter Required Description Location

    Environment ID

    Yes

    The Company ID of the DaVinci application.

    Available in DaVinci in the Company tab, or in the details section at the top of any flow or application.

    Response Type

    Yes

    The response type expected by the PingOne application.

    Available in PingOne under Applications → Applications. Click your application, then click the Configuration tab and find the Response Type field.

    Client ID

    Yes

    The PingOne application’s Client ID.

    Available in PingOne under Applications → Applications. Click your application, then click the Configuration tab and find the Client ID field.

    Redirect URI

    Yes

    A redirect URI configured in PingOne.

    Available in PingOne under Applications → Applications. Click your application, then click the Configuration tab and find the Redirect URIs field.

    Scope

    Yes

    The application request scope.

    Available in PingOne under Applications → Applications → Resources. Click your application, then click the Resources tab and find the Allowed Scopes section.

    Flow Policy ID

    No

    A policy that determines which flow and version is run.

    Available in DaVinci in the Applications tab. Select your application, then click the Flow Policy tab.

    Additional parameters

    No

    You can pass in additional parameters to make their values available during the flow.

    N/A

    You can reference the parameter values passed in with the invocation. The format is:

    global.parameters.authorizationRequest.<parameter name>

  2. If the user requires a token but the flow did not grant a token, make an API call to the PingOne token endpoint to grant the user a token. Use the PingOne token authentication code endpoint or the Pingone client credentials endpoint.