PingOne Application Integrations Guide

Our Application Integrations Guide shows you how to call into PingOne products and services, and retrieve data for processing of transactions by your application. This is a new guide, and the PingOne DaVinci product is our first integration. We'll be adding more integrations soon.

DaVinci Application Integrations

PingOne DaVinci is an orchestration platform that helps you design and create flows that guide users through authorization and authentication tasks, such as sign-on, and registration. After you create a flow, you can associate the flow with an application to make the flow available to the application's users.

For information about designing and creating flows in the DaVinci UI console, see How to create a flow.

To integrate flows into your applications, see Integration Methods.

DaVinci API domain

Currently, DaVinci supports the following domain in the North America region: api.singularkey.com. This is the domain for calling the DaVinci API resource server in a production environment.

In this documentation, endpoint URLs use the variable {{authPath}} to represent the domain, which can be for requests to the production resource server https://api.singularkey.com/v1, or for requests to a custom domain (if you have worked with Ping Identity to set up a custom domain).

Getting Started with DaVinci

Integrating an application with PingOne DaVinci enables you to inject information into DaVinci flows based on user responses, and transactions processed by your application.

To begin integrating your application with a DaVinci flow, you'll need to:

  1. Use the DaVinci Flow Studio UI to design, create, and deploy the flow. See Getting Started.

  2. Create an application connection using the DaVinci UI console. See Creating an application.

  3. Connect the flow to your application using one of our integration methods for DaVinci: Widget, Redirect, or API.

    The DaVinci API path or host is "api.singularkey.com".

Using data model properties

Application integrations use specific data model properties associated with the DaVinci applications and flows that you define. When you create applications and flows in the DaVinci UI console, these resource IDs are often used in your application integration code:

Property Description
ApiKey A string that specifies the application's API key, which is used as a credential for making API calls. This property is visible in the General tab of the Applications view.
client_id A string that specifies the application's ID. This property is visible in the General tab of the Applications view.
companyId A string that specifies your orgnaization's ID. This ID is associated with all the applications and flows you create in DaVinci and is visible in the Company view as well as under the application name in the Applications view.
flowId A string that specifies the flow ID. This property is visible under the flow name in the Flow Studio view.
redirect_uri A URL that specifies the return entry point of the application. This is an OpenID Connect property defined in the OIDC tab of the Applications view.
scope A string that specifies the permissions that determine the resources that the application can access. This is an OpenID Connect property defined in the OIDC tab of the Applications view.

Integration Methods

DaVinci supports the following methods to integrate flows into applications:

  • Widget method

    This method interacts with users by integrating a flow using a modal on the page, as opposed to being redirected to a new location to begin the flow as for the Redirect method. Using a modal on the page, simplifies the UI customization needed to make the flow match your application's branding.

    For more information, see Widget method.

  • Redirect method

    This method launches the flow in another page, redirecting the user to the page.

    For more information, see Redirect method.

  • API method

    This method is intended for initiating or processing transactions for PingOne DaVinci flows, as well as calling the APIs for Ping Identity products and services. The API calls can be coded in the programming language of your choice, and added to your application's source.

    For more information, see API method.

Widget method

Use the PingOne DaVinci Widget to run the flow within a modal on your application page. This reduces any UI customization needed to make the flow match your branding. This integration method is well-suited to flows that involve UI nodes.

Prerequisites

  • A PingOne trial or subscription license.
  • A DaVinci application that's associated with a flow policy.
  • Your DaVinci Company ID, API Key, and Policy ID.

Workflow

  1. Create a worker application in PingOne to provide the credentials needed for adding a PingOne connection in DaVinci. See "Creating PingOne credentials" in Connecting DaVinci with PingOne.

  2. Add a PingOne connection in DaVinci. See "Adding PingOne connections" in Connecting DaVinci with PingOne.

  3. Create a DaVinci flow, see Getting Started. Then, create a DaVinci flow policy and add the flow to the flow policy. See Configuring a flow policy. You'll also need to create a DaVinci application, and associate it with the flow. See Creating an application.

  4. In the DaVinci UI console, click Applications, and open the application for the flow policy you want to integrate with your app. See Configuring a flow policy.

  5. You'll need the Company ID and API Key values from the General tab of your DaVinci application.

  6. You'll also need the Policy ID for the flow associated with your DaVinci application.

  7. In the application you're building to integrate with DaVinci, specify the Company ID, API Key, and Policy ID. See the example below for how you might do this.

