User-Managed Access (UMA 2.0): Permission Tickets, Consent Flows and Secure Deployment

OAuth 2.0 assumes the person granting access is the person using the client, so it has no clean way for a patient, customer or account owner to share a resource with someone else, on their own terms, while they are not online. User-Managed Access (UMA) 2.0, published by the Kantara Initiative as two Recommendations dated 7 January 2018, extends OAuth so that a resource owner sets policy once at an authorisation server and a separate requesting party later asks for access through a permission ticket. This guide explains the UMA roles, the grant flow and the federated authorisation API, where UMA fits in health and consent use cases, how to implement and assess it, and the security traps the specifications themselves call out. It is for identity architects, API platform teams and privacy engineers who already know OAuth; the base protocol is covered in the OAuth 2.0 and OpenID Connect Guide.

Key takeaways

• UMA separates the owner from the requester. The resource owner authorises asynchronously by setting policy; the requesting party, who may be a different person or organisation, gets a token later through the client.
• The permission ticket drives the flow. A resource server answers an unauthenticated request with HTTP 401, a WWW-Authenticate: UMA header, the authorisation server URI and a ticket, which the client exchanges for a requesting party token (RPT).
• Two specifications, two jobs. The UMA 2.0 Grant defines the client side (grant type urn:ietf:params:oauth:grant-type:uma-ticket); Federated Authorization defines how resource servers register resources and request tickets through the protection API.
• Claims replace consent screens. The authorisation server gathers claims about the requesting party, pushed by the client or collected interactively, and evaluates them against the owner's policy.
• Security depends on the details. Tickets must be single-use, short-lived and unguessable, persisted claims tokens must be bound to their client, and an empty policy must never mean "allow".

What it is and who it applies to

UMA 2.0 is not a law or a compliance framework; it is a protocol profile of OAuth 2.0 that a product or ecosystem chooses to adopt. The two documents are Kantara Initiative Recommendations from the User-Managed Access Work Group, edited by Eve Maler with authors Maciej Machulak and Justin Richer:

• UMA 2.0 Grant for OAuth 2.0 Authorization: how a client, acting for a requesting party, uses a permission ticket to obtain an access token asynchronously from the resource owner's authorisation.
• Federated Authorization for UMA 2.0: how an UMA-enabled authorisation server and resource server are loosely coupled, so one authorisation server can protect resources hosted by many resource servers.

It applies wherever an individual controls data held by others and needs to share it with third parties: patient-directed sharing of health records, a customer granting an accountant or family member access to an account, consumer data sharing between services, and personal data stores. The OpenID Foundation's HEART (Health Relationship Trust) work group built profiles of OAuth, OpenID Connect and UMA so that patients could control how, when and with whom their clinical data is shared, on top of FHIR; that group is now listed as archived, but its use cases remain the clearest example of the problem UMA solves.

For newer delegation work, compare UMA with GNAP and Rich Authorization Requests in the OAuth 2.1, GNAP and FAPI Guide and the OAuth Rich Authorization Requests (RAR) Guide.

Structure and key requirements

Roles

• Resource owner: can grant access to a protected resource.
• Requesting party: uses a client to seek access; may or may not be the resource owner.
• Client: requests resources with the owner's authorisation on the requesting party's behalf.
• Resource server: hosts the resources.
• Authorisation server: protects them on the owner's behalf and evaluates policy.

The grant flow

1. The client requests the resource with no token (or an insufficient one).
2. The resource server asks the authorisation server's permission endpoint for a ticket, then returns HTTP 401 with WWW-Authenticate: UMA, as_uri and ticket. If it cannot obtain a ticket it returns 403 with a Warning: 199 header.
3. The client finds the token endpoint from /.well-known/uma2-configuration at as_uri and POSTs grant_type=urn:ietf:params:oauth:grant-type:uma-ticket with the ticket, optionally claim_token and claim_token_format, a pct, an existing rpt to upgrade, and scope.
4. The authorisation server evaluates the owner's policy against the claims and returns an RPT, or an error.
5. On need_info the client either pushes the required_claims or redirects the requesting party to the claims interaction endpoint with client_id, ticket, claims_redirect_uri and state, then retries with the new ticket.
6. The client presents the RPT as a bearer token; the resource server introspects it and enforces the permissions.

Token endpoint outcomes

Federated authorisation: the protection API

• Protection API access token (PAT): an OAuth access token with scope uma_protection that the resource server uses to call the authorisation server. TLS and a valid PAT are mandatory on every protection API endpoint.
• Resource registration endpoint: CRUD and list for resource descriptions; resource_scopes is required, name, type, description and icon_uri optional; creation returns 201 with an _id.
• Permission endpoint: takes resource_id and resource_scopes and returns a ticket (201), or invalid_resource_id or invalid_scope.
• Token introspection: extends RFC 7662; an active RPT's response carries a permissions array (each with resource_id, resource_scopes, optional exp, iat, nbf) instead of scope.
• Discovery: permission_endpoint and resource_registration_endpoint are required metadata; introspection_endpoint, claims_interaction_endpoint and uma_profiles_supported appear where supported.

Identity and NHI requirements

Every UMA deployment depends on several machine identities, and they are where most of the real risk sits:

