Feature Proposal: Support for custom deny reason in the policy provider evaluation #45817

akib1689 · 2026-01-28T09:29:03Z

akib1689
Jan 28, 2026

Summary

When implementing custom PolicyProvider for Keycloak's Authorization Services, there is currently no way to communicate why a permission was denied back to the Policy Enforcement Point (PEP). The error response is always hardcoded to "not_authorized", which makes it impossible for clients to distinguish between different denial reasons.

Use case

I'm developing authorization policy that fails on different case, and depending upon the case, I need to take action in the policy enforcement point. Currently when any of the conditions fail, the PEP receives the same generic response:

{
    "error": "access_denied",
    "error_description": "not_authorized"
}

This forces the client application to make additional API calls to determine the actual reason.

Current Behavior

The Evaluation interface provides binary outcomes

public interface Evaluation {
    void grant();
    void deny();  // No way to specify reason
}

And in AuthorizationTokenService, The error description is hardcoded:

else {
    CorsErrorResponseException notAuthorizedException = new CorsErrorResponseException(request.getCors(), OAuthErrorException.ACCESS_DENIED, "not_authorized", Status.FORBIDDEN);
    fireErrorEvent(event, Errors.ACCESS_DENIED, notAuthorizedException);
    throw notAuthorizedException;
}

Proposed solution

Add optional deny(String reason) method to the Evaluation Interface with backward compatibility:

public interface Evaluation {
    void grant();
    void deny();
    
    // NEW: Deny with custom reason
    default void deny(String reason) {
        deny();
        setDenyReason(reason);
    }
    
    default void setDenyReason(String reason) {
        // Default no-op for backward compatibility
    }
    
    default String getDenyReason() {
        return null;
    }
}

Propagate this reason to the error response in the AuthorizationTokenService

Expected outcome

With this feature custom policy providers could do:

@Override
public void evaluate(Evaluation evaluation) {
    if (case1Failed) {
        evaluation.deny("case_1_failed");
        return;
    }
    if (case2Failed) {
        evaluation.deny("case_2_failed");
        return;
    }
    evaluation.grant();
}

And PEP would receive:

{
    "error": "access_denied",
    "error_description": "case_1_failed"
}

Backward Compatibility

All new methods should have a default implementations
Existing PolicyProvider implementations continue to work unchanged
deny() without arguments still works, defaulting to "not_authorized"

Considered alternatives

Using addClaim() on permission - This only works for granted permissions, not denials.
Throwing Exceptions - causes 500 internal server error instead of proper 403
Separate API endpoints - Requires additional network calls

I'm happy to contribute the implementation if this proposal is accepted.

tawfff · 2026-09-15T06:06:53Z

tawfff
Sep 15, 2026

Disclosure up front: I work at Instruxi on Enforcer, which is an authorization service that returns a reason alongside allow/deny. Not pitching a switch, just offering what bit us building the same feature, because two of these were not obvious until we shipped them.

The reason the PEP sees and the reason the log keeps are different objects.

A detailed deny sent back to the caller is an oracle. "Denied: not in Finance approvers" tells whoever asked that the group exists, that it gates this action, and that membership is the lever. Enough denials with enough detail maps out your policy. That is fine for an internal PEP you own and a real problem for anything an untrusted client can hammer.

What worked for us: a coarse, stable, machine-readable slug goes back to the PEP, the full reason goes to the audit record regardless, and the deployment decides whether an optional detail field travels with the slug. Concretely we return { "allow": false, "reason": "not_owner" }, not prose. The PEP branches on the slug; a human reads the log.

If Evaluation.deny(String reason) lands as free-form text, most people will put prose in it and it will reach clients. A constrained code, or at minimum a documented convention plus a config switch for whether it is forwarded, would age better.

The second one, which surprised us: when you have several possible deny reasons, the order you evaluate them in is part of the feature.

We had a deny that correctly reported a tenancy mismatch. It was true and it was useless, because the real cause was that the request had not said which tenant or owner the resource belonged to, so nothing could match and the tenancy comparison was the first condition that happened to be literally true. People went hunting a tenancy bug that did not exist. We reordered so the more specific "you under-described the request" reason is checked before the generic one, and only ever renames a denial that was already going to happen.

So a reason is not just a string attached to a deny(). It is a ladder, and a wrong-but-technically-true reason is worse than not_authorized, because it sends people somewhere confidently. Whatever shape this lands in, it is worth making it easy for a policy author to express "check this explanation before that one".

0 replies

Navigation Menu

Repository navigation

Feature Proposal: Support for custom deny reason in the policy provider evaluation #45817

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Feature Proposal: Support for custom deny reason in the policy provider evaluation #45817

Uh oh!

akib1689 Jan 28, 2026

Summary

Use case

Current Behavior

Proposed solution

Expected outcome

Backward Compatibility

Considered alternatives

Replies: 1 comment

Uh oh!

tawfff Sep 15, 2026

akib1689
Jan 28, 2026

tawfff
Sep 15, 2026