Example

This is a simple hello-world application. The elements of interest are how to specify the DaVinci API domain, your company ID, flow policy ID, and DaVinci access token, which then integrates your single-page app with the DaVinci application and associated flow policy.

<!DOCTYPE html>
<html lang="en">
  <meta charset="UTF-8" />

  <head>
    <title>Simple HTML/JS widget sample</title>
  </head>

  <body>
    <h3>Simple HTML/JS widget sample</h3>
    <br />
    <p>Widget will be displayed below:</p>
    <br />
    <div id="widget" class="skWidget">Widget should appear here</div>

    <script
      type="text/javascript"
      src="https://sdk.singularkey.com/latest/singularkey.js"
    ></script>
    <script>
      //*** TO DO ***/
      //*** Populate the parameters below from your DaVinci environment ***/
      const companyId = "SvUuK0sZai4uFdLt2kNolPO3Cky5wZGg";
      const skApiKey =
        "YBgdBLjDLFgH2PkOZqPaP5TW6xGfSY0s7GIcJDKQfCJL866i9SQvIDpzcC9vY5lbtstGmbW38MYIooRTPdK9lWOaAmT6wW6vTQO6Ser4fiI3v2RhEFuNvH1hIoaUZh68c6UxeVW000acFQz3ui5bB7axX6wTZkHMAJI0GQ5o6XDqYpgxmPwT2L9WDLAoyhsK8xEKhiIKhva8E6WJkLa6ihmcGeMIlodBY4Ag0sD6P9Y07ZAsem9vtIFA1F7rs55H";
      const policyId = "B7UbORQbqX2QvVVGomShUXFp45NnAm0l";

      //*** Build the get SK Token URL. ***/
      const skGetTokenUrl =
        "https://sdk.singularkey.com/v1/company/" +
        companyId +
        "/sdkToken";

      //*** Add the API Key from your DaVinci application. ***/
      var headers = new Headers();
      headers.append("X-SK-API-KEY", skApiKey);

      var requestOptions = {
        method: "GET",
        headers: headers,
        redirect: "follow",
      };

      //*** Retrieve SK Token ***/
      fetch(skGetTokenUrl, requestOptions)
        .then((response) => response.json())
        .then((responseData) => {
          var props = {
            config: {
              method: "runFlow",
              apiRoot: "https://sdk.singularkey.com/v1",
              accessToken: responseData.access_token,
              companyId: companyId,
              policyId: policyId,
            },
            useModal: false,
            successCallback,
            errorCallback,
            onCloseModal,
          };
          /*** Invoke the Widget ****/
          console.log(props);
          singularkey.skRenderScreen(
            document.getElementsByClassName("skWidget")[0],
            props
          );
        })
        .catch((error) => console.log("error", error));

      function successCallback(response) {
        console.log(response);
      }

      function errorCallback(error) {
        console.log(error);
      }

      function onCloseModal() {
        console.log("onCloseModal");
      }
    </script>
  </body>
</html>

Redirect method

The redirect method launches the flow in a new application page. The user is redirected to the flow's HTML form on the new page, which replaces the previous page. Most of the configuration to redirect users to a new application page to create the flow policy and complete flow actions takes place in the PingOne DaVinci UI console. However, the application's landing page does need links to direct the browser to the page that contains the correct flow action.

Prerequisites

  • A PingOne trial or subscription license.
  • A pingOne worker application to add a PingOne connection in DaVinci.
  • A connection in DaVinci associated with the PingOne application.
  • A DaVinci application that is associated with a flow policy and a flow.

