What Is a Policy?

A Policy is a named, reusable rule, configured inside Keycloak’s Authorization Services feature, that evaluates to either “satisfied” or “not satisfied” for a given user and request. On its own, a Policy doesn’t grant or deny anything — it’s purely a rule waiting to be attached to something it should actually govern, which is the job of a Permission, covered fully in Chapter 10.

Where Authorization Services Fits Into This Series

Everything covered so far in this series about Roles has assumed an application reads a user’s Roles out of a token and makes its own decision in its own code — “if the token contains the admin Role, allow this action.” Keycloak’s Authorization Services feature offers an alternative: instead of that decision living scattered inside application code, it lives centrally inside Keycloak itself, expressed as Policies, and the application simply asks Keycloak “is this specific action, on this specific thing, allowed for this specific user right now?” and gets back a straightforward answer.

Why Centralize Authorization Logic This Way?

Scattering permission checks across dozens of individual applications’ own code creates real problems at scale: inconsistent enforcement between applications, no single place to audit “who can actually do what,” and a genuine engineering cost every time a rule needs to change across many codebases at once. Centralizing the rules as Policies inside Keycloak means one update, made in one place, can immediately apply everywhere that Policy is actually used — a benefit that compounds as an organization’s number of protected resources and applications grows.

How It Works

A Role Policy is satisfied when the requesting user holds a specified Realm Role or Client Role. It can also be configured to require the Role only when a specific condition applies, and multiple Roles can be listed within a single Role Policy, with a setting controlling whether the user must hold all of them or just one.

Role Policy vs. an Application Reading Roles From the Token Directly

It’s worth being explicit about what’s actually gained here, since a Role Policy can seem, at first glance, to simply duplicate a check an application could make itself by reading its token’s Role claims directly. The real difference emerges at scale and over time: a Role Policy lives in one place, is reviewable by a security team without reading application source code, and can be combined with other Policy types (Chapter 8) without any application code changes — advantages that become increasingly valuable as the number of protected Resources and the sophistication of the rules involved both grow.

User Policy

A User Policy is satisfied only for a specifically named, finite list of individual users. This is a narrower, more explicit tool than a Role Policy, appropriate when an authorization rule genuinely applies to particular named people rather than a broader category of user.

Group Policy

A Group Policy is satisfied when the user belongs to a specified Group, covered elsewhere in this series as the common mechanism for bulk Role assignment. Using a Group Policy directly, rather than a Role Policy checking a Role that Group happens to carry, can sometimes better reflect an organization’s actual intent when the distinction is fundamentally about organizational structure (which team someone is on) rather than a formally defined permission label.

How It Works

A Time Policy is satisfied only when the current request falls within a configured window — a specific date range (useful for a temporary, time-boxed grant), a repeating time-of-day window, or specific days of the week. Unlike every Policy type covered so far, a Time Policy’s outcome has nothing to do with who is asking; it depends entirely on when they’re asking.

Time Policies and Temporary Access Grants

A Time Policy configured with a specific start and end date is a clean way to implement genuinely temporary access — a contractor’s project-based permission, an emergency “break-glass” grant issued during an incident — that automatically stops being satisfied once the window closes, without requiring an administrator to remember to manually revoke it later.

How It Works

An Aggregated Policy doesn’t check any fact on its own — instead, it references two or more other, already-defined Policies, and combines their individual results using a configurable rule, commonly requiring that all referenced Policies be satisfied (“unanimous”) or that at least one be satisfied (“affirmative”), among other available combination strategies.

Why Aggregation Is Preferable to Duplicating Logic

Without Aggregated Policies, achieving the same combined effect would require either building one large, bespoke custom rule from scratch for every new combination needed, or accepting looser, less precise enforcement. Aggregation lets an organization build a small library of focused, well-understood individual Policies, then combine them in different ways for different purposes — much like the composite Role pattern covered elsewhere in this series, applied here to rules rather than permission labels themselves.

How It Works

A JS/Rule-Based Policy runs custom logic, written by a developer, that receives details about the current request (the user, the Resource, the Scope, and other available context) and returns a satisfied or not-satisfied result based on whatever bespoke reasoning the organization needs — a proprietary risk score, an external system lookup, or any check too specific to be covered by a built-in type.

What a Permission Does

