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

The query array has the following limitations:

  • At most one attribute can be included without values (unbounded).
  • At most two attributes can be multivalued.
  • At most three attributes can be included in the array, but not all three can be multivalued or unbounded.

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 in query array Supported query attribute combinations

Three attributes

  1. Unbounded/multivalued/single-valued
  2. Multivalued
  3. Single-valued
  1. Unbounded/multivalued/single-valued
  2. Single-valued
  3. Single-valued

Two attributes

  1. Multivalued
  2. Multivalued
  1. Multivalued
  2. Single-valued
  1. Single-valued
  2. Single-valued
  1. Unbounded/multivalued
  2. Multivalued/single-valued

One attribute

  1. Unbounded/multivalued/single-valued

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.

Note:

Both the attribute and values terms in the query array are case-sensitive.

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:

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:

  1. In the Authorization and Policies section, click Policy Decision Service.
  2. In the Policy Query Configuration section, select the response granularity in the Query Response View list.
Screen capture of the Policy Query Configuration section of the Admin Console with "permit" selected 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:
  1. In the Logging, Monitoring, and Notificationssection, click Log Publishers.
  2. Click Debug Trace Logger.
  3. In the Log Messages to Include section, on the Debug Message Typerow, select policy-query-request-and-response.
Screen capture of policy-query-request-and-response option selected in the Log Messages to Include section of the Debug Trace Log Publisher