Troubleshooting policy queries

The following resources can help you solve issues with policy query requests and responses.

Configuring query response granularity

A query response includes a set of decisions. Each decision is executed against a possible combination of request attributes. By default, query responses return two types of decisions:

PERMIT
DENY with statements attached

Adjust the granularity of query responses by configuring the query response view:

In the administrative console, go to Authorization and Policies and click Policy Decision Service.
In the Policy Query Configuration section, select the response granularity in the Query Response View list.

The following table describes the behavior of each available query response view:

Response view Description

Response view	Description
`permit`	Only includes `PERMIT` decisions in the query response.
`permit-and-deny-with-statement`	Includes `PERMIT` decisions and `DENY` decisions with statements attached in the query response.
`unfiltered`	Includes all decisions in the query response, regardless of the outcome or the presence of statements. You can use this view can help diagnose unexpected decision outcomes for specific combinations of attributes.

permit

Only includes PERMIT decisions in the query response.

permit-and-deny-with-statement

Includes PERMIT decisions and DENY decisions with statements attached in the query response.

unfiltered

Includes all decisions in the query response, regardless of the outcome or the presence of statements.

You can use this view can help diagnose unexpected decision outcomes for specific combinations of attributes.

Alternatively, you can add the x-respond-with header to your query requests and assign it one of the following values:

permit
permitAndDenyWithStatement
unfiltered

The configured query response view will apply to responses in both embedded and external policy decision point (PDP) mode.

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 query responses in embedded PDP mode.

debug-trace.log

Records detailed information about the processing of HTTP requests and responses in embedded PDP mode. To include query requests and responses in debug-trace.log:

In the administrative console, go to Logging, Monitoring, and Notifications and 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.

query-audit.log

Records query responses in external PDP mode.

Enabling debug logging in embedded PDP mode

Enable debug logging to provide detailed information when query requests produce errors or unexpected results. In addition to logging the full query request and response, debug logging records details about the resolution, processing, and policy dependencies of each attribute included in the query request. This level of detail can be necessary to troubleshoot the individual decision requests that make up a single query request.

Debug logging could log sensitive and personally identifiable information (PII). Enable debug logging only during troubleshooting and disable it afterward.

In debug mode, a policy query audit log entry includes the following fields:

requestId: A unique identifier the query request.
permutationId: A unique identifier for a query permutation.

A query permutation is a combination of query attributes used for a decision in the final query response. Use this identifier and the requestId for increased visibility of query request information across your logging system. For example, a logged call to an external information point would include identifiers for the request and permutation that invoked that service.
permutation: A query permutation as an array of JSON objects containing each query attribute and its value.
response: The complete, high-verbosity response for a query permutation’s associated decision, including expanded errors and other helpful information.

This field includes details about resolution, processing, and policy dependencies of each attribute involved in the permutation’s corresponding decision, along with details about any external service used in that decision.

These fields could change in future PingAuthorize releases.

The following is an example of a query request body and its associated policy query audit log message. The response field is shortened for the sake of brevity.

{
    "query": [
        {
            "attribute": "User"
        },
        {
            "attribute": "Action",
            "values": ["view"]
        },
        {
            "attribute": "Resource",
            "values": ["account"]
        }
    ]
}

