Keycloak Authorization Services: Policy Types Explained

Last updated: June 2026

Keycloak Authorization Services is a built-in fine-grained authorization engine where you define resources, scopes, policies, and permissions on a client acting as a resource server. Policies decide who or what is allowed and come in multiple types (role, group, user, client, time, regex, JavaScript, aggregate, and client-scope) that you combine into permissions evaluated at runtime by the Policy Enforcement Point (PEP) or retrieved as a Requesting Party Token (RPT) via the token endpoint. Understanding each policy type and when to reach for it is the key to building an authorization model that stays maintainable as your application grows.

Keycloak ships with a capable authorization engine that many teams never fully explore. Most developers start with realm roles and client roles and never look further. That is a missed opportunity: Authorization Services lets you attach fine-grained access rules directly to resources in your API, rules that consider group membership, time of day, attribute values, or combinations of all three, without any custom middleware code.

This guide walks through the complete conceptual model, every policy type available in Keycloak 26.x, the decision strategies that combine them, and a practical breakdown of when to use each. For a broader introduction to the subject, see Fine-Grained Authorization in Keycloak Explained.

---

The Authorization Services model

Before diving into policy types, it helps to understand how the pieces fit together. The Keycloak Authorization Services documentation describes a model built on four concepts.

Resource server

The resource server is a regular Keycloak client representing your API or application. Enable Authorization Services at Clients > {your-client} > Authorization by toggling Authorization Enabled. The client gains an Authorization tab with sub-tabs for Resources, Scopes, Policies, Permissions, and Evaluation.

Resources

A resource is anything you protect: an API endpoint, a document type, or a specific record. Resources live at Clients > {client} > Authorization > Resources. Each resource has a name, optional type, URI pattern, and owner.

Scopes

A scope represents an operation on a resource, typically view, edit, delete, or approve. Scopes live at Clients > {client} > Authorization > Scopes and are associated with resources.

Permissions

A permission binds resources or scopes to policies. Two types exist:

• Resource-based: Applies policies to a named resource or resource type.
• Scope-based: Applies policies only when a specific scope is requested, allowing different rules for view versus delete on the same resource.

Permissions are created at Clients > {client} > Authorization > Permissions.

Policy Evaluation tooling

The Policy Evaluation panel at Clients > {client} > Authorization > Evaluate lets you simulate a request for a given user, resource, and scope. It shows which policies matched, which permissions were granted or denied, and which decision strategy was applied. Use it throughout development to surface misconfigurations early.

---

Policy types in Keycloak

A policy is a standalone, reusable rule that answers one question: does this request satisfy this condition? Policies do not grant access by themselves. They are attached to permissions, and the permission’s decision strategy determines whether a PERMIT or DENY from any given policy translates into an overall grant or denial.

All policies are created at Clients > {client} > Authorization > Policies.

Role-based policy

A role-based policy grants access when the token contains a specified realm role or client role.

Configuration: Create a policy of type Role, then add one or more roles. Each role entry has a Required checkbox. If Required is checked for a role, the token must include that role for the policy to evaluate to PERMIT; if unchecked, any one of the listed roles is sufficient.

When to use: Role-based policies are the right default for coarse access control, as in “only users with the admin role can reach this endpoint.” They map cleanly onto Keycloak realm roles and client roles, which most teams already manage. For a deeper look at structuring roles, see Understanding RBAC: Protect Your Business’s Digital Access and the Skycloak RBAC feature page.

Limitation: Roles become unwieldy when access rules depend on user-specific attributes or contextual factors. For those cases, consider attribute-based policies described below.

Group-based policy

A group-based policy evaluates the groups a user belongs to in Keycloak.

Configuration: Create a policy of type Group, add one or more groups, and optionally check Extend to Children for each group to include subgroups automatically.

When to use: Group policies work well when your authorization boundaries align with organizational units: departments, teams, or tenant groups in a multi-tenant application. If your Keycloak realm already models org structure through groups, you can leverage that structure directly in authorization rules without duplicating it in roles.

Caution: Groups must be added to the token via a group membership protocol mapper on the client. Verify that groups appears in the token before relying on this policy type.

User-based policy

A user-based policy matches against specific named users.

Configuration: Create a policy of type User and add individual user accounts.

When to use: Rarely in production. User policies are appropriate for short-lived exceptions, such as granting a specific contractor access to a specific resource for a limited engagement, or for testing during development. At scale, managing per-user policies becomes operationally expensive. Replace them with group or role policies as soon as patterns emerge.

Client-based policy

A client-based policy evaluates the client ID that originated the token, rather than the user within that token.

Configuration: Create a policy of type Client and add one or more client IDs.

When to use: Machine-to-machine (M2M) authorization. When a backend service calls your API using a client credentials grant, there is no user subject. A client-based policy lets you express “only the billing-service client may access the /api/invoices resource.” Pair with scope-based permissions for precise M2M access control.

