PingAuthorize Authorization Policy Decision API Reference

The PingAuthorize Server provides Authorization Policy Decision APIs to support non-API use cases.

The Authorization Policy Decision APIs consist of the following policy decision point (PDP) APIs:

The Authorization Policy Decision APIs can indicate when a request or response triggers advice, but the application server must implement the advice.

To make a PDP API available, you must:

XACML-JSON PDP API Reference

The XACML-JSON PDP API provides a standards-based HTTP API for decisions determined based on the policies configured within the PingAuthorize Server Policy Decision Service.

The XACML-JSON PDP API is implemented as a single endpoint that consuming application servers can access using POST requests to the /pdp path. The HTTP requests must include the appropriate Content-Type and Accept headers, and request bodies must adhere to the XACML-JSON standard. For more information, see Requests and responses.

The XACML-JSON PDP API supports the Multirequests JSON object, which allows a client to make multiple decision requests in a single HTTP request.

A successful XACML-JSON PDP API request goes through a two-phase flow:

  1. The client makes the XACML-JSON request, which is received by the XACML-JSON PDP API. The API converts the request to a PingAuthorize Server batch decision request and attempts to authorize the client.

  2. On successful authorization, the request is handed off to the Policy Decision Service to process decisions in batch for the XACML-JSON PDP API. The API then converts the batch decision responses to a XACML-JSON response and writes the response to the client.

Authorization

Before calculating a decision, the XACML-JSON PDP API attempts to authorize the client making the XACML-JSON PDP API request by invoking the Policy Decision Service.

To target a PDP authorization request in-policy, it must apply to the PDP Service and the authorize Action. The default policies included with PingAuthorize Server perform this authorization by only permitting requests with active access tokens that contain the urn:pingauthorize:pdp scope.

For example, under the default policies, the following request would result in an authorized client when the PDP is configured with a mock access token validator:

curl --insecure -X POST \
  -H 'Authorization: Bearer {"active":true,"scope":"urn:pingauthorize:pdp", "sub":"<valid-subject>"}' \
  -H 'Content-Type: application/xacml+json' \
  -d '{"Request":{}}' "https://<your-pingauthorize-host>:<your-pingauthorize-port>/pdp"

The default policies are intended to provide a foundation. You can modify these policies if additional authorization logic is required.

Decision processing

On successful client authorization, the XACML-JSON PDP API invokes the Policy Decision Service with the batch decision requests converted from the XACML-JSON request.

When writing policy for the XACML-JSON PDP API endpoint, you should note the mapping between the XACML-JSON schema and the PingAuthorize Server decision request. For more information, see Requests and Responses.

After the Policy Decision Service determines a decision response, it hands the response back to the XACML-JSON PDP API to provide to the client.

Requests and responses

Requests

The XACML-JSON PDP API first converts the XACML-JSON request to a batch decision request for the policy decision point to be consumed by the Policy Decision Service. Policies can match a decision request by Service, Domain, Action, or other attributes.

The example XACML-JSON request body illustrates the conversion to a batch decision request.

The example request shows a single decision request with the following attributes:

  • A domain of Sales.Asia Pacific

  • An action of Retrieve

  • A service of Mobile.Landing page

  • An identity provider of Social networks.Spacebook

  • A single attribute named Prospect name, with a value of B. Vo

The following table shows how these values map from the Trust Framework entities to the XACML-JSON request.

Parent (JSON Path) Field (JSON Path) PingAuthorize Trust Framework type Example value
$.Request $.AccessSubject[*].Attribute[?(@.AttributeId == "domain")].Value Domain Sales.Asia Pacific
$.Action[*].Attribute[?(@.AttributeId == "action")].Value Action Retrieve
$.Resource[*].Attribute[?(@.AttributeId == "service")].Value Service Mobile.Landing page
$.Environment[*].Attribute[?(@.AttributeId == "symphonic-idp")].Value Identity Provider Social Networks.Spacebook
$.Category[*].Attribute[?(@.AttributeId == "attribute:Prospect name")].Value Other Attribute (`Prospect name` in this case) B. Vo

Responses

The XACML-JSON PDP API converts batch decision responses to a XACML-JSON response.

XACML-JSON responses include decisions, such as Permit or Deny, and any obligations or advice that matched during policy processing.

The following table shows the mapping from a decision response to an XACML-JSON response.

Parent (JSON Path) Field (JSON Path) PingAuthorize Trust Framework type
$.Response[*] $.Decision Decision
$.Response[*].Obligations[*] Advice (obligatory)
$.Id Advice code
$.AttributeAssigments[?(@.AttributeId == "payload")].Value Advice payload
$.Response[*].AssociatedAdvice[*] Advice (non-obligatory)
$.Id Advice code
$.AttributeAssigments[?(@.AttributeId == "payload")].Value Advice payload

Authorize client with MultiRequests JSON object

Toggle stack

JSON PDP API Reference

The JSON policy decision point (PDP) API provides an HTTP API for decisions determined by the policies configured within the PingAuthorize Server Policy Decision Service.

The JSON PDP API is implemented with both an individual decision request endpoint and a batch request endpoint that consuming application servers can access using POST requests to the /governance-engine or /governance-engine/batch paths, respectively.

A successful JSON PDP API request goes through the following flow:

  1. The client makes the JSON request, which is received by the JSON PDP API. The API forwards the request to the PDP.

  2. When the PDP returns a response, the API sends the response to the client.

Individual requests

A valid JSON PDP API request is a simple JSON object that can be forwarded to the Policy Decision Service. Policies can match a decision request by Service, Domain, Action, or other attributes.

The following table describes the values contained in a valid JSON PDP API request.

Field Type Required PingAuthorize Trust Framework type Example value
domain string no Domain Sales.Asia Pacific
action string no Action Retrieve
service string no Service Mobile.Landing page
identityProvider string no Identity Provider Social Networks.Spacebook
attributes map<string, string> yes Other Attributes {"Prospect name": "B. Vo"}

Authorize client with individual decision

Toggle stack

Batch requests


Authorize client with batch decision

Toggle stack