Workflow

  1. Create a worker application in PingOne to provide the credentials needed for adding a PingOne connection in DaVinci. See "Creating PingOne credentials" in Connecting DaVinci with PingOne.

  2. Add a PingOne connection in DaVinci. See "Adding PingOne connections" in Connecting DaVinci with PingOne.

  3. Create a DaVinci flow, see Getting Started. Then, create a DaVinci flow policy and add the flow to the flow policy. See Configuring a flow policy. You'll also need to create a DaVinci application, and associate it with the flow. See Creating an application.

  4. In the DaVinci UI console, click Applications, and open the application for the flow policy you want to integrate with your app. See Configuring a flow policy.

  5. Configure DaVinci as an external identity provider in PingOne. See "Configuring an external IDP" in Connecting DaVinci with PingOne.

  6. Configure a PingOne sign-on policy that uses the DaVinci external identity provider for the sign-on flow. See Adding an external identity provider sign-on step.

Example

To configure the HTML form that is embedded in the application page, add HTML in the HTML Template text area control to create the login form interface elements. The following example shows the HTML for the Username and Password fields:

<div class="app-container" style="display: block;">
    <div class="page__content" style="height: 100%;">
        <div class="card card--no-padding">
            <div class="card__content">
                <div class="org-logo"> <img class="org-logo__image" src="https://d3uinntk0mqu3p.cloudfront.net/branding/market/a3d073bc-3108-49ad-b96c-404bea59a1d0.png" alt="Company Logo" />
                </div>
                <div data-skcomponent="skerror"
                    class="feedback feedback--error sk-alert sk-alert-danger has-text-danger has-background-danger-light"
                    data-id="feedback" data-skvisibility=""></div>
                <form class="form" id='signOnForm' data-id="signOnForm">
                    <div class="field float-label"> <input class="text-input float-label__input" data-id="username-input" id="username" name="username" type="text" autocomplete="on" value="" />
                        <label class="float-label__label" for="username">Username</label> </div>
                    <div class="field float-label"> <input class="text-input text-input__password float-label__input" data-id="password-input" id="password" name="password" type="password" autocomplete="on" value="" />
                        <label class="float-label__label" for="password">Password</label> </div>
                    <div class="control">
                        <button class="field is-primary mt-2 button file-input--button button--primary brand-primary-bg" data-id="button" type="submit" data-skcomponent="skbutton" data-skbuttontype="form-submit" data-skform="signOnForm" data-skbuttonvalue="submit">
                            Sign On<i class="fas fa-forward ml-2"></i></button>
                    </div>
                </form>
            </div>
        </div>
    </div>
</div>
Configuring the redirect in your application

An application's landing page might have buttons for Sign On, Forgot Password, and Create an Account. Each button is assocated with a specific URL that redirects the browser to the appropriate application page, which initiates the flow and presents the input form.

To integrate the sign-on action you created above into your application, you need to configure a Sign On button that links to the endpoint URL associated with the PingOne sign-on flow. The HTML for the Sign On button looks something like this:

<p class="control">
    <a href="https://auth.pingone.com/{{envID}}/as/authorize?client_id={{clientID}}&scope=openid&response_type=code&redirect_uri=https://example.com">
    <button class="btn btn-primary btn-xl" style="font-family: 'Ubuntu', sans-serif;" id="signInBtn">Sign On</button>
    </a>
</p>
 

In this case, the https://auth.pingone.com/ is the PingOne resource server's domain. However, by creating a PingOne sign-on policy that uses DaVinci as the external identity provider, the sign-on flow redirects to a DaVinci URL that initiates the flow associated with the DaVinci flowPolicyID in the request.

{{davinciAuthPath}}/auth/{{companyID}}/policy/{{flowPolicyID}}/authorize?client_id={{davinciAppID}}&response_type=code&scope=openid&redirect_uri=https://example.com
 

In this case, the {{davinciAuthPath}} is the DaVinci resource server's domain, https://yourAppHost.singularkey.com/v1. The UI page presented to the end user contains the HTML for the sign-on form, which matches the application's overall branding and style. The {{flowPolicyID}} value must be the ID for the DaVinci flow policy associated with the application.

For more information about the properties of the authorize URL, see Using Authorization APIs.

API method

Use the PingOne DaVinci API method to call our REST APIs from your application page. The API calls might be to initiate or process transactions for DaVinci flows, or call other APIs for supported Ping Identity products and services.

This integration method is well-suited to flows that involve processes requiring no user interaction. For example, you might have a DaVinci flow that does risk analysis, and you want your application to handle the approval process for the flow based on the risk factors. Of course, you can also call our APIs when using the Widget or Redirect methods.

