XACML-JSON PDP API request and response flow
The XACML-JSON policy decision point (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, which 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.
| XACML-JSON PDP API Endpoint path | Action | Content-Type/Accept | Request data |
|---|---|---|---|
|
POST |
application/xacml+json |
XACML-JSON |
The XACML-JSON PDP API supports the .oasis-open.org/xacml/xacml-json-http/v1.1/csprd01/xacml-json-http-v1.1-csprd01.html//[MultiRequests JSON object], which allows a client to make multiple decision requests in a single HTTP request.
|
Because this object also supports single decision requests, it is the only supported XACML-JSON request format. See the .pingidentity.com/pingauthorize/authorization-policy-decision/v1/api/guide///[XACML-JSON PDP API Reference] for more information about making API requests. |
A successful XACML-JSON PDP API request goes through the following two-phase flow:
-
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.
-
On authorize success, 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.
The following sections describe these stages in more detail.
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 following example XACML-JSON request body illustrates the conversion to a batch decision request. For an example with more than one decision request, see Example.
{
"Request": {
"MultiRequests": {
"RequestReference": [{
"ReferenceId": [
"dom",
"act",
"srv",
"idp",
"att"
]
}]
},
"AccessSubject": [{
"Id": "dom",
"Attribute": [{
"AttributeId": "domain",
"Value": "Sales.Asia Pacific"
}]
}],
"Action": [{
"Id": "act",
"Attribute": [{
"AttributeId": "action",
"Value": "Retrieve"
}]
}],
"Resource": [{
"Id": "srv",
"Attribute": [{
"AttributeId": "service",
"Value": "Mobile.Landing page"
}]
}],
"Environment": [{
"Id": "idp",
"Attribute": [{
"AttributeId": "symphonic-idp",
"Value": "Social networks.Spacebook"
}]
}],
"Category": [{
"Id": "att",
"Attribute": [{
"AttributeId": "attribute:Prospect name",
"Value": "B. Vo"
}]
}]
}
}The previous example 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 ofB. 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 |
|---|---|---|---|
|
|
Domain |
|
|
Action |
|
|
|
Service |
|
|
|
Identity Provider |
|
|
|
Other Attribute ( |
|
To illustrate how you can match rules against the Prospect name Trust Framework attribute, the following image shows how Prospect name is defined in the Policy Editor. In this example, the Prospect name attribute has a Request resolver and a Value Settings Type of String.
|
The Trust Framework attribute name must be a case-sensitive match with the decision request |
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.
A PDP authorization request can be targeted in policy as having service PDP with action authorize. 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. You can see this policy in Global Decision Point → PDP API Endpoint Policies → Token Authorization.
|
The parent of the Token Authorization policy, PDP API Endpoint Policies, constrains the Token Authorization policy to apply to the PDP service only. |
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. 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.
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 Policy Enforcement Point (PEP) must apply any obligations or advice. |
The following table shows the mapping from a decision response to a XACML-JSON response.
| Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type |
|---|---|---|
|
|
Decision |
|
|
Advice (obligatory) |
|
Advice code |
|
|
Advice payload |
|
|
|
Advice (non-obligatory) |
|
Advice code |
|
|
Advice payload |
The following example is an appropriate response based on the request in Requests.
{
"Response": [{
"Decision": "Permit",
"Obligations": [{
"Id": "obligation-id",
"AttributeAssignments": [{
"AttributeId": "payload",
"Value": "payload-value"
}]
}],
"AssociatedAdvice": [{
"Id": "advice-id",
"AttributeAssignments": [{
"AttributeId": "payload",
"Value": "payload-value"
}]
}]
}]
}In this example, it is up to the application server to handle the obligations and advice in the response.
Example
This example shows how to use the XACML-JSON PDP API in the context of a peer recognition program.
The example company, AnyCompany, has an internal peer recognition program. The peer recognition program allows employees to recognize each other by awarding each other points. The points can be spent in different categories. Each category requires a minimum number of points for the category to become available. When an employee spends enough points in a category, a related product becomes unlocked in an online catalog that the employee can purchase. AnyCompany has implemented a web application where employees spend their points, view their available catalog, and purchase products.
In this example, the web application that implements the online catalog can make the following XACML-JSON request when an employee spends their points. The request includes three decision requests.
{
"Request":{
"MultiRequests":{
"RequestReference":[
{
"ReferenceId":[
"domain-1",
"action-1",
"service-1",
"idp-1",
"attributes-1"
]
},
{
"ReferenceId":[
"domain-1",
"action-2",
"service-2",
"idp-1",
"attributes-2"
]
},
{
"ReferenceId":[
"domain-1",
"action-1",
"service-3",
"idp-1",
"attributes-1"
]
}
]
},
"AccessSubject":[
{
"Id":"domain-1",
"Attribute":[
{
"AttributeId":"domain",
"Value":"AnyCompany.Management"
}
]
}
],
"Action":[
{
"Id":"action-1",
"Attribute":[
{
"AttributeId":"action",
"Value":"Update"
}
]
},
{
"Id":"action-2",
"Attribute":[
{
"AttributeId":"action",
"Value":"Retrieve"
}
]
}
],
"Resource":[
{
"Id":"service-1",
"Attribute":[
{
"AttributeId":"service",
"Value":"Peer Recognition.Point allocation"
}
]
},
{
"Id":"service-2",
"Attribute":[
{
"AttributeId":"service",
"Value":"Peer Recognition.Points unspent"
}
]
},
{
"Id":"service-3",
"Attribute":[
{
"AttributeId":"service",
"Value":"Peer Recognition.Products"
}
]
}
],
"Category":[
{
"Id":"attributes-1",
"Attribute":[
{
"AttributeId":"attribute:User input.User Id",
"Value":"self"
},
{
"AttributeId":"attribute:User input.Entertainment",
"Value":8
},
{
"AttributeId":"attribute:User input.Travel",
"Value":5
},
{
"AttributeId":"attribute:User input.Academics",
"Value":6
},
{
"AttributeId":"attribute:User input.Electronics",
"Value":5
},
{
"AttributeId":"attribute:User input.Sports",
"Value":5
},
{
"AttributeId":"attribute:User input.Food",
"Value":7
},
{
"AttributeId":"attribute:User input.Music",
"Value":4
}
]
},
{
"Id":"attributes-2",
"Attribute":[
{
"AttributeId":"attribute:User input.User Id",
"Value":"self"
}
]
}
],
"Environment":[
{
"Id":"idp-1",
"Attribute":[
{
"AttributeId":"symphonic-idp",
"Value":"AnyCompany SSO"
}
]
}
]
}
}The three decision requests are summarized in the RequestReference JSON array. Each JSON object in the array contains a single field, ReferenceId. Each ReferenceId field contains an array of Id references that represent the content of the decision request. The following tables highlight the key components of each decision request.
|
For brevity, only one Trust Framework attribute is listed in each decision request. |
| Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value |
|---|---|---|---|
|
|
Domain |
|
|
|
Action |
|
|
|
Service |
|
|
|
Identity Provider |
|
|
|
Attribute |
|
| Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value |
|---|---|---|---|
|
|
Domain |
|
|
|
Action |
|
|
|
Service |
|
|
|
Identity Provider |
|
|
|
Attribute |
|
| Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value |
|---|---|---|---|
|
|
Domain |
|
|
|
Action |
|
|
|
Service |
|
|
|
Identity Provider |
|
|
|
Attribute |
|
The following is an example response to the previous example request.
The XACML-JSON response contains the decision responses for each of the three decision requests. The order of the decision responses corresponds to the order of the decision requests. In the first decision response, the system policy does not detect any problems and permits the employee to change her point allocation. In the second decision response, the system policy allows the employee to view her own unspent points and indicates that the value is now 0. In the third decision response, the system permits the retrieval of the employee’s own product catalog and indicates which of the products should be unlocked for purchase.
Given the response, the web application can now render the content for the three decision requests. It renders the 0 unspent points and all catalog products, with purchase buttons disabled where appropriate.
{
"Response": [
{
"Decision": "Permit",
"Obligations": [],
"AssociatedAdvice": []
}, {
"Decision": "Permit",
"Obligations": [],
"AssociatedAdvice": [{
"Id": "remaining-points",
"AttributeAssignments": [{
"AttributeId": "payload",
"Value": "0"
}]
}]
}, {
"Decision": "Permit",
"Obligations": [],
"AssociatedAdvice": [{
"Id": "catalog",
"AttributeAssignments": [{
"AttributeId": "attribute:Derived.Product availability.Trip to exotic country",
"Value": "false"
}, {
"AttributeId": "attribute:Derived.Product availability.Super Bowl tickets",
"Value": "false"
}, {
"AttributeId": "attribute:Derived.Product availability.Movie theater gift card",
"Value": "true"
}, {
"AttributeId": "attribute:Derived.Product availability.Encyclopedia subscription",
"Value": "false"
}, {
"AttributeId": "attribute:Derived.Product availability.Dinner at 5-star restaurant",
"Value": "true"
}, {
"AttributeId": "attribute:Derived.Product availability.Expensive laptop",
"Value": "false"
}, {
"AttributeId": "payload",
"Value": "2020-03-17T16:21:20.175132-05:00"
}]
}]
}]
}