PingOne DaVinci

Launching a flow with a Ping SDK

Launch a prepared flow through an application built with one of the Ping SDKs.

The Ping SDKs provide powerful orchestration capabilities with PingOne DaVinci. They let you create flows to meet your use cases, while providing a native iOS, Android, or single-page app JavaScript experience.

This method is effective when you want complete control of your end user’s experience while using a flow behind the scenes.

Configuring the Flow

Prepare a flow to be launched with the Ping SDK for Android, iOS, or JavaScript.

About this task

This procedure only covers the steps and nodes required to prepare a flow for SDK invocation. It assumes that you’ve already created a flow for the purpose you have in mind. You can find more information about building flows in the Getting started with DaVinci and DaVinci Best Practices documentation.

Steps

  1. On the Flows tab, find the flow and click ... → Edit.

  2. Verify that your user interface nodes use only compatible connectors, capabilities, and elements.

    Compatible connectors and capabilities are:

    • The HTTP Connector and its Custom HTML Template capability

    • The PingOne Forms Connector and its Show Form capability

    Compatible elements within the Custom HTML Template and PingOne Forms capabilities are:

    PingOne Forms element name Custom HTML element name Description

    Text Input

    Text field

    Lets the user enter text

    Password

    Text Input with the Secure setting

    Lets the user enter a password that cannot be read from the screen. The PingOne Forms Verify Password feature is supported.

    Submit Button

    Submit Button

    Lets the user submit field data and proceed

    Flow Button

    Flow Button

    Lets the user trigger a new process without submitting field data

    Translatable Rich Text

    Label

    Displays text for the user

    Dropdown

    Dropdown

    Lets the user make a selection from a dropdown list

    Radio Button List

    Radio Button List

    Lets the user make a selection from a radio button list

    Checkbox List

    N/A

    Lets the user select any number of options from a checkbox list

    Combobox

    N/A

    Lets the user select an existing option from a dropdown list or enter text

    Social Login

    skIDP component

    Lets users sign on using a third-party identity provider (IdP)

  3. Verify that your flow does not depend on any unsupported elements:

    • SKPolling components: SKPolling components cannot be processed by the SDK and should not be included.

    • Variable field names: You cannot use variables or other values from a node’s input schema in the names of any field used by the SDK.

    • Images: Images included in the flow cannot be passed to the SDK.

    • Additional text: Titles or other text cannot be passed to the SDK.

  4. If you’re using HTTP Connector nodes, ensure that any buttons that submit page data use the following parameters:

    • type=submit

    • The data-skbuttonvalue must be Continue, Submit, Proceed, or Next.

      For example:

      <button data-id="button"
    type="submit"
    class="btn btn-primary mb-3"
    data-skcomponent="skbutton"
    data-skbuttontype="form-submit"
    data-skform="usernamePasswordForm"
    id="btnSignIn"
    data-skbuttonvalue="Submit">
Sign On
</button>

  5. If you’re using HTTP Connector nodes, ensure that any buttons that navigate to a different screen without submitting data use the following parameters:

    • The data-skbuttonvalue must not be Continue, Submit, Proceed, or Next.

      For example:

      <button data-id="button"
    class="btn btn-link"
    data-skcomponent="skbutton"
    data-skbuttontype="form-submit"
    data-skform="usernamePasswordForm"
    id="btnTrouble"
    data-skbuttonvalue="TROUBLE">
