What Is a Permission Ticket?

A Permission Ticket is a short-lived, opaque token issued by a Resource Server, naming a specific Resource (and optionally a specific Scope on it) that someone is attempting to access. On its own, it proves nothing about whether access should actually be granted — it’s purely a reference, a claim check, that gets exchanged in a second step for an actual authorization decision.

The Problem It Solves

An ordinary Access Token, covered in this series’ OpenID Connect guide, is obtained once, upfront, through a login flow, and carries a fixed, broad set of claims about the user. It has no built-in way to say “and by the way, I specifically want to access this invoice’s approve action right now” — that specificity has to come from somewhere else. The Permission Ticket flow exists to let an application ask this more specific, resource-aware question at the moment access is actually needed, rather than trying to bake every possible fine-grained detail into a single upfront login token.

Where the Name “UMA” Comes From

This flow implements a broader, formal standard called User-Managed Access (UMA) 2.0, an extension built on top of OAuth2. UMA’s own vocabulary introduces the terms this guide uses throughout — Resource Server, Requesting Party, Permission Ticket, and Requesting Party Token — and Keycloak is one of the more complete, widely used implementations of this standard.

The Client’s Initial Attempt

A Client attempts to access something on the Resource Server — perhaps fetching a specific invoice’s details — typically presenting whatever ordinary Access Token it already obtained through a standard login. Critically, this token may say nothing at all yet about the specific invoice being requested; it simply establishes who the user is.

The Resource Server Recognizes This Needs Finer-Grained Evaluation

Rather than making its own local decision, the Resource Server recognizes that this specific Resource is protected by Keycloak’s Authorization Services, and that a real-time, ticket-based check is needed to determine whether this particular user should actually be allowed to access this particular invoice right now.

What Gets Registered

The Resource Server calls a dedicated Keycloak endpoint, describing exactly which Resource (and optionally which Scope on it) the current request concerns. Keycloak responds with a freshly generated Permission Ticket — a short-lived, opaque reference to this exact, specific access attempt.

The Resource Server Returns the Ticket to the Client

Rather than granting or denying access itself, the Resource Server responds to the Client with an HTTP 401 status (meaning “not currently authorized”) along with the newly issued Permission Ticket, effectively telling the Client “here’s a reference to what you’re asking for — go get this evaluated properly.”

The Ticket Exchange Request

The Client sends the Permission Ticket to Keycloak’s standard token endpoint, using a specific UMA-defined grant type reserved for exactly this purpose, alongside its own existing Access Token identifying who’s actually asking. This single request effectively says “here’s who I am, and here’s the specific thing I was just told to get evaluated.”

Why This Step Happens at Keycloak, Not the Resource Server

Centralizing the actual decision at Keycloak, rather than letting the Resource Server decide locally, is exactly the same underlying motivation covered in this series’ earlier Policy guide: keeping authorization logic centralized, auditable, and consistent, rather than reimplemented differently inside every individual protected application.

Policy Evaluation

Keycloak locates the Permission tied to the Resource (and Scope) named in the ticket, and evaluates every Policy attached to it — a Role Policy, a Group Policy, a Time Policy, or any combination through Aggregation, exactly as described in this series’ earlier Policy guide — using the requesting user’s actual identity and context.

What an RPT Actually Is

If the evaluation succeeds, Keycloak issues a Requesting Party Token (RPT) — itself an Access Token, in the same JWT format covered in this series’ OpenID Connect and signing guides, but carrying an additional claim describing exactly which specific Resources and Scopes this particular token has now been authorized to access.

Presenting the RPT to the Resource Server

The Client retries its original request against the Resource Server, this time presenting the newly obtained RPT instead of its original, more general Access Token. The Resource Server verifies the RPT and confirms it specifically authorizes the exact Resource and Scope this request concerns, then finally serves the request.

The Limits of Role-Only Checks

A Role tells you something about a category of user in general — “this person is a manager” — but says nothing about a specific, individual object, like exactly which one of thousands of individual documents a manager happens to be allowed to view right now. Encoding a rule that depends on the specific object being accessed, not just the category of user asking, is exactly what a plain Role check alone can’t express.

Resource-Level Granularity Without Rebuilding the Token

The Permission Ticket flow lets this specific, object-level decision be made at the exact moment it’s needed, using live, current Policy evaluation, rather than requiring every possible object-level permission to somehow be pre-computed and stuffed into a single upfront login token — which would be both impractical for a large or frequently changing set of Resources, and immediately stale the moment anything about those permissions changed.

Letting a Resource Owner Grant Access Directly

UMA’s original vision imagined an individual Resource Owner — a person, not just an administrator — directly managing who else can access something they own, without needing an administrator to manually configure a Policy on their behalf. A user sharing a specific document with a specific colleague, entirely through their own action, is the kind of scenario this broader vision was built around.

Most Keycloak Deployments Use a Narrower Slice of This Model

In practice, many real-world Keycloak deployments use the Permission Ticket flow primarily for the administrator-configured, resource-level authorization pattern covered throughout the rest of this guide, without necessarily building out the full, end-user-driven sharing experience UMA originally envisioned — a perfectly reasonable, narrower application of the same underlying mechanism.

Policy Creation Can Itself Be Driven by an API Call

Building a genuine self-service sharing feature generally means the application itself, not a human administrator clicking through the Admin Console, creates the underlying Policy on the fly, using Keycloak’s own administrative API in response to the user’s own in-app action. The end user experiences this as a simple “share” button; behind that button, the application is quietly using Keycloak’s own management capabilities to construct a new, narrowly scoped Policy and attach it to the relevant Permission, all without the end user ever seeing or needing to understand any of Keycloak’s own configuration screens.