A Permission joins one or more Policies to a specific Resource, a specific Scope, or both, making the rule they express actually enforceable. Two main Permission types exist: a Resource-based Permission (governing any and all Scopes on a given Resource) and a Scope-based Permission (governing one specific action, potentially across multiple Resources).

Reading the Full Picture Together

Putting the whole model together: a Resource describes what, a Scope describes which action, a Policy describes the rule, and a Permission is what actually wires the rule to the thing it governs. An application never needs to understand any of these individually — it simply asks its one authorization question and receives one clean answer, with every layer of this structure working together invisibly behind that single request.

Design. An administrator or security architect identifies a genuine, reusable rule worth formalizing — often recognizing the same underlying condition would otherwise be duplicated across several different Permissions.

Creation. The Policy is created inside the relevant Resource Server, choosing the appropriate built-in type (or Aggregating several existing ones, or writing custom logic as a last resort).

Attachment. The Policy is attached to one or more Permissions, each joining it to specific Resources or Scopes it should actually govern.

Active Use. Every authorization request touching an attached Permission now evaluates this Policy as part of reaching its overall decision.

Reuse. Because Policies are independent, named objects, the very same Policy can be attached to many different Permissions across many different Resources, without being redefined each time.

Retirement. When a rule is no longer needed, the Policy can be detached from its Permissions and removed, though this deserves the same careful review as removing any other access control, to confirm nothing still depends on it unexpectedly.

graph LR
    A["Reusable Rule Identified"] --> B["Policy Created
(built-in type, aggregated, or custom)"]
    B --> C["Attached to One or More
Permissions"]
    C --> D["Evaluated on Every
Matching Authorization Request"]
    D --> E{"Rule No Longer Needed?"}
    E -->|"Yes"| F["Detached and Retired"]
    E -->|"No"| G["Reused Across Additional
Permissions Over Time"]
    

Negative Logic Deserves Careful Review

Because any Policy can be inverted with Negative logic, a reviewer auditing a Permission’s attached Policies should always check each one’s logic setting individually, rather than assuming a Policy’s name alone describes its actual effect — a Role Policy named “finance-approver” set to Negative logic is actually satisfied by everyone except finance approvers, the opposite of what its name might suggest at a glance.

Custom Policy Code Is a Security-Critical Surface

A JS/Rule-Based Policy runs directly inside the authorization decision path for every request it’s attached to, meaning a bug here can either wrongly deny legitimate access or, more seriously, be tricked into approving an action it shouldn’t. This code deserves the same review rigor as the custom authenticators discussed elsewhere in this series.

Fail-Closed Versus Fail-Open Behavior

Any custom Policy that calls out to an external system — the fraud-risk example from Chapter 9 is a good illustration — has to make an explicit decision about what happens when that external call itself fails or times out. A Policy that silently defaults to “satisfied” whenever its external dependency is unreachable is said to fail open, and this is almost never the right default for a security-relevant rule, since an outage in an unrelated system would quietly widen access rather than narrow it. The safer default, failing closed, treats an unreachable dependency as “not satisfied,” at the cost of occasionally denying a legitimate action during an outage — a trade-off worth making deliberately and documenting clearly, rather than leaving to whatever a custom Policy’s error-handling code happens to do by accident.

Least Privilege Applies to Policy Design Itself

The same least-privilege thinking that governs Role design elsewhere in this series applies just as directly to Policies: a Policy should check the narrowest fact that actually captures the intended rule, rather than a broader one that happens to produce the right answer today but would silently over-grant access the moment circumstances change. A Group Policy checking membership in a broad “all-staff” Group, used as a stand-in for a much narrower intended audience, is a common example of this drift, and it’s exactly the kind of gap a periodic Policy and Permission review, discussed in Chapter 14, is meant to catch.

Good Patterns

• Build a small library of focused, single-purpose Policies: combine them through Aggregation for specific needs, rather than creating many near-duplicate Policies
• Prefer built-in types over custom code: reach for a JS/Rule-Based Policy only once Aggregating existing built-in types genuinely can’t express the needed rule
• Verify combination logic explicitly: never assume how multiple Policies on one Permission combine — check and test it directly
• Name Policies for what they check, and note their logic setting clearly, so a Negative-logic Policy’s actual effect is obvious without needing to open its configuration

Anti-patterns to Avoid