Policy queries

Policy queries enable you to dynamically determine user entitlements by posing open-ended authorization questions.

Why use policy queries?

Authorization can be represented as a relationship between a subject, action, and a resource. For example, "Is John (subject) authorized to transfer (action) money from this savings account (resource)?"

Instead of executing a batch request to obtain a list of accounts or actions a user is authorized to access or perform, policy queries enable you to construct a single decision request that checks which combinations of subject, action, and resource produce a PERMIT decision in a specified context. This enables your applications to more efficiently retrieve and enforce decisions for real-time events, such as generating dynamic web content.

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, the following decision request asks, "Is John Smith (subject) authorized to edit (action) the account (resource)?":

{
    "domain": "",
    "service": "",
    "action": "",
    "identityProvider": "",
    "attributes": {
    "Subject": "John Smith",
    "Resource": "account",
    "Action": "edit",
    "RegionInfo": "EU",
    "RequestType": "WEB"
    }
}

However, instead of limiting each authorization attribute to a single, fixed value, you might want to ask authorization questions such as:

Which accounts can this customer withdraw funds from?
Which users can update account preferences?

For example, the following decision request sent to the governance-engine/query endpoint asks, "Which users are authorized to edit the account?":

{
  "query": [
    {
      "attribute": "Subject"
    },
    {
      "attribute": "Action",
      "values": ["edit"]
    },
    {
      "attribute": "Resource",
      "values": ["account"]
    }
  ]
}

The following section walks through the necessary steps to successfully send such a request.

Querying entitlements based on user role

Suppose you want to implement access controls in your banking application around users' interaction with accounts, based on those users' organizational role.

The following diagram illustrates the process of using policy queries to enforce such access controls, from request to response:

A diagram illustrating the policy query flow from request to response.

The following rule checks whether the user requesting to edit an account has the role of manager. If the user is assigned this role, the decision engine returns a PERMIT, and denies otherwise.

Screen capture of a rule targeting requests to edit an account. The rule permits if the Subject’s role equals 'manager', and denies otherwise.

To dynamically populate values for a request attribute with an external service call, rather than providing a static value in the request, enable query settings for that attribute. In this example, to query which users can edit the account, enable query settings for the Subject attribute.

Screen capture of the Subject attribute with query settings enabled. The Subject.listOfUsers attribute is selected as the source.

When enabling query settings for a request attribute, you must specify a Source attribute. This attribute provides a collection of possible attribute values for the decision engine to check your policies against. In this example, the Subject.listOfUsers attribute resolves from a call to an external information point made by UsersService and provides a list of possible Subject values.

Screen capture of the Subject.listOfUsers attribute. The attribut is defined with a UsersService service resolver.

Screen capture of the UsersService service. The service is of type HTTP and is defined with an example API URL.

Learn more about the Response Value query setting in Enabling query settings.

Based on the request and policy logic, the JSON PDP API returns the following:

{
   "requestId": "f1c536bd-a5e0-4b14-80f8-25a71d45774c",
   "timeStamp": "2024-08-16T14:32:25.417092Z",
   "deploymentPackageId": "a2435f66-3669-4d2c-960c-d01dc9c39bfa",
   "elapsedTime": 60,
   "results": [
       {
           "attribute": "Subject",
           "value": "John Smith",
           "results": [
               {
                   "attribute": "Action",
                   "value": "edit",
                   "results": [
                       {
                          "attribute": "Resource",
                          "value": "account",
                          "decision": "PERMIT"
                       }
                    ]
               }
          ]
       },
       {
           "attribute": "Subject",
           "value": "Sally White",
           "results": [
               {
                   "attribute": "Action",
                   "value": "edit",
                   "results": [
                       {
                           "attribute": "Resource",
                           "value": "account",
                           "decision": "PERMIT"
                       }
                   ]
                }
           ]
       }
   ]
}

The top-level results array contains each subject that produced a PERMIT decision, and each of the subjects contains the action and resource that the subject is authorized to perform and access.

Learn more about the structure of query requests and responses in Query requests.