What Is a Claims-Based Policy in Keycloak?
A complete, no-code walkthrough of Keycloak's context-aware authorization — how claims shape access decisions in real time, and how to design them well.
Picture an airport security checkpoint that doesn’t just check your boarding pass once at the entrance. Instead, at every checkpoint along the way — the gate, the lounge, the jet bridge — a fresh set of facts is checked: which flight are you actually on right now, what class of ticket do you hold, has your gate changed in the last ten minutes. Nothing is decided once and forgotten; every checkpoint re-reads the current facts before letting you through. Keycloak’s claims-based, context-aware policies work the same way — they look at the live facts carried in a request and decide access based on what’s true right now, not just who you generically are.
1Core Concepts
Understanding claims-based policies starts with understanding what a “claim” actually is.
What is a claim?
A claim is simply a labeled piece of information about a user, a session, or a request — a small fact like “department: Finance,” “device: managed-laptop,” or “mfa-completed: true.” Claims can come from several places: they can be baked into the token issued at login, or they can be supplied fresh with the specific request being made right now.
Think of claims like the stamps on a well-traveled passport. Each stamp is a small fact: which country, which date, which type of visa. A border officer doesn’t just check that the passport is genuine — they read the specific stamps relevant to today’s crossing. A claims-based policy is that officer, reading the relevant stamps before deciding whether to wave someone through.
What makes a policy “context-aware”?
A context-aware policy doesn’t rely purely on static facts like “this user has the Manager role.” Instead, it factors in details that can change moment to moment — the specific claims sent along with the current request, attributes of the session, or the state of the resource being requested. This lets Keycloak make sharper, more situational access decisions than role membership alone ever could.
Claim
A labeled fact about a user, session, or request, such as a department name or a device type.
Claims-Based Policy
A policy that grants or denies access by inspecting specific claims present in the current request.
Context
The full bundle of situational information available at the moment of an access decision.
Runtime Claims
Claims supplied fresh with the specific request, rather than fixed at login time.
Static Attribute
A fact stored permanently on the user’s account, such as their department.
Policy Provider
The Keycloak component responsible for evaluating one specific policy type, including claims-based logic.
A role tells you something generally true about a person, almost regardless of the moment: “this user is a Manager.” A claim can tell you something true right now, that might be false five minutes later: “this request came from a managed corporate device.” Claims-based policies are built to reason about that second, more time-sensitive kind of fact.
2Architecture and Components
Claims-based policies plug into the same authorization services framework as every other Keycloak policy type, but pull from a wider set of inputs.
Where claims come from
Claims reaching Keycloak’s policy engine can originate from several sources layered together: claims embedded in the access token itself, additional claims attached to the specific authorization request being made, and attributes already stored on the user or client. A well-designed claims-based policy is explicit about exactly which of these sources it trusts for each fact it checks.
Token Claims
Facts embedded in the access or ID token at issuance time, such as roles or custom attributes.
Request Context
Additional claims or parameters supplied alongside the specific authorization request.
User Attributes
Facts stored persistently on the user’s account inside Keycloak’s user store.
Claims-Based Policy
The rule that compares one or more of the above sources against expected values.
Permission
Links resources and scopes to the claims-based policy (and possibly others) guarding them.
Policy Enforcement Point
The layer in front of the protected resource that asks Keycloak for a decision before allowing the request through.
How this differs from rules-based and JavaScript policies
Rules-based and JavaScript policies mostly reason over relatively stable facts — roles, group membership, user attributes fixed at some earlier point. Claims-based, context-aware policies are distinguished by their emphasis on facts supplied specifically with the current request, making them well-suited to conditions that genuinely change from one call to the next, such as which device initiated the request or what specific action a caller is asserting they’re performing.
A layered mental model
It helps to think of Keycloak’s policy types as a spectrum: role-based policies check “who you generally are,” rules-based policies check “a structured combination of stored facts,” and claims-based policies check “what’s specifically true about this exact request, right now.”
3Internal Working
Tracing exactly how Keycloak turns a request into a claims-based decision.
Step one: gathering the claims
When an authorization request arrives, Keycloak first assembles every claim it has access to for that request — pulling from the presented token, any additional context parameters sent with the request, and stored user attributes. This assembled bundle becomes the evaluation context for every policy attached to the relevant permission.
Step two: matching claims against expected values
A claims-based policy defines, for one or more specific claim names, what value or pattern is expected. During evaluation, Keycloak looks up each named claim in the assembled context and compares it against the policy’s expected value. If a required claim is missing entirely, that’s typically treated as a failed condition rather than silently ignored.
This step is like a pharmacist checking a prescription slip. They don’t just verify that a slip exists — they check specific fields on it: the patient’s name matches, the dosage matches, the prescribing doctor’s signature is present. Each field is a claim; each expected match is a condition.
Step three: combining with other policies
Claims-based policies rarely stand entirely alone. A permission might require a role-based policy and a claims-based policy to both agree, meaning a user must both hold the right role and have the right contextual claim present for that specific request to be permitted.
A claim being present in a token does not automatically mean it’s trustworthy for every purpose. A claims-based policy should be deliberate about which claims come from a source it actually trusts for that decision — not all claims carry equal weight.
4Data Flow and Lifecycle
Seeing the whole path from request to decision makes the moving parts concrete.
sequenceDiagram
participant Client as Client Application
participant PEP as Policy Enforcement Point
participant KC as Keycloak (Authorization Services)
participant Policy as Claims-Based Policy
Client->>PEP: Request access, carrying token + request claims
PEP->>KC: Ask for authorization decision
KC->>KC: Assemble context (token claims, request claims, user attributes)
KC->>Policy: Evaluate required claims against expected values
Policy-->>KC: Permit or deny
KC->>KC: Combine with any other attached policies
KC-->>PEP: Final decision
PEP-->>Client: Serve resource or deny access
The lifecycle of a claims-based policy
Like any authorization artifact, a claims-based policy moves through recognizable stages from design to retirement.
Identified
A business need surfaces for a decision that depends on request-specific facts, not just static roles.
Defined
An administrator specifies which claims to check and what values or patterns are acceptable.
Attached
The policy is linked to a permission covering specific resources and scopes.
Evaluated Live
Every relevant request is checked fresh, against whatever claims are actually present at that moment.
Reviewed
As claim sources evolve — a new token field, a retired attribute — the policy is revisited and adjusted.
Because the entire point of a claims-based policy is reacting to what’s true right now, caching its decision would defeat its purpose. Every single request gets its own fresh evaluation against the claims present at that exact moment.
5Advantages, Disadvantages, and Trade-offs
Claims-based policies unlock precision, at the cost of added design and operational complexity.
Advantages
- Reacts to situational facts that don’t change how a user’s roles work
- Enables fine-grained, per-request decisions rather than blanket access
- Composable with role-based, rules-based, and other policy types
- Keeps sensitive, situational logic centralized rather than embedded in application code
- Reflects changes immediately, since nothing about the decision is cached
Disadvantages / Trade-offs
- Depends heavily on the quality and trustworthiness of the claims supplied
- More moving parts to design, test, and reason about than a simple role check
- Missing or malformed claims can produce confusing, hard-to-diagnose denials
- Overly granular claim checks can make policies brittle to legitimate upstream changes
6Security
Because claims-based policies decide access based on situational facts, the trustworthiness of those facts is the whole security story.
Only trust claims from a verified source
A claim embedded inside a signed token has cryptographic backing — it can’t be silently altered without breaking the token’s signature. A claim supplied loosely as part of an unsigned request parameter carries much weaker guarantees. Security-sensitive policies should lean on the former wherever possible, and treat unsigned, request-supplied claims with proportionate caution.
Treating every claim as equally trustworthy regardless of where it came from. A claim asserted by the caller themselves, with nothing to back it up, should never be the sole basis for a sensitive access decision.
Explicit handling of missing claims
A well-designed claims-based policy explicitly decides what happens when an expected claim simply isn’t present — and the safe default is to deny, not to silently skip that condition. Ambiguity should never resolve in favor of access.
Prefer Signed Claims
Lean on token-embedded claims over loosely supplied request parameters for sensitive checks.
Deny on Missing
Treat an absent required claim as a failed condition, not a skipped one.
Validate Claim Shape
Check that a claim’s value is well-formed before comparing it, not just that it exists.
Layer with Roles
Combine claims-based checks with role-based policies rather than relying on claims alone.
7Monitoring, Logging, and Metrics
Because decisions here hinge on situational data, visibility into what claims actually arrived matters as much as the final outcome.
Signals worth tracking
Teams relying on claims-based policies often watch how frequently expected claims are simply absent (a sign an upstream token or request source changed shape), how often present claims fail the expected match (which can indicate legitimate business drift, like a renamed department), and the general mix of where claims are coming from, to catch a shift toward less-trustworthy sources over time.
Logging the specific claim that failed
When a decision is denied, logging which named claim failed to match — rather than a generic “access denied” — turns a confusing support ticket into a two-minute investigation.
8Design Patterns and Anti-patterns
Good claims-based design keeps decisions explainable; poor design turns them into a black box.
Problem
A policy checks a claim supplied entirely by the caller’s own request, with no independent verification, to grant access to a sensitive resource.
Why It’s Harmful
Anyone crafting the request can simply assert whatever claim value the policy expects, effectively self-authorizing without any real trust boundary in place.
Correct Approach
Reserve sensitive decisions for claims backed by a verifiable source, such as a signed token, and use unsigned request-supplied claims only for low-stakes, non-security-critical routing.
Problem
A policy silently treats a missing claim the same as a claim that matched, in order to “avoid breaking things” for callers that don’t supply it.
Why It’s Harmful
This quietly converts a should-be-restrictive condition into a no-op, effectively granting access to every caller who simply omits the claim.
Correct Approach
Explicitly deny when a required claim is missing, and address legitimate gaps by fixing the upstream claim source, not by loosening the policy.
A healthier pattern: explainable decisions
The strongest claims-based designs make it easy to answer “why was this denied?” in plain language — one clearly named claim, one clearly expected value, one clear mismatch. Complexity should live in how many such simple checks are combined, not in how opaque any single check is.
9Best Practices and Common Mistakes
A short, practical checklist for teams designing claims-based authorization in Keycloak.
Document claim sources
Record exactly where each required claim comes from and how trustworthy it is.
Keep checks focused
One claims-based policy should verify one clear, nameable fact, not a tangle of unrelated conditions.
Plan for absence
Decide up front what a missing claim means, and default that outcome to deny.
Review as tokens evolve
Revisit claims-based policies whenever the shape of tokens or requests changes upstream.
Building a claims-based policy against a claim’s current value format without accounting for how that value might legitimately change shape later — for example, a department name changing from a plain string to a structured code.
10Real-World and Industry Examples
Claims-based, context-aware access decisions show up wherever “who you are” alone isn’t a sufficient answer.
Device-aware access
Enterprises increasingly restrict sensitive actions to requests carrying a claim confirming the request came from a managed, compliant device, layered on top of normal role checks.
Step-up authentication scenarios
Some systems check a claim confirming that multi-factor authentication was recently completed before permitting a particularly sensitive action, even for an already-authenticated user.
Partner and B2B integrations
Organizations exposing APIs to external partners often use claims-based policies to check partner-specific context — such as a contract identifier or an agreed scope — carried along with each request, rather than relying on coarse role assignments alone.
11Frequently Asked Questions
A role-based policy checks a relatively fixed fact — role membership. A claims-based policy checks facts tied to the current request or context, which can vary from one call to the next.
They can come from the access token itself, from parameters supplied with the specific authorization request, or from attributes already stored on the user’s account.
No. Because the whole purpose is reacting to what’s true right now, each request is evaluated fresh against the claims present at that specific moment.
The safe, recommended behavior is to deny access, treating an absent required claim as a failed condition rather than something to skip past silently.
Yes. A single permission can require a claims-based policy alongside role-based, rules-based, or other policy types, all contributing to one combined decision.
No. Claims backed by a signed token carry stronger guarantees than claims freely supplied with an unsigned request, and sensitive decisions should weigh that difference.
12Summary and Key Takeaways
Claims-based, context-aware policies let Keycloak look past static roles and reason about what’s specifically true about a request right now — which device it came from, whether a fresh authentication step was completed, what situational facts accompany this exact call. That precision is powerful, but it’s only as reliable as the trustworthiness of the claims behind it. Designed with clear claim sources, explicit handling of absence, and honest logging of why a decision landed the way it did, claims-based policies turn Keycloak’s authorization layer from a blunt gate into a genuinely situational decision-maker.
Key Takeaways
- A claim is a labeled fact — about a user, a session, or the specific request being made.
- Context-aware means “right now,” not “in general” — the defining trait versus static role checks.
- Trust the source, not just the label — a signed token claim and an unsigned request claim are not equally reliable.
- Absence should mean deny — a missing required claim must never be silently treated as a pass.
- Evaluation is always live — nothing here is cached, by design.
- Combine, don’t overload — pair claims-based checks with role or rules-based policies rather than one sprawling condition.
- Log the specific mismatch — explainable denials make both support and audits far easier.