RFC 9700, the OAuth 2.0 Security Best Current Practice (BCP 240, January 2025), applies in full: sender-constrained tokens via mutual TLS (RFC 8705) or DPoP (RFC 9449), audience-restricted access tokens, exact redirect URI matching and PKCE with S256. The UMA Grant itself notes proof-of-possession for RPTs is out of its scope, so binding has to come from these companion specifications. See the OAuth 2.0 Security Best Current Practice (RFC 9700) Guide and the DPoP Guide.

AI agents acting for a person are a natural UMA client: the owner's policy decides what the agent's requesting party may reach, and the RPT carries exactly those resource and scope pairs. Chains of agents still need attenuation at each hop, covered in the Delegation Chains and Attenuated Authority for AI Agents guide.

Implementation steps

1. Confirm UMA is the right tool. Choose UMA when a third party needs access the owner approves in advance or later; stay with plain OAuth and OpenID Connect when the user is always the one using the client. Small single-application teams often get more from fine-grained authorisation inside the application.
2. Write a profile. The specifications recommend written profiles and trust agreements. Define resource types, scope names, accepted claim token formats and issuers, ticket and token lifetimes, and the URIs you will advertise in uma_profiles_supported.
3. Model resources and scopes. Register resources at the granularity owners understand (a record set, a folder, an account), with scopes such as read, write or share. Avoid one resource per row: it bloats the registry and leaks detail to the authorisation server.
4. Stand up the authorisation server. Use a product that implements both specifications and publishes /.well-known/uma2-configuration. Keycloak, for example, exposes a per-realm discovery document listing token, introspection, resource registration, permission and policy endpoints, and supports a submit_request parameter that turns a ticket into a pending request; check each product's documentation for how far owner self-service actually goes.
5. Integrate resource servers. Issue a PAT per resource server, register resources at creation time, request tickets on unauthorised calls, and introspect RPTs on every request or cache results for no longer than the permission exp.
6. Build the owner experience. Owners need to see who has access, to what, and since when, and to revoke it. Privacy section 6.1 of the Grant asks that grant lifetimes follow the owner's actions.
7. Test. Run negative tests for every error code, expired and reused tickets, a PCT presented by a different client, a resource with no policy, and claims from an untrusted issuer. Pilot with one resource type and internal requesting parties first.
8. Roll back safely. Keep the resource server able to fall back to its previous access model per resource type behind a feature flag, and keep existing RPTs short-lived so a rollback does not leave long-lived grants behind.

Evidence and assessment

There is no UMA certification body to point an auditor at, so assessment relies on your own evidence:

• Configuration: the discovery document, registered clients with their claims_redirect_uris, PAT lifetimes and binding settings.
• Policy records: each owner's policies with creation, change and removal timestamps.
• Decision logs: every ticket issued, every token request with outcome (need_info, request_denied, success) and the claims evaluated, stored with personal data protections.
• Test results: the negative test suite above, rerun on each release.

Monitor for spikes in invalid_grant (ticket guessing or replay), PCTs presented by a client other than the one they were issued to, and resource registrations from a PAT outside its normal pattern.

Mapping to other frameworks

For the wider consent picture see the Identity Data Privacy and Consent Guide; for health sector identity, the Healthcare Identity Security Guide.

Common pitfalls

• Naive default-deny: the Grant (section 5.6) warns that a resource whose policy has no conditions must not be treated as permission to everyone. Test the empty-policy case explicitly.
• Reusable or guessable tickets: tickets must be single-use, expire and be unguessable (sections 5.4 and 5.5). Long-lived tickets turn the 401 response into a standing invitation.
• Unbound PCTs and RPTs: section 5.2 describes a malicious client switching users with an exposed RPT or PCT. Bind both to the client and keep them confidential.
• Missing state on claims redirects: claims interaction without state invites cross-site request forgery (section 5.1); public clients must pre-register claims_redirect_uri.
• Trusting any pushed claim: claim tokens need pre-established trust and audience checks (section 5.7), or a client can assert anything about its requesting party.
• Leaking owner identity: an unauthenticated request can reveal who owns a resource (privacy section 6.3), and verbose resource descriptions tell the authorisation server more than it needs (Federated Authorization section 8).

Practitioner checklist

• Document why UMA rather than plain OAuth, and write a profile with scopes, claim formats, issuers and lifetimes.
• Publish and review /.well-known/uma2-configuration; disable endpoints you do not use.
• Issue one short-lived PAT per resource server and log every protection API call.
• Make tickets single-use, short-lived and high entropy; alert on invalid_grant spikes.
• Bind RPTs and PCTs to the client with DPoP or mutual TLS and restrict RPT audience.
• Require state and pre-registered claims_redirect_uris for claims interaction.
• Test empty policies, expired tickets, cross-client PCT use and untrusted claim issuers on every release.
• Give owners a view of current grants with one-step revocation, and measure revocation time.
• Store claims and decision logs as personal data with defined retention.

Standards and references

• Kantara Initiative: UMA 2.0 Grant for OAuth 2.0 Authorization
• Kantara Initiative: Federated Authorization for UMA 2.0
• IETF: RFC 9700 Best Current Practice for OAuth 2.0 Security
• OpenID Foundation: HEART Working Group
• Keycloak: Authorization Services Guide
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: OAuth 2.0 and OpenID Connect Guide · Authorisation Models Guide · OAuth Scope Design Guide · Identity Data Privacy and Consent Guide