Keycloak fine-grained authorization: how it works

Roles work until a rule depends on the record someone is touching. "Approvers can approve invoices" is a role. "Approvers can approve invoices of their own department, below 50,000, during business hours in the invoice's region" is four conditions. Roles can only express them by multiplying: one role per department, per limit, per region. Our post on the limits of RBAC explains why role counts grow with every exception.

The signs are easy to recognize in a Keycloak realm:

• Role names carry customer, region or limit: invoice-approver-emea-under-50k.
• Ownership checks ("is this user on the project that owns this document?") are if statements repeated in several services.
• Temporary access is a ticket to add a role and a reminder to remove it.

Coarse-grained authorization answers "may this user use this application?". Fine-grained authorization answers "may this user approve this invoice, now?". Keycloak's own Authorization Services answers part of that on the server, and a policy enforcer library applies the result inside each application. Keymate keeps Authorization Services available and on top of it decides every request in the request path, so applications in any language are covered.

Each policy uses the model that fits its rule, and one policy can combine several.

The payment release above reads two roles (payment-approver and senior-approver) and an attribute (the user's approval limit), combined in one named policy and, if you add it, a risk score, all in one decision.

An access control list (ACL) attaches to each object a list of who may do what with it, as file systems, databases and network devices do. ACLs are precise, but because they live on each object, the rule behind them ("the team that owns the project can edit it") is written nowhere. Discretionary access control (DAC) lets an object's owner change its list. Mandatory access control (MAC) sets access by labels, such as classification levels, that users cannot change. Keymate policies write the rule once: relationships do what per-object lists do, and attributes do what labels do.

A Keymate policy names the resource and the action it covers, the conditions that must hold, the effect (allow or deny) and how it combines with other policies on the same resource. Policies are written in the admin console.

• Visual editor or policy language.

  A visual editor for people who think in conditions, and a policy language for people who prefer code. Both produce the same policy, and you can switch between the two views of one policy.

• Validated.

  A validator checks each policy before anyone can activate it.

• Templates.

  A new policy can start from a template.

• Versioned, with optional approval.

  Every change has an author, a reason and a diff. You can require an approver before any policy change reaches production. Authorization Governance covers that change cycle.

The payment release above, in the policy language:

hasEffectiveRole("payment-approver")
  && (attributes.approval_limit >= 10000 || hasEffectiveRole("senior-approver"))

A payment approver can release it if their approval limit is 10,000 or more, or if they also hold the senior-approver role.

For each allow or deny, Keymate records which policy decided and which condition was met or missed, and states what would change the outcome. For the payment above, the explanation names the policy (payments-release), the condition that was missed (an approval limit below 10,000 and no senior-approver role) and what would allow the request (a payment approver with a limit of 10,000 or more, or with the senior-approver role).

When a user asks why they were denied, support reads that explanation. Every decision is also recorded with the policy version and any approval behind it. That is the evidence auditors ask for, and Access evidence for audits shows what the record contains.

Keymate enforces the same policies at five points: the Access Gateway in the request path, your API gateway, the service mesh between services, SDKs inside an application, and event streams. For event streams, Keymate decides which application may publish to, or read from, which stream. The decision is made on every request, not once at login: if a right is revoked at 10:02, the request at 10:03 is denied. Which enforcement point fits which application, and what each one needs from your code, is covered in the enforcement deep dive.

A service or an AI agent that calls your APIs signs in as a software client, and the same policies decide its requests.

• Machine identities.

  A service signs in with the OAuth client credentials grant. A policy can say that billing-worker may create invoices only in its own tenant and never delete them. That rule is checked on every call.

• AI agents.

  Today an AI agent that calls your APIs signs in as a service, and each of its calls is decided by the same policies as any other client, outside the agent, so an instruction the agent receives cannot widen what the policy allows. Treating an agent as an identity of its own, evaluated together with the person it acts for, is on our Roadmap.

Our post why AI agents need fine-grained authorization explains why authentication alone leaves agents over-privileged.