Having trouble signing on?
</button>

  6. If you’re using HTTP Connector nodes, add each text field, password field, and button to the node’s output fields.

    These outputs are all used by the SDK, regardless of any conditional logic used to control their display in the HTML.

    1. Click the node.

    2. On the General tab, find the Output Fields List section, and click Add.

    3. In the Property Name field, enter a name for the property to be passed to the SDK.

    4. In the Display Name field, enter a name for the property to be used in the user interface.

    5. In the Control Type list, select Text Field.

    6. In the Data Type list, select String.

    7. If the value is a password, select Secure.

    8. In the Value field, select the {} option and map the field’s value to the property.

    9. Repeat steps b-h for each additional output.

    10. Click Apply.

    11. Repeat these steps for each additional node with outputs.

  7. If you’re using social login, ensure that your flow uses a supported method.

    Social login lets users sign on using a third-party IdP such as an Apple, Google, or Facebook. You must configure the external IdPs according to the PingOne documentation before including them in a flow.

    Social Login using the Sign On with External Identity Provider capability of the PingOne Authentication connector is not supported in SDK flows.

    • In a PingOne Form, you can use the Social Login tool to enable social login. Configure this button using the PingOne documentation.

      A screenshot of the configuration for the Social Login tool on a PingOne Form.

    • In a Custom HTML Template, you can use the skIDP sk-component to enable social login:

      1. In the HTML Template section of the General tab, click the {} icon.

      2. In the Choose Connection list, select SK-Component, then select skIDP.

      3. Click the skIDP component in the HTML Template field.

        A screenshot of the skIDP component included in a Custom HTML Template node.

      4. In the Identity Provider Connector list, select PingOne Authentication.

      5. In the PingOne External Identity Provider list, select a configured social login provider.

      6. If you want to correlate the third-party login user with a PingOne user, select Link with PingOne User, then select a user population in the PingOne Population list.

      7. In the Button ID field, enter an ID.

        A screenshot of the skIDP component configuration, as described in the current step.

      8. Click Save.

  8. To use the user’s PingOne User ID in your flow, include the p1UserId global parameter in your flow.

    The user’s PingOne User ID is only available after the user has been identified. The user can be identified directly through PingOne or using a third-party authentication that is correlated with the user’s PingOne account.

    1. Open the node in which you want to include the invocation information.

    2. Click the Variables ( {} ) icon.

    3. Click Global.

    4. Select the p1UserId property.

  9. To use data about the invocation method or the invocation platform type in your flow, include the isSdk and platformType global parameters in your flow.

    Property Type Description

    isSdk

    Boolean

    Indicates whether the flow was launched using the SDK.

    platformType

    String

    Indicates what platform was used to launch the flow if it was launched using the SDK. Valid values are js, android, and ios.

    1. Open the node in which you want to include the invocation information.

    2. Click the Variables ( {} ) icon.

    3. Click Global > Current Request.

    4. Select the isSdk or platformType property.

      For example:

      A screen capture of the selection process described in steps a-d.

  10. Click More options ( ) > Flow Settings to show the flow settings.

  11. Select the PingOne Flow option.

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

  13. 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 or ID token.

    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.

  14. Click Save, then click Deploy.

  15. If the main flow uses subflows, ensure that the subflows are not configured as PingOne flows.

    1. On the Flows tab, find the flow and click …​ > Edit.

    2. Click More options ( ) > Flow Settings to show the flow settings.

    3. Select the PingOne Flow option.

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

    5. Repeat these steps for each additional subflow.

Creating a DaVinci application

Create an application in DaVinci to enable your flow.

Steps

  1. Sign on to DaVinci.

  2. On the Applications tab, click Add Application.

    Result:

    The Add Application modal opens.

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

  4. Click Create.

  5. Find the application and click Edit.

  6. On the OIDC tab, note the application parameters for the following:

    • Company ID

    • Client ID

    • Client Secret

    • Issuer

    • Token Endpoint

    • JWKS Endpoint

  7. Create a flow policy:

    1. On the Flow Policy tab, click Add Flow Policy..

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

    3. Select PingOne Flow Policy.

    4. In the flow list, select your flow.

    5. In the version list, select Latest Version.

    6. Click Create Flow Policy.

      Result:

      The Edit Your Weight Distribution modal opens.

      This example only uses one flow, but if your flow policy included multiple flows or flow versions, you could use this modal to split traffic between them.

    7. Click Save Flow Policy.

    8. Note the Policy ID of your flow policy.

Configuring PingOne for flow invocation

Configure an application in PingOne to launch flows.

About this task

The PingOne application is used as part of the flow invocation process.

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 an application type corresponding to your platform:

    • If you’re using the Ping SDK for JavaScript, select OIDC Web App.

    • If you’re using the Ping SDK for iOS or Android, select Native.

    A screen capture of the OIDC Web App Application Type options. The OIDC Web App and Native Application Types options are indicated with a red border.

  5. Click Save.

  6. On the Policies tab, click Add Policies.

  7. On the DaVinci Policies tab, select one or more flow policies to add to the application.

    Only flow policies with the PingOne Policy option are displayed.

  8. Click Save.

  9. If you’re using the Ping SDK for JavaScript, configure CORS settings for your application.

    1. On the Configuration tab, click the Pencil icon.

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

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

    4. Click Save.

  10. Create a revoke resource as described in the SDK documentation.

  11. Register OAuth 2.0 applications as described in the SDK documentation.

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. You must download the Ping SDKs and create a user experience that launches the flow.

To create the link, you need the following values:

  • Client ID

  • Redirect URI

  • Scopes

  • OIDC Discovery Endpoint

Learn more about creating the link and launching the flow in the SDK documentation.