UMA 2.0 (User-Managed Access) in Keycloak
A zero-prior-knowledge guide to the open standard that lets the actual owner of a piece of data — not just an administrator — decide who else gets to see it, and how Keycloak turns that idea into a working system.
When you share a single photo album with one specific friend, or grant a colleague temporary access to one specific folder, you are doing something an ordinary company IT department almost never lets you do directly: making a real access-control decision about your own data, without filing a request or waiting for an administrator to act on your behalf. Most identity systems are built entirely around administrators deciding who can access what. User-Managed Access, or UMA, flips that assumption on its head for a specific, important class of situations — ones where the person who actually owns a piece of data should be the one deciding who else can touch it. This article explains, from first principles, what UMA 2.0 actually is as an open standard, and exactly how Keycloak implements it as a real, working feature.
Foundations
Core Concepts
Before UMA makes sense as a system, we need to understand the specific gap it exists to fill, compared to how most access control traditionally works.
The traditional model: administrators decide
In most identity and access systems, decisions about who can access what are made centrally, by an administrator configuring roles, groups, and permissions ahead of time. This works well for company-owned resources — an HR system, an internal tool — where a central authority genuinely should own those decisions. It works far less naturally for resources that are personally owned by an individual end user, where that person, not a system administrator, is the one who actually knows and should decide who else deserves access.
What is UMA?
User-Managed Access is an open standard, built as an extension on top of OAuth 2.0, specifically designed to let a resource’s owner control access to their own resources, and to let a completely separate party — someone the owner may be sharing with — request and obtain access to those resources through a standardized, secure process. Keycloak implements this standard directly inside its Authorization Services feature, meaning the Resources, Scopes, and Policies discussed elsewhere in Keycloak’s authorization model are the very same building blocks UMA relies on.
Picture a self-storage facility. In a traditional company office, the building manager decides who gets a key to which room, based on company policy. A self-storage facility works differently: each renter has their own private unit, and if they want to let a family member access it temporarily, they personally arrange that directly, without needing the facility’s central management to configure it for them. UMA brings this same personally-owned, individually-managed model of access to digital resources.
The five roles UMA introduces
UMA formally defines a small set of distinct roles that participate in every exchange. The Resource Owner is the person who owns a specific resource and controls access to it. The Resource Server is the application that actually hosts and protects that resource. The Authorization Server — Keycloak, in this context — manages Resources, Policies, and issues the tokens that grant or deny access. The Requesting Party is the person trying to gain access to the owner’s resource. And the Client is the application the Requesting Party is using to make that attempt.
Resource Owner
The person who controls access to a specific resource, such as their own personal document.
Resource Server
The application actually storing and protecting the resource, and enforcing decisions Keycloak returns.
Requesting Party
A different person entirely from the owner, attempting to gain access to that specific resource.
Authorization Server (Keycloak)
Evaluates Policies and Permissions, and issues the tokens that ultimately grant or deny the requested access.
Structure
Architecture & Components
UMA’s roles interact through a small set of specific tokens and endpoints, each with a distinct, well-defined job.
The Protection API Token (PAT)
Before a Resource Server can register Resources or manage Permissions on behalf of a Resource Owner, it must first authenticate itself to Keycloak using a Protection API Token, or PAT. This token proves the Resource Server itself is a legitimate, registered participant, entitled to call Keycloak’s Protection API to manage Resources belonging to its users.
The Permission Ticket
When a Requesting Party attempts to access a protected resource without yet holding the right level of access, the Resource Server does not simply reject them outright. Instead, it asks Keycloak to issue a Permission Ticket — a short-lived reference describing exactly which resource and which specific action was being attempted. This ticket is handed back to the Requesting Party’s client, effectively saying, “here is a formal reference to what you were just trying to do; take this to the Authorization Server to pursue access properly.”
The Requesting Party Token (RPT)
Armed with the Permission Ticket, the Requesting Party’s client exchanges it, through a specific UMA grant type, for a Requesting Party Token, or RPT — a specialized access token that, if the underlying Policies allow it, carries the specific permissions the Requesting Party has actually been authorized for. This RPT is what the client ultimately presents back to the Resource Server to gain the access it originally attempted.
The Resource Set Registration and Authorization endpoints
Underneath these tokens, UMA defines a small set of formal endpoints a Resource Server interacts with: one for registering and managing Resources (backed by Keycloak’s Protection API), and another specifically for the token exchange process that turns a Permission Ticket into an RPT. Keycloak implements both of these as part of its broader Authorization Services feature set.
flowchart TD
A["Requesting Party's Client attempts access"] --> B["Resource Server denies and requests a Permission Ticket from Keycloak"]
B --> C["Keycloak issues Permission Ticket"]
C --> D["Client exchanges Permission Ticket for an RPT"]
D --> E["Keycloak evaluates Policies and Permissions"]
E -->|"Authorized"| F["RPT issued with granted permissions"]
E -->|"Not authorized / needs consent"| G["Access denied or additional steps required"]
F --> H["Client presents RPT back to Resource Server"]
H --> I["Resource Server grants access to the resource"]
Fig 1 — The core UMA token exchange: a denied attempt becomes a Permission Ticket, which becomes an RPT, which finally unlocks access.
This flow deliberately separates “attempting access” from “obtaining authorization” into two distinct steps, each producing its own specific token, which is what allows the whole system to accommodate scenarios where access is not immediately available — for example, when the resource owner needs to actively grant permission first.
This chapter looks closely at what happens, step by step, when a Requesting Party attempts to access a resource they do not yet have permission for.
The first attempt and the denial
When the Requesting Party’s client first tries to access the protected resource, without holding any relevant permission yet, the Resource Server does not simply return a generic error. It specifically calls out to Keycloak’s authorization endpoint, on the Requesting Party’s behalf, describing the resource and action being attempted, and receives back a Permission Ticket in response, which it then returns to the client along with a message indicating that authorization is required.
Exchanging the ticket for an RPT
The client then takes this Permission Ticket directly to Keycloak’s token endpoint, using a UMA-specific grant type, to request an RPT. Keycloak evaluates every Permission and Policy relevant to the resource and scope named in the ticket, checking whether the Requesting Party — now authenticated as themselves — actually satisfies the conditions those Policies require.
Think of trying to enter a members-only lounge without a membership card. The bouncer does not simply turn you away with no further recourse — they hand you a numbered form describing exactly what you were trying to enter and when, and direct you to the membership office. At the membership office, that form is checked against the actual membership rules, and if you qualify, you are issued a temporary access pass, which you then bring back to the same bouncer to be let in. The numbered form is the Permission Ticket; the temporary pass is the RPT.
What happens if the owner has already decided
If the resource’s owner has already configured a Permission or Policy that covers this specific Requesting Party — for example, having previously shared the resource with them directly — Keycloak can issue the RPT immediately, without any further interaction needed at the moment of the request. This is what makes previously-granted, owner-managed sharing feel instantaneous on subsequent access attempts.
What happens when no decision exists yet
If no relevant Permission yet exists granting the Requesting Party access, Keycloak can, depending on configuration, either deny the RPT outright, or surface the pending request so the resource owner can be prompted to explicitly decide whether to grant it — commonly surfaced through account management interfaces where owners can review and approve pending access requests to their own resources.
Lifecycle
Data Flow & Lifecycle
Following one real sharing scenario — a user sharing a personal document with a specific colleague — end to end shows how every UMA piece connects.
The Resource Owner uploads a document
The application, acting as the Resource Server, uses its Protection API Token to register the document as a new Resource in Keycloak, owned by the uploading user.
A colleague requests access
A different person — the Requesting Party — attempts to open the document through their own client application, without yet holding any specific permission for it.
Access is denied, and a Permission Ticket is issued
The Resource Server denies the attempt but obtains a Permission Ticket from Keycloak describing exactly what was being requested, and returns it to the colleague’s client.
The colleague’s client attempts to exchange the ticket
The client sends the Permission Ticket to Keycloak’s token endpoint, requesting an RPT on behalf of the colleague, who is authenticated as themselves.
No matching Permission exists yet
Since the owner has not yet shared the document with this specific colleague, Keycloak does not issue an RPT immediately, and the pending request becomes visible to the owner.
The owner reviews and grants access
The Resource Owner, checking their own account’s resource-sharing management screen, sees the pending request and explicitly approves sharing the document with this specific colleague.
The colleague’s next attempt succeeds instantly
With a matching Permission now in place, the colleague’s next request for an RPT succeeds immediately, and their client is finally able to present a valid RPT to open the document.
Weighing the Choice
Advantages, Disadvantages & Trade-offs
Adopting UMA is a deliberate architectural choice, with real benefits for the right kind of application and real added complexity to weigh against them.
Advantages
- Lets end users share their own resources directly, without every sharing decision requiring an administrator’s manual involvement
- Built on an open, standardized protocol, rather than a proprietary, application-specific sharing mechanism
- Separates the moment of attempting access from the moment of being authorized, allowing pending, owner-reviewed requests to fit naturally into the model
- Integrates directly with Keycloak’s existing Resources, Scopes, and Policies, rather than requiring an entirely separate authorization system
Disadvantages & Trade-offs
- Introduces genuinely more moving parts than a simple role check — Permission Tickets, RPTs, and Protection API Tokens all need to be understood and implemented correctly
- Requires the Resource Server application to actively participate in the flow, rather than simply trusting a single, simpler access token
- User-driven sharing decisions can be harder for an organization to audit and centrally govern compared to administrator-defined access rules
- Building a good user experience around pending requests and approvals takes real design effort beyond the underlying protocol itself
When UMA is worth the added complexity
UMA earns its complexity specifically in applications where end users genuinely need to control sharing of their own individually owned resources — personal documents, private data, individually managed devices. For resources that are fundamentally owned and governed by the organization rather than an individual end user, simpler, administrator-driven Resources and Permissions, without the full UMA request-and-grant flow, are usually a better fit.
Defense
Security
Because UMA hands real access-control power directly to end users, its security depends heavily on how carefully each piece of the flow is implemented and validated.
Protecting the Protection API Token
The PAT used by a Resource Server to manage Resources and Permissions on behalf of its users is itself a highly privileged credential. If leaked, it could allow an attacker to register fraudulent Resources or manipulate existing Permission configurations, directly undermining the trust the entire owner-managed sharing model depends on.
It is easy to assume that because UMA puts sharing decisions in the hands of end users, Keycloak’s own security responsibilities are somehow reduced. In reality, Keycloak still fully evaluates every Policy and Permission before issuing an RPT — user-driven sharing decisions are captured as Permissions, and those Permissions are evaluated with exactly the same rigor as any administrator-defined rule elsewhere in the authorization model.
Permission Ticket lifetime and reuse
Permission Tickets are intentionally short-lived and meant to be used once, for the specific access attempt that generated them. Treating them as long-lived or reusable values would open unnecessary risk, since a leaked ticket could otherwise be used to probe or attempt access outside the specific context it was originally issued for.
Ensuring resource owners genuinely understand what they are granting
Because UMA moves real access decisions to end users, the interface a resource owner uses to review and approve pending requests must clearly and accurately describe exactly what is being requested — which resource, which specific action — so owners are not misled into granting broader or different access than they actually intended.
Auditing owner-granted Permissions
Even though sharing decisions originate from end users rather than administrators, organizations operating UMA-based sharing at scale should still maintain visibility into what has been granted, since an accumulation of forgotten, overly broad, or stale owner-granted Permissions can quietly become a meaningful security exposure over time if never reviewed.
Visibility
Monitoring, Logging & Metrics
Visibility into UMA activity matters both for security oversight and for understanding whether the sharing experience is actually working well for real users.
Keycloak’s account console sharing view
Keycloak’s user-facing account console includes a dedicated area where users can review resources they own, resources shared with them, and pending access requests awaiting their decision, giving both end users and, indirectly, administrators reviewing the system a clear picture of active owner-managed sharing relationships.
Watching for unusual Permission Ticket or RPT activity
A sudden spike in denied RPT exchange attempts against a specific resource, or an unusual volume of Permission Ticket requests originating from a single Requesting Party across many different resources, can indicate either a misbehaving client application or a deliberate attempt to probe the system for accessible resources.
Reviewing granted Permissions periodically
Beyond individual event monitoring, periodically reviewing the accumulated set of owner-granted Permissions across the system — particularly for resources tied to sensitive data — helps organizations catch stale, forgotten, or unexpectedly broad sharing grants before they become a meaningful exposure, even though the original sharing decisions were legitimately made by the resource owners themselves.
Shape
Design Patterns & Anti-patterns
Applications that build real, user-facing sharing features on top of UMA tend to converge on a handful of recognizable, effective patterns.
Pattern: Explicit, human-readable sharing prompts
Well-designed applications translate the underlying Permission and pending-request mechanics into clear, plain-language prompts for resource owners — “Priya wants to view your March expense report” — rather than exposing raw technical details, making the owner-driven decision genuinely easy and safe to make correctly.
Pattern: Scoped, time-limited sharing grants
Rather than granting indefinite access by default, thoughtful implementations encourage or default to sharing grants scoped to specific actions and, where appropriate, limited durations, reducing the chance that a one-time sharing decision quietly becomes a permanent, forgotten access grant.
Pattern: Combining owner-managed and administrator-managed Permissions
Some applications layer UMA’s owner-driven sharing on top of a baseline of administrator-defined Permissions — for example, an administrator-set rule ensures compliance staff always retain access, while individual owners can additionally grant sharing to specific colleagues on top of that baseline.
Anti-pattern: Exposing raw UMA mechanics directly to end users
A recurring mistake is building a sharing interface that surfaces technical concepts like Permission Tickets, RPTs, or raw Policy configuration directly to ordinary end users, rather than translating the underlying mechanism into a simple, intuitive sharing experience they can actually understand and use confidently.
Situation
A team building a document-sharing feature on top of UMA ships a first version that simply exposes a raw list of “Policies” and “Scopes” for users to configure directly, mirroring the underlying Keycloak concepts almost one-to-one, in order to save time on interface design.
Consequence
Ordinary end users find the sharing screen confusing and unpredictable, frequently misconfiguring access without realizing it, leading to a wave of support tickets about documents being shared with the wrong people or not shared with the intended ones at all.
Better Approach
Design a simple, plain-language sharing interface — “share with,” “can view,” “can edit” — that translates cleanly into the correct underlying Resources, Scopes, and Permissions behind the scenes, keeping UMA’s real mechanics entirely invisible to the end user making the decision.
Getting It Right
Best Practices & Common Mistakes
A handful of deliberate habits separate a UMA-based sharing feature that feels natural and trustworthy from one that quietly confuses or endangers its users.
Translate UMA concepts into plain language
Owners and requesting parties should never need to understand Permission Tickets or RPTs to use the feature correctly.
Make pending requests clearly visible
A resource owner should never be surprised to learn, long after the fact, that someone had been waiting on a sharing decision.
Protect the Protection API Token rigorously
Treat it with the same seriousness as any other highly privileged, application-wide credential.
Periodically audit accumulated sharing grants
Even legitimately owner-granted Permissions deserve occasional review, especially for sensitive resource types.
Treating Permission Tickets as reusable or long-lived
They are meant for a single, specific access attempt, not as a general-purpose token to be cached and reused.
Skipping a real user-experience design pass
UMA provides the underlying mechanism, not the interface — a good sharing experience still has to be deliberately designed on top of it.
Before building a sharing feature on UMA, sketch the exact plain-language sentence a resource owner should see when reviewing a pending request, and work backward from that sentence to the underlying Resources, Scopes, and Policies needed to support it — rather than starting from the technical model and hoping a reasonable interface falls out of it naturally.
In Practice
Real-World & Industry Examples
UMA-style, owner-managed access shows up wherever an application’s core value depends on individuals controlling their own, personally owned data.
Personal cloud storage and document platforms
Applications that let users store personal files and selectively share specific ones with specific other people rely on exactly the kind of owner-driven, per-resource sharing model UMA was designed to support, letting each user manage their own sharing decisions without administrator involvement in every case.
Connected smart-home and IoT device access
Platforms managing smart-home devices frequently need to let a primary device owner grant limited access to family members or guests — for example, letting a house-sitter temporarily control specific devices — a scenario that maps naturally onto UMA’s owner-managed, scoped sharing model.
Patient-controlled health data sharing
Healthcare platforms exploring patient-directed data sharing — where a patient personally decides which specific providers or family members can view their own health records — often look to UMA as the standardized mechanism underneath that kind of individually controlled consent model, rather than building an entirely bespoke sharing system from scratch.
Collaborative productivity and project tools
Tools where individual users create their own personal workspaces or documents, but occasionally need to invite specific collaborators into just one of them, frequently implement this collaborator-invitation experience on top of an owner-managed access model conceptually aligned with UMA, even when the underlying implementation details vary.
Questions Answered
FAQ
Wrapping Up
Summary & Key Takeaways
UMA 2.0 answers a question that traditional, administrator-centered access control was never designed to handle well: what happens when the right person to decide “who else can see this” is not an administrator, but the individual who actually owns the thing? By formally defining the Resource Owner, Resource Server, Requesting Party, Client, and Authorization Server roles, and by introducing the Permission Ticket and RPT to carry a request from a denied attempt through to a genuine, owner-approved grant, UMA gives Keycloak a standardized, well-tested way to support exactly this kind of individually controlled sharing — built directly on top of the same Resources, Scopes, and Policies already powering the rest of its Authorization Services.
Key Takeaways
- UMA puts sharing decisions in the hands of the actual resource owner — not solely in the hands of a central administrator.
- Five distinct roles participate in every exchange — Resource Owner, Resource Server, Requesting Party, Client, and the Authorization Server.
- A denied access attempt becomes a Permission Ticket — a short-lived reference to exactly what was being requested.
- The Permission Ticket is exchanged for an RPT — the actual token carrying whatever access has genuinely been granted.
- UMA builds directly on Keycloak’s existing Authorization Services — Resources, Scopes, and Policies remain the same underlying building blocks.
- Good UMA-based features hide the mechanics from end users — a well-designed sharing experience never requires understanding Permission Tickets or RPTs directly.
- Owner-driven sharing still needs oversight — periodic review of accumulated grants keeps individually-managed access from quietly becoming an unmonitored risk.