Resource Registration (Prerequisite). Before any of this can happen, the Resource Server must have already registered the relevant Resource and Scope with Keycloak, and an administrator must have already configured the governing Permission and its Policies.

Ticket Issuance. A specific access attempt triggers the Resource Server to register a fresh Permission Ticket, scoped to exactly that attempt.

Ticket Exchange. The Client presents the ticket to Keycloak, which is immediately consumed as part of the exchange — a Permission Ticket is not meant for repeated, long-lived reuse.

RPT Issuance. A successful evaluation produces an RPT, itself carrying its own expiration, exactly like any other Access Token.

RPT Use and Expiry. The Client uses the RPT for the immediate request (and potentially a short window of subsequent requests, depending on the Resource Server’s own design), until it eventually expires and a fresh exchange becomes necessary.

graph LR
    A["Resource & Permission
Pre-configured"] --> B["Access Attempt
Triggers Ticket Issuance"]
    B --> C["Ticket Exchanged
at Keycloak"]
    C --> D["Policies Evaluated"]
    D --> E["RPT Issued"]
    E --> F["RPT Used, Then
Eventually Expires"]
    F --> B
    

The Resource Server Must Still Verify the RPT

Simply receiving an RPT on a retried request isn’t, by itself, sufficient — the Resource Server still needs to properly verify its signature (using the RS256 verification approach covered in this series’ signing-algorithm guide) and confirm it actually authorizes the specific Resource and Scope being requested, rather than blindly trusting that any presented RPT must be valid for whatever is currently being asked.

Ticket Reuse Should Be Prevented

A Permission Ticket is intended for a single exchange, and a properly implemented Keycloak deployment treats an already-exchanged ticket as no longer valid for a second attempt — a safeguard worth confirming is genuinely in place, since a reusable ticket would undermine the tight, moment-specific scoping this flow is meant to provide.

The Resource Server’s Own Trust Boundary Still Matters

None of this ticket-based machinery replaces the ordinary need for the Resource Server itself to be a properly secured, trusted piece of infrastructure. If the Resource Server’s own code can be tricked into registering a ticket for a Resource the requesting Client shouldn’t even be allowed to ask about in the first place, the downstream Policy evaluation is only ever as sound as that initial registration step — the flow evaluates whether an already-identified access attempt is permitted, not whether the attempt was framed honestly to begin with.

Rate-Limiting Ticket Registration Guards Against Abuse

Because registering a Permission Ticket is itself a real operation with a real cost, an unusually high volume of ticket-registration requests from a single Client or user — potentially probing which Resources exist or attempting to overwhelm the evaluation pipeline — deserves the same kind of rate-limiting consideration applied to any other authentication or authorization endpoint, exactly as covered in this series’ discussion of Brute Force Detection for ordinary login attempts.

Logging Denials Without Leaking Resource Existence

Care is also worth taking in exactly what a denial response reveals. A Resource Server or Keycloak deployment that responds very differently to “this Resource doesn’t exist” versus “this Resource exists but you can’t access it” can inadvertently let an attacker enumerate which Resources are actually present in a system, simply by observing which specific denial message comes back. Keeping denial responses deliberately uniform, regardless of the underlying reason, avoids handing an attacker this kind of unintended reconnaissance capability.

Distinguishing Expected Denials From a Genuine Problem

Not every failed ticket exchange is itself a problem — a user correctly being denied access to a Resource their Policies genuinely don’t permit is the flow working exactly as intended, not a fault to fix. A useful monitoring setup distinguishes this expected, “policy correctly denied” outcome from a genuinely unexpected failure, such as a misconfigured Permission with no attached Policy at all, or a Resource Server unable to reach Keycloak’s token endpoint — the former is routine, everyday behavior, while the latter deserves real, timely attention.

Correlating Ticket Exchanges With the Originating Request

Because the full sequence spans an initial request, a ticket registration, an exchange, and a retried request, tracing a single user’s experience end to end requires correlating these separate events together, typically through a shared request or trace identifier carried across the whole sequence. Without this correlation, diagnosing a specific user’s reported access problem can mean piecing together several disconnected log entries by hand, a slow and error-prone process compared to having the full sequence already linked together for review.

Good Patterns

• Reach for this flow only when authorization is genuinely resource-specific, reserving simpler Role checks for broader, category-level rules
• Let client libraries handle the 401-and-exchange sequence transparently wherever possible, rather than hand-rolling this logic in every application
• Respect RPT expiration strictly, re-exchanging for a fresh one rather than extending its effective lifetime through independent caching
• Always verify a presented RPT’s signature and specific claims on the Resource Server side, never assuming its mere presence is sufficient

Anti-patterns to Avoid

Stepping back from the individual steps, the deeper value of this whole exchange is that it lets “who can access exactly this one thing right now” remain a live question, answered fresh against the current state of the world, rather than a frozen assumption baked into a token the moment someone logged in. That distinction matters most exactly where a plain Role check runs out of expressive power — a large, growing, or frequently reshuffled set of individually protected Resources, each potentially governed by its own combination of Policies that can change independently of any user’s underlying Role. Everywhere else, the simpler tools covered earlier in this series remain the right, lower-overhead choice, and reaching for this heavier mechanism only where the added precision is genuinely needed keeps a deployment’s overall authorization architecture both correct and comprehensible.