Time-based policy

A time-based policy evaluates the current date and time at the moment of the authorization request.

Configuration: Create a policy of type Time and configure any combination of:

• A Not Before date/time (access denied before this point)
• A Not On or After date/time (access denied from this point)
• Day of Week ranges (e.g., Monday through Friday)
• Hour ranges within a day
• Month ranges
• Year ranges

When to use: Regulatory or compliance requirements that restrict data access to business hours. Maintenance windows where administrative endpoints should be locked. Temporary access grants to contractors with a hard expiry date. Time policies are most useful when combined with other policies inside an aggregate policy (described below), because time alone is rarely sufficient to grant access.

Regex and JavaScript (attribute-based) policies

Keycloak gives you two distinct ways to make decisions based on attributes: the UI-native Regex policy for simple single-claim matching, and the deployed-as-a-JAR JavaScript policy for arbitrary logic. They look similar at a glance but differ sharply in capability and operational cost.

Regex policy: Still available natively in the admin UI in Keycloak 26.x. You select a token claim or user attribute, then provide a regular expression. The policy evaluates to PERMIT when the claim value matches the pattern. This is the simplest built-in way to do an attribute check directly in the console, for example matching a department claim against ^(finance|accounting)$. The catch: a Regex policy matches a single claim against one pattern. It is great for simple attribute conditions, not for complex multi-attribute logic.

JavaScript policy: For anything beyond a single-claim match, you reach for a JavaScript policy, which can read multiple claims and apply arbitrary conditions. Inline JS editing in the admin UI is disabled by default for security reasons, because arbitrary server-side script execution is a significant attack surface, and it cannot be re-enabled through the UI. To use one, deploy it as a JAR via the Keycloak SPI extension mechanism (/providers directory or the Operator’s extensions field) and reference it by provider ID in the admin console.

In practice, most teams implementing fuller attribute-based access control (ABAC) pick one of three approaches:

1. A custom SPI-deployed JS policy JAR
2. An external policy decision point such as OPA (see Keycloak Fine-Grained Permissions with OPA)
3. Attribute-based logic encoded into role or group assignments at token issuance

For a complete ABAC walkthrough, see Keycloak ABAC Configuration Step-by-Step Guide.

Aggregate policy

An aggregate policy combines multiple existing policies using its own decision strategy.

Configuration: Create a policy of type Aggregate, add any existing policies, and select a decision strategy (Affirmative, Unanimous, or Consensus, explained in the next section).

When to use: When you need compound conditions that no single policy type can express. Examples:

• “User must have the analyst role AND it must be a weekday AND it must be between 08:00 and 18:00″: combine a role policy, a time policy (day of week), and a time policy (hour range) in an aggregate with Unanimous strategy.
• “User must belong to the finance-team group OR have the finance-admin role”: combine a group policy and a role policy in an aggregate with Affirmative strategy.

Aggregate policies are the composition mechanism in Keycloak’s authorization model. Build your atomic policies first, then compose them.

Client-scope policy

A client-scope policy evaluates whether the token contains a specific OAuth scope (client scope in Keycloak terminology).

Configuration: Create a policy of type Client Scope, add one or more client scopes, and mark each as required or not.

When to use: When your API uses OAuth scopes as a first-class authorization mechanism, for example requiring the reports:read scope before allowing access to reporting endpoints. This policy type is particularly useful for delegated authorization scenarios where users or clients are granted specific scopes at token issuance, and you want the resource server to enforce those scopes at the permission level rather than in application code.

---

Policy type comparison

Policy Type	Decides Based On	Typical Use Case
Role	Realm or client roles in the token	Coarse-grained RBAC, most common default
Group	Group membership in the realm	Org-unit or tenant-based access
User	Specific named user accounts	Temporary exceptions, dev/test only
Client	OAuth client ID of the requestor	Machine-to-machine (M2M) access
Time	Current date and time	Business-hours restrictions, expiry windows
Regex	A single token claim matched against a regular expression (UI-native)	Simple attribute conditions, no code
JavaScript (SPI)	Custom logic over one or more claims (deployed as a JAR)	Complex ABAC, multi-attribute rules
Aggregate	Combination of other policies	Compound conditions (AND/OR logic)
Client Scope	OAuth scopes present in the token	Delegated authorization, scope-based APIs

---

Decision strategies

Every permission and every aggregate policy has a Decision Strategy controlling how it combines policy results.

• Affirmative: At least one policy must PERMIT (logical OR). Use when any qualifying condition is sufficient.
• Unanimous: All policies must PERMIT (logical AND). Use when every condition must hold simultaneously.
• Consensus: More policies must PERMIT than DENY (majority vote). Use sparingly, since it is harder to audit as policy sets grow.