[2024-08-26 16:28:19,173] {"requestId": "20f9adb8-f07a-4dbe-a7e0-6734ab7e12f7", "permutationId": "7cffcc00-eab9-4992-be24-15c554e9fc70","permutation": [{"attribute":"User","value":"{\"id\":1}"},{"attribute":"Action","value":"view"},{"attribute":"Resource","value":"account"}],"response":{"id":"7cffcc00-eab9-4992-be2f-15c554e9fc70","...":"..."}},
{"requestId": "20f9adb8-f07a-4dbe-a7e0-6734ab7e12f7", "permutationId": "3769e5e4-4d35-4385-b15f-299bd0b34d9a", "permutation": [{"attribute":"User", "value":"{\"id\":2}"}, {"attribute":"Action","value":"view"},{"attribute":"Resource","value":"account"}], "response":{"id":"e9118333-eb00-48bc-b25e-2ab9a8deecc3","...":"..."},{"requestId": "20f9adb8-f07a-4dbe-a7e0-6734ab7e12f7", "permutationId": "2784e5e4-4d35-4385-b15f-299bd0b12d9a", "permutation": [{"attribute":"User", "value":"{\"id\":3}"}, {"attribute":"Action","value":"view"},{"attribute":"Resource","value":"account"}], "response":{"id":"e9118333-eb00-48bc-b25e-2ab9a8deecc3","...":"..."}}

In this example, each possible combination of the query attributes is represented as a distinct permutation with its own identifier and decision response details. These permutations are correlated by a common requestId.

You can enable debug logging for the policy query audit log in the administrative console or with dsconfig.

By default, the policy query audit log is located at PingAuthorize/logs/policy-query.log.

Administrative console
dsconfig

Configuring policy query audit logging in the administrative console

Steps

Go to Logging, Monitoring, and Notifications and click Log Publishers.
Click Policy Query Logger.
Select the Include Query Permutations checkbox.
Click Save to PingAuthorize Server Cluster.

Configuring policy query audit logging with dsconfig

Steps

Enable the file-based Policy Query Logger.

dsconfig set-log-publisher-prop
  --publisher-name "Policy Query Logger"
  --set enabled:true

Use the dsconfig set-log-publisher-prop command with the following arguments:

dsconfig set-log-publisher-prop
  --publisher-name "Policy Query Logger"
  --set include-query-permutations:true

You can also enable policy query audit log debugging for policy development and testing in the Policy Editor. Learn more in Configuring policy query debug logging in the Policy Editor.

Visualizing policy query decisions

As part of the policy development and debugging process, you can examine recent decisions returned in a query response.

About this task

When you develop and test policies, you can examine the decision flow and other details about recent decisions to make sure the decision engine is evaluating policies according to your expectations.

Steps

In the policy-query.log file, copy the response field for the individual query permutation for which you want to visualize the corresponding decision.

"response":{"id":"38be8a7e-b552-4fd8-9311-4b742dc71280","deploymentPackageId":"38288f2d-f7ca-4c1c-ada4-0d6ef878de38","timestamp":"2024-09-09T14:44:19.687068Z","elapsedTime":42514,"request":{"domain":"","service":"","identityProvider":"","action":"","attributes":{"User":"{\"userID\":789,\"role\":\"financial advisor\",\"name\":\"Jim Jones\"}","Action":"view","BankAccount.resource":"balance"}},"externallyResolvedAttributes":{},"decision":"DENY","authorised":false,"statements":[{"id":"1290c587-bfdc-434b-b181-43f542207235","name":"Denial reason","code":"denied-reason","payload":"Example: { \"status\": 403, \"message\": \"error_code\", \"detail\":\"Role does not equal teller or customer service rep\"}","obligatory":false,"fulfilled":false,"attributes":{}}],"status":{"code":"OKAY","messages":[],"errors":[]},"attributes":{...},"services":{...},"decisionTree":{...},"evaluationLog":[{...},{...}]}

In the Policy Editor, go to Policies > Decision Visualiser.
In the Paste Logs field, paste the log data you copied in step 1.
Click Visualise.

On the Visualisation tab, examine the decision flow to make sure decisions are evaluated according to your expectations.
Click a box in the flow to show more details.

This example represents a rule that denies requests to view account balances if the user’s role is not teller or customer service rep and permits otherwise. The decision evaluated as deny and took 0.818 milliseconds. Additionally, there is a denied-reason statement attached to the decision with additional context for the denial.
Click the other tabs for additional details:
- Request tab: Shows the JSON request sent to the decision engine, allowing you to confirm that the expected information was sent.
- Response tab: Shows the reponse for the individual permutation’s decision.
  
  This tab includes detailed information about the attributes and policy elements used to produce the decision response.
- Output tab: Shows the time taken to evaluate each policy set, policy, and rule used in the final decision.
- Attributes tab: Shows resolution, processing, and policy dependency details for each attribute used in the decision.
- Services tab: Shows details about the services used in the decision.