Prerequisites

  • A PingOne trial or subscription license.
  • A DaVinci application that's associated with a flow policy.
  • Your DaVinci Company ID, API Key, and Policy ID.

Workflow

  1. Create a worker application in PingOne to provide the credentials needed for adding a PingOne connection in DaVinci. See "Creating PingOne credentials" in Connecting DaVinci with PingOne.

  2. Add a PingOne connection in DaVinci. See "Adding PingOne connections" in Connecting DaVinci with PingOne.

  3. Create a DaVinci flow, see Getting Started. Then, create a DaVinci flow policy and add the flow to the flow policy. See Configuring a flow policy. You'll also need to create a DaVinci application, and associate it with the flow. See Creating an application.

  4. Using a tool like Postman, construct the DaVinci REST API calls you need. See Initiating Flow Policies and Using Authorization APIs for more information.

    You can also call the APIs for any supported Ping Identity product or service.

  5. Test the flow in Postman or a similar tool by specifying the DaVinci API path (the api.singularkey.com production domain, or a custom domain we've set up with you), the Company ID, API Key, and Policy ID.

  6. When your testing is successful, export the API calls in the programming language of your choice from Postman (or other such tool), and add the API calls to your application source code.

Example

This Javascript function example calls the Initiate Registration API:

async register({rawPayload}) {
        console.info('Integration.SingularKey.js', 'Registering a new user with PingOne using DaVinci.');

        let myHeaders = new Headers();
        myHeaders.append("X-SK-API-Key", this.envVars.SINGULARKEY_REGISTRATION_KEY);
        myHeaders.append("Content-Type", "application/json");

        const requestOptions = {
            method: 'POST',
            headers: myHeaders,
            body: rawPayload,
            redirect: 'manual'
        };
        const url = this.createUrl({skFlowId: this.envVars.SINGULARKEY_REGISTRATION_POLICY_ID});
        const response = await fetch(url, requestOptions);
        const jsonResponse = await response.json();
        return jsonResponse;
    }

Using Authorization APIs

PingOne DaVinci integrates with applications that use standards-compliant protocols. As such, it provides the framework for providing access to protected HTTP resources. The DaVinci authorization endpoint {{davinciAuthPath}}/auth/{{companyID}}/policy/{{policyID}}/authorize interacts with the resource owner and obtains an authorization grant.

The following request samples show common authorize endpoints that are useful to DaVinci application integrations.


Authorize using POST

Toggle stack

Authorize using GET

Toggle stack

Well-Known OIDC Config

Toggle stack

Initiating Flow Policies

The POST {{davinciAuthPath}}/company/{{companyID}}/policy/{{policyID}}/start endpoint initiates the flow (or flows) that are included in the flow policy specified by {{policyID}} in the request URL. However, before you can initiate a flow policy, you must complete the following tasks:

  1. Create an application configuration.

  2. Create the flow actions.

  3. Create the flow policy and associate a flow (or flows) with the policy.

  4. Associate the deployed flow policy with the application.

For more information, see Creating an application, How to create a flow, and How to create a flow policy.

You can associate multiple flow policies with an application. The /start API initiates a flow policy associated with an application, depending on the {{policyID}} passed in with the request.

Using an input schema with the flow

Flows can receive input parameters when invoked. It is good practice to configure the flow to validate input provided by users. Associating an input schema with the flow achieves input validation to ensure that the flow only allows input that meets your data criteria.

The following sample shows the request body for a /start request that uses input schema values in a user profile update flow. If input schema properties are designated as required, the flow invocation needs to pass in the required parameters to start the flow.

{
    "hostname": "bxhealth.devops.com",
    "dn": "uid=testpatient,ou=People,dc=bxhealth,dc=org",
    "modifications": [
        {
            "attributeName": "givenName",
            "modificationType": "set",
            "values": [
                "PatientFirst"
            ]
        },
        {
            "attributeName": "sn",
            "modificationType": "set",
            "values": [
                "PatientLast"
            ]
        }
    ]
}

Initiate Login

Toggle stack

Initiate Registration

Toggle stack

Initiate MFA Create Device

Toggle stack