PingOne DaVinci

Launching a PingOne flow with a redirect using an external IdP

You can configure PingOne and DaVinci so that you can invoke specifically-configured flows through PingOne. This method configures DaVinci as an identity provider (IdP) in PingOne.

If you have not yet configured PingOne to launch DaVinci flows, follow the steps in Launching a PingOne flow with a redirect instead.

For additional information about integrating PingOne with DaVinci, see the DaVinci Application Integrations guide.

Creating PingOne credentials

Create a set of credentials for adding PingOne connections.

Steps

  1. Sign on to PingOne.

  2. Create a worker app as described in the PingOne documentation.

  3. Assign the following roles to the worker app:

    • Identity Data Admin

    • Environment Admin

  4. Note the Client ID, Client Secret, and Environment ID for the worker app.

  5. Click Finish.

  6. Go to Applications → Applications, click the application to open the application details, and click the toggle switch in the upper right to enable the application.

Adding PingOne connectors

Add one or more PingOne connectors in DaVinci to enable your flows to use PingOne-related capabilities such as reading or updating users.

Steps

  1. Sign on to DaVinci.

  2. Click the Connectors tab.

  3. Click Add Connector.

  4. In the list of available connectors, select one of the PingOne connectors and click .

    The New Connector modal opens.

  5. Enter a name for the new connector and click Create.

  6. Find and click the newly-created connector in the list of your connectors.

  7. Set up the connector configuration.

    The Client ID, Client Secret, and Environment ID that you noted in the previous procedure are used to configure the PingOne connectors.

  8. Click Apply.

Preparing a flow

Create a flow, then prepare it for implementation through an OpenID Connect (OIDC) call to PingOne.

This procedure does not go into detail about creating a flow. See the other use cases for additional information about creating specific flows. The preparation steps apply regardless of the purpose of your flow.

This implementation method launches the flow in a new page. The user is redirected to the flow, which replaces the previous page and uses a DaVinci URL.

This implementation method is simple and does not require the addition of a widget to the page. It’s also well-suited for any type of flow. Because the flow takes the entire page, you must design the flow to match your own branding and style.

Depending on the purpose of the flow, you might want to include a token connector, which directs PingOne to mint a token for the user.

You can reference information from PingOne in your flow. The format for this information is global.skOpenId.p1Oidc.<request object hierarchy>, where the hierarchy is taken from the request object schema.

The full request object schema for OIDC is:

"p1Oidc": {
  "id": "<ID value>",
  "environment": {
    "id": "<environment ID value>"
  },
  "application": {
    "id": "<application ID value>"
  },
  "user": {
    "id": "<user ID value>"
  },
  "request": {
    "http": {
      "remoteIp": "<remote IP value>",
      "userAgent": "<user agent information>",
      "headers": {
        "Accept-Language": [
          "<language value>"
        ]
      }
    },
    "oidc": {
      "responseTypes": [
        "<response type>"
      ],
      "acrValues": [
        "<acr value>"
      ],
      "scopes": [
        "<scope value>"
      ],
      "parameters": {
        <One or more parameter-value pairs>

The full request object schema for Security Assertion Markup Language (SAML) is:

"p1Oidc": {
    "id": "<ID value>",
    "environment": {
        "id": "<environment ID value>"
    },
    "application": {
        "id": "<application ID value>"
    },
    "request": {
        "http": {
            "remoteIp": "<remote IP value>",
            "userAgent": "<user agent information>"
        },
        "saml": {
            "environmentId": "<environment ID value>",
            "urlContext": {
                "environmentId": "<environment ID value>",
                "customDomainHost": "<custom domain host value>,
                "hostUrl": "<host URL value>",
                "authHostUrl": "<URL value>",
                "idpEntityId": "<IDP entity ID value>",
                "internalIdpEntityId": "<internal IDP entity ID value>",
                "flowHeaders": {
                    "X-Forwarded-Host": "<host value>"
                },
                "host": "<host name>",
                "customDomain": <domain value>
            },
            "ssoInitialized": <value>,
            "requestBinding": <value>,
            "requestSigned": <value>,
            "ssoRequest": {
                "requestId": <ID value>,
                "version": <value>,
                "issueInstant": <value>,
                "destination": <value>,
                "consent": <value>,
                "spEntityId": "<security ID value>",
                "forceAuthn": <value>,
                "passive": <value>,
                "acsUrl": "<value>",
                "acsBinding": "<value>",
                "subject": <value>,
                "signed": <value>,
                "authnContextRef": <value>
            },
            "application": {
                "id": "<ID value>",
                "name": "<name value>",
                "protocol": "<value>",
                "enabled": <value>,
                "spEntityId": "<value>",
                "acsBinding": "<value>",
                "acsUrls": ["<value>"],
                "assertionDuration": <value>,
                "sloBinding": "<value>",
                "assertionSigned": <value>,
                "responseSigned": <value>,
                "environment": {
                    "id": "<value>"
                }
            },
            "user": <user name value>,
            "relayState": <value>,
            "idpIssuer": "<issuer value>",
            "attributes": <value>
        }
    }
}

For example, the following code references the remote IP:

global.skOpenId.p1Oidc.request.http.remoteIp

Any property you reference must be included by the configured scopes, as described in the Configuring an external IDP section.

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.

Creating an application

Create an application in DaVinci to enable your flow.

Steps

  1. Sign on to DaVinci.

  2. Click the Applications tab.

  3. Click Add Application.

    The Add Application modal opens.

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

  5. Click Create.

  6. Find the application and click Edit.

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

    • Company ID

    • Client ID

    • Client Secret

    • Issuer

    • Token Endpoint

    • JWKS Endpoint

  8. Create a flow policy:

    1. Click the Flow Policy tab.

    2. Click Add Flow Policy.

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

    4. In the flow list, select your flow.

    5. In the version list, select Latest Version.

    6. Click Create Flow Policy.

      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 an external IDP

Configure DaVinci as an external IdP in PingOne.

Steps

  1. Sign on to PingOne.

  2. Add DaVinci as an OIDC identity provider according to the PingOne documentation.

    1. For the Connection Details, use the values that you noted in Creating an application:

      • Client ID

      • Client Secret

    2. In the Discovery Document URI field, enter the well-known endpoint to configure the discovery detail values. The format is:

      https://auth.pingone.com/<EnvironmentID>/davinci/.well-known/openid-configuration

    3. In the Requested Scopes field, add a scope for each entity you want to import from the PingOne flow. The format for these scopes is:

      p1FlowRequest:<parent entity>.<entity>

      The entity name and parent entities are determined by the object request schema documented above. For example, to make the remote IP available, add the scope p1FlowRequest:http.remoteIp.

      You can add the p1FlowRequest scope to make all entities from the PingOne flow available, but this can sometimes result in request size errors.

    Do not configure the User Information Endpoint.

  3. Create the authorization endpoint using the following structure:

    https://<domain>/v1/auth/<companyID>/policy/<policyID>/authorize

    Use the values that you noted in the previous procedure:

    • Company ID

    • Policy ID

  4. Create the external IdP sign-on policy step according to the PingOne documentation.

    1. In the External Identity Provider list, select the external IdP application you created in step 1.

    2. In the Required Authentication Level field, enter policyId-<your policy ID>. For example, policyId-69b043b9edeb60b6c1945617ab1b4fae.

    3. Select Pass user context to provider.

    4. Select the external IdP application, and then click Save to save your changes.

  5. Create an application in PingOne and assign the sign-on policy step to that application according to the PingOne documentation.

  6. Copy the Callback URL for the external IdP in PingOne.

  7. Optional: Copy the JWKS information to enable PingOne context information to be used by DaVinci.

    1. Copy the PingOne Application JWKS URL.

    2. Access the JWKS URL and copy the complete JWKS key.

  8. Sign on to DaVinci.

  9. Click the Applications tab.

  10. Find the application that you previously created and click Edit.

  11. Click the OIDC tab, and then add the copied callback URL value to the Redirect URLs field.

  12. Optional: Enter the JWKS information to enable DaVinci to use context information from PingOne within flows.

    1. Click Applications.

    2. Open your application.

    3. Click the OIDC tab.

    4. In the Service Provider (SP) JWKS URL field, enter the JWKS URL.

    5. In the Service Provider (SP) JWKS Keys to Verify Authorization Request Signature field, enter the JWKS key.

Invoking the flow

Add a link to the resource that invokes the flow using a call to PingOne.

Steps

  1. Open the source file for the resource that will launch the flow.

  2. Create a call to your PingOne application according to the PingOne documentation and add it to the launching resource.

    The general format used for this call is:

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

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

    global.skOpenId.<parameter name>

  3. 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.