The default for new permissions is Unanimous, which is the safest starting point.

---

RPT tokens and UMA 2.0

When a client calls the token endpoint to retrieve authorization decisions, Keycloak can return a Requesting Party Token (RPT), a JWT that embeds the granted permissions in an authorization.permissions claim. The resource server validates the RPT and reads those claims to make access decisions without a round-trip to Keycloak per request.

Two response modes are available:

• response_mode=decision: Returns { "result": true } or { "result": false } for lightweight yes/no decisions.
• RPT (default): Returns a full JWT listing every granted resource and scope.

Keycloak’s Authorization Services implement the UMA 2.0 (User-Managed Access) grant type, which extends RPT to allow resource owners to delegate access to third parties without involving the resource server operator. For a full walkthrough of UMA flows, see Keycloak UMA 2.0 Resource Sharing Guide.

The Policy Enforcement Point (PEP) in your resource server intercepts incoming requests, checks the RPT, and allows or rejects the request. The RPT is a standard JWT that any middleware can validate.

---

Frequently asked questions

What is the difference between roles and Authorization Services in Keycloak?

Realm and client roles are boolean flags on the token: your application code checks them and enforces the rule. Authorization Services moves enforcement into Keycloak itself, where you define resources, scopes, and policies in the admin console, and Keycloak evaluates them at request time. The distinction matters when access rules involve time constraints, attribute conditions, or resource ownership, factors that would require complex middleware if handled in application code. Authorization Services centralizes that logic in one auditable place. See Understanding RBAC: Protect Your Business’s Digital Access for an introduction to role-based models.

What is an RPT in Keycloak?

An RPT (Requesting Party Token) is a JWT issued by Keycloak’s token endpoint that contains an embedded authorization.permissions claim listing every resource and scope the bearer has been granted. Unlike a standard access token, which carries roles and claims about the user, an RPT carries the results of evaluating your Authorization Services policies at that moment. The resource server validates the RPT signature and reads the permissions claim to make access decisions without a round-trip to Keycloak per request. RPTs are central to the UMA 2.0 flow and can be requested by any client that has been granted authorization on the resource server. Full details are in Keycloak UMA 2.0 Resource Sharing Guide.

Which Keycloak policy type should I use?

Start with the simplest policy type that satisfies the requirement. Role-based policies cover the majority of access control needs and are the easiest to audit. Reach for group policies when your access boundaries follow an organizational structure already modeled in Keycloak groups. Use time policies for temporal restrictions and always combine them with role or group policies via an aggregate. Use client-scope policies for OAuth-scoped APIs where different token scopes unlock different capabilities. Avoid user-based policies in production except for one-off exceptions. For a simple single-claim attribute check, the UI-native Regex policy is the lightest option. For richer multi-attribute logic, use a SPI-deployed JavaScript policy or an external policy engine like OPA rather than inline JS, which Keycloak no longer supports in the admin UI. Aggregate policies are the glue that lets you compose all of the above.

Can you use Authorization Services alongside standard realm roles?

Yes, and most production deployments do. Realm roles handle authentication-layer access control: who can log in and receive a token. Authorization Services handles application-layer access control: which resources a valid token can reach. The two are complementary. A user might have the employee realm role to access the application at all, plus Authorization Services policies that govern which specific documents or API routes they can reach within it.

How do I debug a policy that is not granting the expected access?

Use the Policy Evaluation panel at Clients > {client} > Authorization > Evaluate. Select the user, resource, and scopes, then click Evaluate. The panel lists every evaluated policy, its result (PERMIT or DENY), and the final decision. If a role policy is denying unexpectedly, verify the role assignment and confirm the role appears in the token via a role mapper. If a group policy is denying, verify the groups claim is present in the token and that the group path matches exactly. Keycloak uses full paths like /engineering/backend, not just backend.

---

Summary

Keycloak Authorization Services gives you a complete fine-grained authorization engine built into the identity provider you are already running. The model (resource server, resources, scopes, policies, permissions) is consistent and composable. Each policy type handles a specific dimension of access control:

• Role and group policies for identity-based access
• Client policies for M2M access without a user subject
• Time policies for temporal constraints
• Regex policies (UI-native) for simple single-claim checks, and JavaScript policies (deployed as SPI JARs) for complex claim-based logic
• Client-scope policies for OAuth scope enforcement
• Aggregate policies to combine any of the above

Decision strategies (Affirmative, Unanimous, Consensus) give you precise control over how combined policies resolve. RPT tokens carry the results into your resource server without per-request round-trips to Keycloak.

If managing the infrastructure behind all of this sounds like overhead you would rather not deal with, Skycloak’s managed Keycloak hosting handles upgrades, clustering, and configuration management so your team can focus on building authorization policies rather than operating the server they run on.