Connectors

PingOne Authorize Connector

This connector lets you use PingOne Authorize for policy-based authorization decisions in your PingOne DaVinci flow.

PingOne Authorize controls what users can see and do inside of applications and APIs. It allows organizations to centrally configure authorization requirements, ranging from simple rules to real-time, fine-grained policies.

PingOne Authorize can integrate with other PingOne services, such as PingOne Protect, and exploit information in a PingOne user profile to augment authorization events in real-time.

Use the PingOne Authorize connector to:

  • Externalize authorization from your DaVinci flows, allowing separation of duties between the team controlling the user experience and the team controlling what users are authorized to see and do.

  • Leverage real-time data in fine-grained policies that go beyond identity and roles.

  • Make adaptive, context-aware authorization decisions that result in permit, deny, or challenge outcomes.

  • Assemble and provide DaVinci with authorized information used in flows, for example, retrieving the list of accounts that a user is authorized to access.

Setup

Resources

For information and setup help, learn more in the following documentation:

Requirements

To use the connector, you’ll need:

  • A PingOne Authorize license

  • A PingOne environment with a configured worker application

Setting up PingOne Authorize

  1. Follow the instructions in Getting started with PingOne Authorize.

  2. In the Trust Framework, define the resources needed to build policies.

  3. Write policies for authorization decisions that you want to include in your flow. Include advice in your policies for statements you want to return to your flows.

  4. Publish the policies to a Decision Endpoint.

Setting up the PingOne Authorize connector configuration

In DaVinci, add a PingOne Authorize connection. Learn more in Adding a connector.

Connector configuration

Client ID

The Client ID of the worker application that you created in PingOne.

Client Secret

The Client Secret from the Configuration tab of your PingOne worker application.

Endpoint

The decision endpoint to which the connector submits decision requests. On the Decision Endpoints page in PingOne Authorize, expand the appropriate endpoint to get the URL or the Endpoint ID.

Using the connector in a flow

The PingOne Authorize connector provides these capabilities:

Make Decision Request

Add authorization decision requests to your flows. Decision requests return permit, deny, indeterminate, or not applicable decisions that you can act on in your flows.

Find Statements

Find statements returned in decision responses and use them as inputs in subsequent nodes. Add multiple PingOne Authorize connector nodes at different points in your flow to use the authorized information returned in statements.

When a statement code is found, you can act on it in your flow. For example, you can use it to determine if multi-factor authentication (MFA) is required or a risk update is needed. You can also extract authorized information from the statement payload, for use in scenarios such as reporting fraud case information or providing a list of authorized IDs or accounts in your flow.

In the following example, the first PingOne Authorize connector uses information about an authenticated user to make an authorization decision. The second PingOne Authorize connector finds a statement code in the decision response to determine if MFA is required.

Screen capture of an example PingOne Authorize flow in DaVinci.

Make a decision request

Collect user information with an HTML form, then use the first PingOne Authorize connector to send the information to PingOne Authorize, and use the decision response in your flow.

  1. In your flow, build a sign-on flow that populates a User ID field in an HTTP connector with the HTML Form capability.

  2. Send user information to PingOne Authorize:

    1. After your sign-on flow, add the PingOne Authorize connector and select the node in your flow.

    2. Select the Make Decision Request capability.

    3. In the User ID field, click {} and select the User ID variable from your HTML Form node.

  3. Populate attribute information in the decision request:

    1. In the Fields section, click to add one or more key-value pairs. These pairs map to attributes in PingOne Authorize.

    2. In the Key field, enter the full name of the attribute that you want to map to the decision request.

    3. In the Value field, click {} and select a variable from a node. Alternatively, you can enter a hard-coded value.

      To edit key-value pairs, click the Pencil icon. In edit mode, the icon turns into an X icon. Click the X icon to leave edit mode. To delete a Key-Value pair in edit mode, click the - icon under Key.

      Screen capture of Key/Value field options including the Delete button.

    4. Click Apply.

  4. Add a node to capture the decision response from PingOne Authorize:

    1. After the PingOne Authorize node, add a Function connector and select the node in your flow.

    2. Select the A == B (Multiple Conditions) trigger.

    3. In the Value A field, click {} and select the decision variable from your PingOne Authorize node.

    4. Click Add and enter PERMIT in the Value 1 field.

    5. Click Add and enter DENY in the Value 2 field.

      In this example flow, Not Applicable and Indeterminate decisions fall under No Match and connect to an Error node.

    6. Click Apply.

  5. Add nodes to your flow that act on the Permit, Deny, and No Match decision responses.

  6. Test your flow:

    1. Click Save, Deploy, then Run.

    2. Review status messages.

Find statements

Use the second PingOne Authorize connector to find a statement code that matches advice in a policy, then use the code in your flow to determine if MFA is required. If the code is found in decision response statements, then the outcome of the node is true.

  1. Find a statement code in the decision response from the first PingOne Authorize node:

    1. After the first PingOne Authorize node in your flow, add another PingOne Authorize connector and select the node in your flow.

    2. Select the Find Statement(s) capability.

    3. In the Statement Code field, enter the statement Code from Advice and Obligations in your policy rule. For example, the following image shows the MFA_REQ advice code in a PingOne Authorize rule.

      Screen capture of Advice and Obligations in a PingOne Authorize policy rule.

    4. In the Statements field, click {} and select the statements (array) output variable from the first PingOne Authorize node in your flow.

      Screen capture of Statements options for a PingOne Authorize connector.

    5. Click Apply.

  2. After the second PingOne Authorize node in your flow, add nodes for an MFA flow.

  3. Test your flow:

    1. Click Save, Deploy, then Run.

    2. Review status messages.

Capabilities

Make Decision Request

Submit a decision request to a PingOne Authorize endpoint.

Show details
Properties
Parameters keyValueList

The list of parameters included in the decision request.

User ID textField

The ID of the PingOne user on whose behalf the connector is making a decision request.

Input Schema
default object
parameters array

Input parameters for the decision request.

userId string

ID of the PingOne user on whose behalf the connector is making a decision request.

clientId string

The Client ID of the PingOne worker application.

clientSecret string

The Client Secret of the PingOne worker application.

endpointUrl string

The PingOne Authorize decision endpoint to which the connector submits decision requests.

Output Schema
output object
rawResponse object

The body of the HTTP response.

statusCode number

The HTTP status code of the response.

statements array

Statements produced by the decision evaluation.

decision string

The result of the decision evaluation. This can be Permit, Deny, Not Applicable, or Indeterminate.

headers object

The decision response header.

Find Statement(s)

Filter decision response statements by code.

Show details
Properties
Statement Code textField

The statement code to search for.

Statements textField

The array of statements to search through.

Input Schema
default object
statements string

The array of statements to search through in a decision response.

code string

The advice code from a PingOne Authorize policy rule to search for in an array of statements from a decision response.

Output Schema
output object
statements array

Statements in the decision response that match the input statement code. Statements with the same code are grouped together.

Troubleshooting

You should start any troubleshooting efforts by checking PingOne Authorize events in the audit log. The following resources can help you solve issues with the connector:

Learn more about PingOne audit logs in Audit.

Learn more about the PingOne Authorize events available in audit logs in PingOne Authorize event monitoring.