Policy Evaluation Model

Summary

The Policy Evaluation Model defines how Keymate processes permission requests and produces authorization decisions. When a permission check arrives, the platform evaluates each requested Resource and Scope combination against configured policies and returns a granular result — GRANT, DENY, or ERROR — for every combination. The overall decision follows a strict all-or-nothing rule: the request is granted only if every requested resource-scope pair is individually granted.

Why It Exists

Authorization decisions must be predictable, consistent, and auditable. Without a well-defined evaluation model:

• Applications would need to interpret raw policy outcomes on their own, leading to inconsistent enforcement across services.
• Partial grants (some resources allowed, others denied) would go undetected, creating security gaps.
• There would be no standardized contract between the authorization authority and the services that consume its decisions.

The Policy Evaluation Model establishes a single, deterministic evaluation contract. Every permission request follows the same path, applies the same decision rules, and produces the same structured result — regardless of which service initiated the check.

Where It Fits in Keymate

The Policy Evaluation Model sits at the core of Keymate's runtime authorization flow. It is the logic that the Authorization Decision Provider executes when it receives a permission evaluation request from the Access Gateway.

Upstream: The Access Gateway validates the token, resolves the target resource server, and delegates the permission decision.

Evaluation: The Authorization Decision Provider applies the Policy Evaluation Model — matching requested resources and scopes to configured policies in Keycloak's authorization services.

Downstream: The structured GRANT or DENY result flows back to the Access Gateway, which enforces the decision.

Boundaries

What the Policy Evaluation Model covers:

• Evaluating explicit resource-scope combinations against policies
• Retrieving a complete permission profile for a user in a single query
• Incorporating contextual attributes into policy decisions
• Producing per-resource, per-scope granular results
• Applying the all-or-nothing decision rule for explicit requests

What the Policy Evaluation Model does not cover:

• Token validation or exchange — handled by the Access Gateway
• Decision caching — handled by the Version-Aware Decision Cache
• Policy authoring or management — handled through Keycloak's authorization configuration
• Request routing or traffic proxying

How It Works

Evaluation Modes

The Policy Evaluation Model supports two distinct evaluation modes, each suited to a different use case.

Explicit Resource Evaluation

The caller specifies one or more resource-scope combinations to evaluate. The platform evaluates each combination against configured policies and returns a per-combination result.

The overall decision follows a strict rule: the status is GRANT only if all requested resource-scope combinations are granted. If any single combination is denied, the overall status is DENY. This all-or-nothing approach prevents partial authorization — the caller either has full access to everything it requested, or the request is denied.

Full Permission Profile

The caller requests a complete permission profile for the authenticated user. The platform evaluates all configured resources on the target resource server and returns every resource-scope combination that the user has access to.

In this mode, the result contains only granted permissions. This is useful for scenarios like UI rendering, where the application needs to know the full set of granted permissions upfront to determine which features to display.

Context-Aware Evaluation

Permission requests can include contextual attributes that policies use during evaluation. These attributes enable Attribute-Based Access Control (ABAC) scenarios where decisions depend on runtime context — such as the HTTP method, request path, or custom business attributes.

Context attributes are key-value pairs passed alongside the resource-scope request. Keycloak's policy engine makes these attributes available to all configured policies during evaluation, allowing conditions like "grant access only if the HTTP method is GET" or "deny access if the request originates from outside the allowed network."

Role Enrichment

Before policy evaluation begins, the platform enriches the identity context with the user's current role assignments — both realm-level and client-level roles. This ensures that Role-Based Access Control (RBAC) policies evaluate against the complete set of roles, even if the token does not contain all role claims.

Decision Outcomes

Every evaluation produces one of three result types:

Result	Meaning
GRANT	All requested resource-scope combinations are permitted
DENY	One or more requested resource-scope combinations are not permitted
ERROR	The evaluation could not complete (invalid token, unknown client, server error)

Each individual resource-scope combination in the response also carries its own status (GRANT, DENY, or ERROR), giving the caller full visibility into which specific permissions were granted or denied.

Diagram

Example Scenario

Scenario

A frontend application checks whether the current user can both view and edit employee data. The permission request includes two scope checks on the same resource. The user has a policy that grants view access but not edit access.

Input

• Actor: Authenticated user (user@example.com) with a valid token
• Resource: employee-data with scopes can-view and can-edit
• Action: Permission evaluation via the Authorization Decision Provider
• Context: clientId: acme-portal, resourceClientId: acme-api

Expected Outcome

• Overall Decision: DENY
• Why: The per-resource, per-scope results show employee-data:can-view as GRANT and employee-data:can-edit as DENY. Because the all-or-nothing rule applies to explicit resource evaluation, the overall status is DENY. The application receives the granular breakdown and can determine that view access is available even though the full request was denied.

Common Misunderstandings

• "A DENY overall means everything was denied." — No. The overall DENY means at least one resource-scope combination was not granted. The per-resource, per-scope breakdown in the response reveals exactly which combinations were granted and which were denied.
• "Requesting a full permission profile bypasses policy checks." — No. A full permission profile request runs the same policy evaluation against every configured resource. The difference is in what gets returned: only granted permissions appear in the result.
• "Context attributes override policy decisions." — No. Context attributes are inputs to the policy evaluation. They provide additional data points that policies can use in their conditions, but they do not override or bypass policy logic.

warning

The overall decision for explicit resource evaluation is GRANT only when every requested resource-scope combination is individually granted. Design your permission requests accordingly — request only the scopes your application needs for the current operation.

Design Notes / Best Practices

• Request specific resources and scopes for transactional authorization checks. Use the full permission profile mode only when you need a complete view of granted permissions (e.g., building a navigation menu or feature visibility map).
• Leverage the per-resource, per-scope breakdown in DENY responses to provide meaningful feedback to users — such as showing which specific actions they lack permission for.
• Pass contextual attributes when your policies use ABAC conditions. This enables dynamic authorization decisions based on request context without requiring separate policy configurations for each scenario.

tip

When the Access Gateway's decision cache is active, GRANT decisions are cached. Subsequent identical permission checks are served from cache without reaching the Authorization Decision Provider, reducing latency for high-traffic authorization scenarios.

Related Docs

Authorization Decision Provider

The centralized authorization decision authority that executes the Policy Evaluation Model.

Enforcement Pipeline

Request processing stages that lead to policy evaluation.

Version-Aware Decision Cache

Subject-based caching that reduces repeated policy evaluations.

Policy Model

How policies are authored, structured, and governed in Keymate.