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 Fraud and PingOne Risk, 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, see 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. For help, see Adding a connection.

Connector configuration

Client ID
The Client ID of the worker application you created in PingOne.
Client Secret
The Client Secret from the Configuration tab of your PingOne worker application.
Endpoint URL
The decision endpoint to which the connector submits decision requests. Get the URL from the Decision Endpoints page in PingOne Authorize.

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, 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 example, to report fraud case information or provide 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 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.
      Tip:

      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.
      Note:

      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 (makeDecisionRequest)

Submit a decision request to a PingOne Authorize endpoint.


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.

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


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:

For information about PingOne audit logs, see Audit.

For information about the PingOne Authorize events available in audit logs, see PingOne Authorize event monitoring.