Overview

Summary

The Keymate Authorization Decision Provider is the centralized authorization decision authority of the Keymate platform. It evaluates fine-grained permission checks — determining whether a given subject has access to specific resources and scopes. Running as a Keycloak extension, it leverages Keycloak's built-in authorization services, policies, and decision strategies to produce GRANT or DENY outcomes.

The Access Gateway delegates all permission evaluation requests to this component. No other component in the Keymate platform makes authorization decisions — this separation ensures a single source of truth for all permission outcomes.

Why It Exists

In an enterprise authorization platform, the decision authority must be centralized to ensure consistency. Without a single decision point:

• Different services could evaluate the same permission differently, leading to inconsistent access control.
• Policy changes would need to propagate to every service individually.
• There would be no single audit trail for authorization decisions.

The Keymate Authorization Decision Provider solves these problems by centralizing all permission evaluation within Keycloak, where resources, scopes, and policies are already defined and managed.

Where It Fits in Keymate

The Authorization Decision Provider sits downstream of the Access Gateway. The gateway handles request validation, token mediation, and caching — then delegates the actual permission decision to this component.

Upstream: The Access Gateway sends permission evaluation requests after completing token validation and access rule processing.

Downstream: Keycloak's built-in authorization services evaluate the configured policies (RBAC, ABAC, resource-based, scope-based) and return the decision.

Boundaries

What the Authorization Decision Provider does:

• Evaluates permission checks for specific resources and scopes
• Returns GRANT or DENY decisions with per-resource, per-scope granularity
• Lists all accessible resources and scopes for a given user in a single query
• Retrieves organization context (tenants and departments) for authenticated users
• Integrates with Keycloak's policy evaluation and decision strategies

What the Authorization Decision Provider does not do:

• Validate or exchange tokens (this is the Access Gateway's responsibility)
• Cache decisions (caching is handled by the Access Gateway's decision cache)
• Define or manage policies (policies are configured in Keycloak's authorization settings)
• Route or proxy application traffic

How It Works

The Authorization Decision Provider exposes two REST API endpoints through Keycloak's realm resource model. All requests require a valid Bearer token.

Permission Evaluation

When the Access Gateway receives a permission check request, it delegates the evaluation to the Authorization Decision Provider's /authorize endpoint. The provider evaluates each requested resource and scope combination against Keycloak's configured policies and returns a granular 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.

Organization Context

The /get-organizations endpoint retrieves the authenticated user's organization assignment — including tenant and department hierarchy. This supports multi-tenant authorization scenarios where decisions depend on organizational context.

List All Permissions

The Authorization Decision Provider supports retrieving a complete permission profile for a user in a single call. This returns all resources and scopes the authenticated user has access to — useful for scenarios such as UI rendering where the application needs to know the full set of granted permissions upfront.

API Endpoints

Endpoint	Method	Purpose
/realms/{realm}/keymate-permission-gateway/authorize	POST	Evaluate permissions for requested resources and scopes
/realms/{realm}/keymate-permission-gateway/get-organizations	POST	Retrieve the authenticated user's organization context

Permission Evaluation Request

Field	Type	Required	Description
clientId	string	Yes	Client identifier making the request
resourceClientId	string	No	Client owning the resources (defaults to clientId)
resources	array	Yes	Resources and scopes to evaluate
resources[].name	string	Yes	Resource identifier
resources[].scopes	string[]	Yes	Requested scopes for the resource
context	object	No	Contextual attributes for policy evaluation

Permission Evaluation Response

Field	Type	Description
status	string	Overall result: GRANT, DENY, or ERROR
permissions	array	Per-resource, per-scope results
permissions[].resource	string	Resource name
permissions[].scope	string	Scope name
permissions[].status	string	Individual result: GRANT, DENY, or ERROR

Diagram

Example Scenario

Scenario

A frontend SPA (demo-spa) checks whether the current user can view employee data on the demo-api backend. The Access Gateway exchanges the token and delegates the permission evaluation to the Authorization Decision Provider.

Input

• Actor: Authenticated user with a valid exchanged token
• Resource: employee-data with scope can-view
• Action: Permission evaluation via the Authorization Decision Provider
• Context: clientId: demo-spa, resourceClientId: demo-api

Expected Outcome

• Decision: GRANT
• Why: Keycloak's authorization policies grant the user access to employee-data:can-view on the demo-api resource server. The provider returns a GRANT status with the matching permission entry.

Common Misunderstandings

• "The Authorization Decision Provider caches decisions." — No. Decision caching is handled by the Access Gateway's version-aware decision cache. The provider evaluates every request it receives against Keycloak's policies.
• "The Authorization Decision Provider is a standalone service." — No. It runs as a Keycloak extension within the Keycloak process. It does not have its own deployment — it is deployed as part of Keycloak.
• "Listing all permissions bypasses policy evaluation." — No. When retrieving a complete permission profile, all configured resources are evaluated against the user's policies. Only resources where all requested scopes are granted appear in the result.

warning

The Authorization Decision Provider is the single source of truth for all permission decisions. Do not implement authorization logic outside of Keycloak's policy configuration — doing so creates inconsistency between what the provider evaluates and what your application enforces.

Design Notes / Best Practices

• Define resources and scopes in Keycloak's authorization settings for the target client (resource server). The Authorization Decision Provider evaluates against these definitions.
• Prefer specific resource and scope queries over full permission profile queries. Use the list-all-permissions capability only when you need a complete permission profile (e.g., for UI rendering).

tip

The Access Gateway caches GRANT decisions. In high-traffic scenarios, most permission checks are served from cache without reaching the Authorization Decision Provider.

Related Docs

Access Gateway

PDP Proxy and Edge Orchestrator that delegates permission evaluation to the Authorization Decision Provider.

Enforcement Pipeline

Request processing stages that lead to permission evaluation.

Version-Aware Decision Cache

Subject-based caching that reduces calls to the Authorization Decision Provider.

Authority Integration & Token Mediation

Token exchange and permission evaluation flow between Access Gateway and authorities.

What is the Keymate Authorization Decision Provider?

The Keymate Authorization Decision Provider is the centralized authorization decision authority of the Keymate platform. It runs as a Keycloak extension and evaluates fine-grained permission checks — determining whether a user has access to specific resources and scopes based on configured policies.

How does the Authorization Decision Provider relate to the Access Gateway?

The Access Gateway handles request validation, token mediation, and decision caching. When a permission evaluation is needed, the gateway delegates the decision to the Authorization Decision Provider and enforces the resulting GRANT or DENY outcome.

Does the Authorization Decision Provider support multi-tenant authorization?

Yes. The provider includes an organization context endpoint that retrieves the authenticated user's tenant and department hierarchy. This supports authorization scenarios where decisions depend on organizational context.

Can I query all permissions for a user at once?

Yes. The Authorization Decision Provider supports retrieving a complete permission profile in a single call. It evaluates all configured resources and returns the full set of granted permissions for the authenticated user.