Working with Deny Reason

About Deny Reason

The includeDenyReason parameter is an optional Runtime request parameter sent in the Permit Deny API. When sent in the request, the PDP response provides detailed Deny Reason Codes, offering visibility into why an authorization request resulted in a denied decision.

This capability is particularly useful for troubleshooting, as well as for onboarding new Applications or Policies, by helping identify which Policy conditions or evaluation steps led to the denial.

Applications can also display these Deny Reason Codes in their responses to clearly communicate to users why access was not granted. For example, a user may be denied access if they do not meet policy conditions such as permitted working hours.

When the includeDenyReason flag is enabled, certain Deny Reason Codes require additional checks during the evaluation flow. These additional checks might trigger additional queries to external data sources through PIP integrations, which can result in extra or alternative data fetches.

In some cases, the additional queries might not be possible or may impact the evaluation flow due to limitations in the integrated Data Sources. This can affect the overall PDP evaluation and final decision result.

Therefore, it is strongly recommended to evaluate data integration constraints before enabling the includeDenyReason parameter, due to the following considerations:

• Additional queries may be triggered against external data sources through the PIP.
• The data source may need to support retrieving assets directly by the Asset ID.

These limitations are more common with REST-based data sources, where APIs often require additional filtering parameters and may not support requests using only an AssetID. In some cases, the REST service may not expose an endpoint that allows fetching data solely by AssetID, which can impact the authorization flow when deny reasons are evaluated.

For example, when distinguishing between PID0004 – Asset not found and PID0005 – The Policy was evaluated and the Asset was denied, PDP is required to perform an additional query to check for the existence of the Asset. Depending on how your PIP integration handles queries, this additional lookup may impact the overall flow. This query determines either that:

• The Asset does not exist (PID0004)
• The Asset exists, but was denied by Policy evaluation (PID0005)

Response structure

Deny-Reason codes within the response are returned for every Asset Action permutation. A basic response returns all the Deny-Reason code/s relevant to the request.

Example:
Basic Response Structure (includeDetails set to false, includeDenyReason set to true)

{
  "result": "DENY",
  "reason": ["PID003","PID004"]
}

A breakdown for every code per Asset Action permutation is returned in a detailed response.

Example:
Detailed Response Structure (includeDetails set to true, includeDenyReason set to true)

{
    "result": "DENY",
    "reason": [
        "PID003",
        "PID004"
    ],
    "response": [
        {
            "allowed": [],
            "denied": [
                {
                    "path": "/accounts/transfer",
                    "Action": "Approve",
                    "template": "Accounts",
                    "reason": "PID003"
                },
                {
                    "path": "/accounts/transfer",
                    "Action": "Edit",
                    "template": "Accounts",
                    "reason": "PID004"
                }
            ],
            "not_applicable": []
        }
    ]
}

PlainID PDP Deny Reason Codes

Deny Reason returns in a form of code to make the integration with consuming Applications easier.

For each Asset Action permutation sent in the Authorization request, an appropriate error code is returned.
It is important to ensure that the Asset Type setup is correct, all relevant Actions are available, and the values match the Authorization request sent.
Note: Action value is case sensitive.

The following table provides information for each Deny Code scenario: