To understand an aggregated policy, you first need to understand what a plain “policy” is inside Keycloak’s authorization system.

A quick refresher: what is a policy?

Inside Keycloak’s Authorization Services, a policy is a single, named condition — for example “user has the manager role,” “request comes from a specific IP range,” or “current time is within business hours.” A policy by itself doesn’t grant or deny access to anything; it’s just a reusable rule that says whether a condition is true or false for a given request.

What an aggregated policy adds

An aggregated policy is a special kind of policy whose only job is to combine other, already-existing policies into one. Instead of checking a role or an IP address directly, it says “evaluate policy A, policy B, and policy C, then combine their individual results using this rule.” The output is still just one true/false decision, but it’s built entirely out of pieces you’ve already defined elsewhere.

Why not just write one big policy?

You technically could combine several conditions inside a single custom or JavaScript-based policy. But then that combined logic lives in exactly one place, tied to exactly one use case. The moment a second permission needs “role is manager OR role is admin,” you’d have to copy that logic again. Aggregation keeps each condition as an independent, testable, reusable unit, and lets combinations be built and rebuilt without touching the original policies at all.

Aggregated policies don’t operate in isolation — they sit inside a larger pipeline of resources, scopes, policies, and permissions that make up Keycloak’s fine-grained authorization model.

Policy types available for aggregation

Keycloak ships with several native policy types — role, user, group, client, time, and JavaScript-based (rule) policies — plus, importantly, the aggregated type itself. Because an aggregated policy is itself a policy, it can reference other aggregated policies too, letting you build layered combinations: a mid-level aggregation of two simple policies can itself become one ingredient inside a larger aggregation.

Decision strategy — the setting that makes aggregation meaningful

Every aggregated policy carries its own decision strategy, which decides how the results of its child policies are merged into one outcome. Keycloak offers three strategies:

Understanding the evaluation order helps explain some behavior that otherwise looks confusing, especially around the Affirmative strategy.

Step by step

When a permission tied to an aggregated policy needs to be evaluated, Keycloak’s policy evaluation engine runs through the aggregated policy’s associated policies one at a time, computing a grant or deny for each. It then applies the aggregated policy’s own decision strategy to those individual results to produce a single combined outcome, which is treated exactly like the result of any other policy type by whatever permission or higher-level aggregation is using it.

flowchart TD
    A[Permission evaluates Aggregated Policy] --> B[Policy 1: Role Check]
    A --> C[Policy 2: Time Window Check]
    A --> D[Policy 3: Group Check]
    B --> E{Decision Strategy}
    C --> E
    D --> E
    E -->|Unanimous: all must grant| F[Combined Result]
    E -->|Affirmative: any one grants| F
    E -->|Consensus: majority wins| F
        

A subtlety worth knowing: each associated policy has its own decision strategy too

Here’s a detail that catches many administrators off guard. Every policy in Keycloak — including each individual policy referenced inside an aggregated policy — already has its own resource-server-level default logic and can itself be composed of multiple conditions with its own “affirmative” or “unanimous” behavior internally. This nesting means that a confusing Affirmative-strategy outcome is often not a bug in the aggregated policy layer at all, but a mismatch between what you expect a child policy’s own internal logic to mean versus what it’s actually configured to do. When troubleshooting, it’s worth checking each associated policy’s own individual evaluation result in isolation before assuming the aggregation logic is at fault.

Logic negation

Like any Keycloak policy, an aggregated policy also supports a “Negate Logic” toggle. When enabled, the final combined outcome — after the decision strategy has already been applied — is flipped. This is useful for expressing “NOT (role is contractor AND after-hours)” style conditions without inventing a fourth decision strategy.

Building an aggregated policy follows a predictable sequence, and skipping steps is the most common source of setup confusion.

Combining policies changes the shape of your access-control surface, which is worth reasoning about deliberately rather than by trial and error.

Choosing the wrong decision strategy is a real security risk

An Affirmative strategy applied to a set of policies that were designed independently, without considering how they’d interact, can accidentally grant access whenever any single one of several loosely related conditions is met — which is often far more permissive than intended. Conversely, a Unanimous strategy applied to policies that were never meant to all apply simultaneously can produce unexpected denials that look like a bug but are actually the aggregation doing exactly what it was told.

Review aggregations whenever a building-block policy changes

Because a single underlying policy can be referenced by several aggregated policies, tightening or loosening one shared building block silently changes the behavior of every combination that uses it. A role policy that’s broadened to include a new role, for instance, widens access everywhere that role policy is aggregated into, not just in the one place someone was thinking about when they made the change.

Auditing combined outcomes

Because the combined result is what ultimately governs access, security reviews should test the aggregated policy’s actual output under representative scenarios — not just read the configuration and assume the intended meaning matches the configured decision strategy.

Authorization decisions that quietly deny legitimate users, or quietly grant more than intended, tend to surface as support tickets long before anyone notices in a dashboard — unless you watch for them directly.

Use the built-in policy evaluation tool

Keycloak’s admin console includes an “Evaluate” feature under a client’s Authorization tab that lets an administrator simulate a request — a specific user, resource, and scope — and see exactly which policies fired and how the aggregated result was reached. This should be the first stop whenever an aggregated policy’s real-world behavior needs verifying, rather than reasoning about it purely from the configuration screen.

What’s worth tracking over time

For permissions backed by an aggregated policy, it’s worth trending the overall grant/deny rate over time. A sudden shift after a routine change to a building-block policy — even one that seemed unrelated — is a strong signal that the aggregation’s real-world behavior has changed in a way nobody intended.

Common mistakes to avoid

Beyond choosing the wrong decision strategy, three mistakes recur in practice: forgetting that a building-block policy is shared across several aggregations before editing it; assuming the aggregated policy’s decision strategy also governs how multiple different permissions interact (that’s a separate, resource-server-level setting); and building a large aggregation for a condition that’s only ever going to be used once, where a simpler direct policy attached to the permission would have been easier to read and maintain.

Yes. Because an aggregated policy is itself a policy, it can be added to the “Apply Policy” list of a larger aggregated policy, allowing layered, nested combinations.

Unanimous requires every associated policy to grant access. Affirmative requires only one to grant. Consensus follows whichever side — grant or deny — has more votes among the associated policies.

No. An aggregated policy, like any policy, is not tied to a specific resource or scope on its own — it becomes relevant to a resource or scope only once it’s attached to a permission.

Yes — the aggregated policy always references the current version of each associated policy at evaluation time, so any edit to a building-block policy immediately affects every aggregation that uses it.

Keycloak doesn’t impose a hard limit, but readability and auditability suffer well before any technical limit would be reached — a handful of well-named conditions is usually more maintainable than a very long list.

An Aggregated Policy in Keycloak is a policy whose entire purpose is to combine other, already-existing policies into a single decision, using one of three decision strategies — Unanimous, Affirmative, or Consensus — to merge their individual results. It doesn’t check roles, groups, or networks directly; it orchestrates other policies that already do. This makes complex, multi-condition access rules reusable, auditable, and easier to reason about than one large custom rule, provided the decision strategy genuinely matches the real relationship between the conditions being combined.