Policy queries
Policy queries enable you to drive user interfaces and proactively evaluate authorization policy behavior through dynamic decision requests containing unbounded and multivalued attributes.
Why use policy queries?
Authorization can be defined as a relationship between three core attributes:
-
Subject
-
Action
-
Resource
In PingAuthorize, if a decision request including a subject, action, and resource produces a PERMIT response, that subject is authorized to perform that action on that resource. Policy administrators specify which users (subjects) can access system resources and which actions they can perform on those resources, given a range of dynamic, contextual data points evaluated at runtime. This data can include user roles, identity attributes, organization rules and policies, or a combination of them.
A typical decision request forwarded to the JSON PDP API in PingAuthorize includes a single value for subject, action, and resource. The Policy Decision Service uses these explicitly provided values, together with your access control policies, to compute a PERMIT or DENY decision result. For example, to determine if user ID123 is authorized to delete the configuration resource:
{
"domain": "",
"service": "",
"action": "",
"identityProvider": "",
"attributes": {
"User": "ID123",
"Account": "configuration",
"Action": "DELETE",
"RegionInfo": "EU",
"RequestType": "WEB",
}
}In this example, the User, Action, and Account attributes represent the subject, action, and resource. The decision engine evaluates the request against your dynamic access control logic to determine if this particular subject can perform this particular action on this particular resource. However, instead of limiting each authorization attribute to a single, fixed value, you might want to ask open-ended and multivalued questions, such as:
-
Which accounts (resource) can this customer (subject) withdraw (action) funds from? (Open-ended)
-
Can John (subject) add funds to or transfer from (actions) a business checking account (resource)? (Multivalued)
In each of these examples, at least one of the authorization attributes is a query attribute. A query attribute is an attribute that either has multiple values or is unbounded in the decision request .
Decision requests with query attributes check which combinations of subject, action, and resource produce a PERMIT decision result in a specified context. Open-ended and multivalued requests increase decision efficiency by eliminating the need for batch requests to answer such questions as "Which accounts can this user access?" or "Can this user read or delete this resource?"
Policy queries enable these more flexible decision requests with a new governance-engine/query endpoint exposed by the JSON PDP API. Using this endpoint, clients of the API can obtain information about what actions users are authorized to perform. For example, applications could enable or disable navigation items or display lists limited to entities that the customer is authorized to access.
How policy queries work
The new Policy Query API request format introduces a query array containing the following elements:
-
attribute: The full name of the query attribute. -
values: An optional array defining the values of the query attribute. If more than one value is included in this array, the query attribute is considered multivalued. If the query attribute values will not be provided in the query decision request, this array is not required.
|
The
For example, if you have already included one unbounded and one multivalued attribute in the array, the last attribute must have a single value. |
Including a single-valued attribute in the query array returns that attribute and its corresponding value in the Policy Query API response, adding further context to the query results.
The following table outlines the supported Policy Query API request formats:
| Number of attributes inqueryarray | Supported query attribute combinations |
|---|---|
Three attributes |
|
Two attributes |
|
One attribute |
|
In addition to the query array, query decision requests feature a context field that provides additional request context in the form of non-query attributes. This field resembles the format of a typical JSON PDP API request. The format of Policy Query API requests and responses is explored in detail in the next section.
Query requests and responses
The following query decision request includes an unbounded User attribute to ask which users can delete the configuration resource:
{
"query": [
{
"attribute": "User"
}
]
"context": {
"domain": "",
"service": "",
"identityProvider":"",
"action":"",
"attributes": {
"action": "delete",
"resource": "configuration"
}
}
}The response to this query decision request returns each user that produced a PERMIT decision result:
{
"requestId": "8236be35-ec9e-40f1-a79a-80890041f4b0",
"timeStamp": "2023-11-14T03:21:47.734842Z",
"elapsedTime": 20,
"results": [
{
"attribute": "User",
"value": "{\"id\": 23, \"name\":\"Joe\"}",
"decision": "PERMIT"
},
{
"attribute": "User",
"value": "{\"id\": 24, \"name":\"Bob\"}",
"decision": "PERMIT"
}
]
}The following query decision request includes an unbounded action attribute to ask which actions the specified user can perform on the configuration resource:
{
"query": [
{
"attribute": "action"
}
]
"context": {
"domain": "",
"service": "",
"identityProvider":"",
"action":"",
"attributes": {
"User": "{\"id\": 23, \"name\":\"Joe\"}",
"resource": "configuration"
}
}
}The response to this query decision request returns each action that produced a PERMIT decision result:
{
"requestId": "8245be35-ec9e-40f1-a79a-80890041f4b0",
"timeStamp": "2023-11-14T03:21:47.734842Z",
"elapsedTime": 22,
"results": [
{
"attribute": "action",
"value": "delete",
"decision": "PERMIT"
}
]
}For such open-ended query decision requests, the decision engine must retrieve all possible values of the unbounded query attribute from a source collection to evaluate your policies with. This collection can resolve from the attribute itself, the decision request, or an external service. You must specify this source collection when enabling query settings for the query attribute.
The following multivalued query decision request asks whether either of two specified users can delete or update the configuration resource:
{
"query": [
{
"attribute": "User",
"values": ["{\"id\": 23, \"name\":\"Joe\"}", "{\"id\": 24, \"name":\"Bob\"}"]
},
{
"attribute": "action",
"values": ["delete", "update"]
}
]
"context": {
"domain": "",
"service": "",
"identityProvider":"",
"action":"",
"attributes": {
"resource": "configuration"
}
}
}The response to this query decision request returns each of the specified users that produced a PERMIT decision result on either of the delete or update actions:
{
"requestId": "c6b1be8a-848d-44c3-b3d2-5b0f48c74cbf",
"timeStamp": "2024-05-24T21:22:39.646980Z",
"elapsedTime": 31,
"results": [
{
"attribute": "User",
"value": "{\"id\": 23, \"name\":\"Joe\"}",
"results": [
{
"attribute": "action",
"value": "delete",
"decision": "PERMIT"
}
]
},
{
"attribute": "User",
"value": "{\"id\": 24, \"name":\"Bob\"}",
"results": [
{
"attribute": "action",
"value": "update",
"decision": "PERMIT"
},
{
"attribute": "action",
"value": "delete",
"decision": "PERMIT"
}
]
}
]
}You don’t have to enable query settings for query attributes with multiple values or a single value unless you plan on making those attributes unbounded in some requests.
|
Both the |
The following query decision request brings unbounded and multivalued query attributes together, asking which users can update or delete the configuration resource:
{
"query": [
{
"attribute": "User"
},
{
"attribute": "action",
"values": ["delete", "update"]
}
]
"context": {
"domain": "",
"service": "",
"identityProvider":"",
"action":"",
"attributes": {
"resource": "configuration"
}
}
}The response to this query decision request returns each user that produced a PERMIT decision result on either of the delete or update actions, or a DENY decision result with statements:
{
"requestId": "dbb30a53-08b0-413e-b253-f97f613266ee",
"timeStamp": "2024-05-24T21:33:51.556673Z",
"elapsedTime": 249,
"results": [
{
"attribute": "User",
"value": "{\"id\": 23, \"name\":\"Joe\"}",
"results": [
{
"attribute": "action",
"value": "delete",
"decision": "PERMIT"
}
]
},
{
"attribute": "User",
"value": "{\"id\": 24, \"name":\"Bob\"}",
"results": [
{
"attribute": "action",
"value": "update",
"decision": "PERMIT"
},
{
"attribute": "action",
"value": "delete",
"decision": "PERMIT"
}
]
},
{
"attribute": "User",
"value": "{\"id\": 25, \"name":\"Sarah\"}",
"results": [
{
"attribute": "action",
"value": "update",
"decision": "PERMIT"
},
{
"attribute": "action",
"value": "delete",
"decision": "DENY",
"statements": [
{
"id": "f5456746-6c55-4744-97bc-ecf3a679d026",
"name": "additional-permission-needed",
"code": "additional-permission-needed",
"payload": "",
"obligatory": false,
"fulfilled": false,
"attributes": {}
}
]
}
]
}
]
}By default, the Policy Query API returns all query attribute values that produce one of two decision results:
-
Permit -
Denywith statements
If you only want attribute values that produce a Permit decision included in the response, you can add the x-respond-with header to your query decision request and assign it a value of PERMIT. Alternatively, you can configure the endpoint response in the administrative console:
-
In the Authorization and Policies section, click Policy Decision Service.
-
In the Policy Query Configuration section, select the response granularity in the Query Response View list.
Learn more about filtering Policy Query API responses in Enabling query settings.
Logging
Policy query information is written to the following logs:
policy-query.log-
Similar to the Policy Decision Logger, this file-based log publisher records responses from the Policy Query API.
debug.log-
The Policy Editor application log. You can use it to debug any application-related issues. To control whether query decision requests and responses are included in this log, in the admin console:
-
In the Logging, Monitoring, and Notifications section, click Log Publishers.
-
Click Debug Trace Logger.
-
In the Log Messages to Include section, on the Debug Message Type row, select policy-query-request-and-response.
-