Understanding UMA and Keycloak

 

Introduction

In this article, we demystify User-Managed Access (UMA) and explain how it is implemented in Keycloak. UMA introduces a powerful authorization paradigm that moves fine-grained access control out of applications and into a centralized authorization server.

UMA is especially useful in modern distributed systems, APIs, and microservice architectures where resource ownership and dynamic permission delegation are required.

---

What is UMA?

UMA (User-Managed Access) is an authorization framework built on top of OAuth 2.0.

It defines a mechanism that allows a client, acting on behalf of a requesting party, to obtain authorization after a resource owner explicitly grants access - often asynchronously.

In simple terms:

Users decide who can access their resources, and under which conditions.

Key characteristics:

• Built on OAuth 2.0
• Fine-grained, resource-based authorization
• Asynchronous approval workflow
• Centralized authorization logic

---

Specification Reference

The UMA 2.0 specification is maintained by the Kantara Initiative:

https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html

---

UMA Key Stakeholders

UMA clearly separates responsibilities between several actors:

Actor	Description
Resource Server	Hosts protected resources and issues permission tickets
Authorization Server	Evaluates policies and issues tokens (Keycloak)
Client	Application requesting access to a resource
Resource Owner	User who owns the resource
Requesting Party	User attempting to access the resource

---

UMA High-Level Workflow

1. Requesting party logs in to a client application
2. Client requests access to a protected resource
3. Resource server denies access and returns a permission ticket
4. Client sends the ticket to the authorization server
5. Authorization server evaluates permissions
6. A Requesting Party Token (RPT) is issued
7. Client retries the request using the RPT

---

Typical UMA Use Case

Step 1 – Accessing a Protected Resource

GET /users/alice/album/photo.jpg HTTP/1.1
Host: photoz.example.com

Step 2 – Resource Server Response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="example",
  as_uri="https://as.example.com",
  ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de"

Returned elements:

• HTTP status 401 Unauthorized
• WWW-Authenticate: UMA
• as_uri – Authorization server endpoint
• ticket – Permission ticket

---

Exchanging the Ticket for an RPT

The client contacts the UMA token endpoint:

POST /token HTTP/1.1
Host: as.example.com

grant_type=urn:ietf:params:oauth:grant-type:uma-ticket
&ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de

Response:

{
  "access_token": "<RPT>"
}

The returned token is a Requesting Party Token (RPT).

---

Accessing the Resource Using the RPT

curl -X GET https://localhost:8080/photoz-restful-api/album/238af68b   -H "Authorization: Bearer $RPT"

If permissions are valid, the resource server grants access.

---

Anatomy of an RPT Token

An RPT is a special OAuth 2.0 access token that embeds authorization decisions.

Example fragment:

"authorization": {
  "permissions": [
    {
      "scopes": ["album:view", "album:delete"],
      "rsid": "a3b2d138-2222-4e8e-8938-e06104bb2b73",
      "rsname": "italy vacation"
    }
  ]
}

Important fields:

• scopes – Allowed actions on the resource
• rsid – Resource identifier
• rsname – Resource name

---

Resources in Keycloak

In Keycloak, a UMA resource is defined by:

• Name – Logical resource name
• Owner – Resource owner (e.g. Alice)
• URI – Protected endpoint
• Scopes – Allowed operations (e.g. album:view, album:delete)

---

Permission Approval Flow

Scenario:

• Alice owns resource A4
• Jdoe requests album:view access

Initial state:

• Access denied (403 Forbidden)
• Permission request sent to Alice

Alice can:

• Approve the request
• Deny the request

Once approved, Jdoe can access the resource.

---

Permission Revocation

Resource owners can revoke access at any time.

After revocation:

• Existing permissions are invalidated
• Access attempts fail again

This guarantees continuous user control over shared resources.

---

Why UMA Improves Application Productivity

Using UMA with Keycloak:

• Centralizes authorization logic
• Removes permission handling from application code
• Enables fine-grained access control
• Simplifies long-term maintenance
• Improves security consistency

Applications focus on business logic — Keycloak handles authorization.

---

Conclusion

UMA represents a major evolution in access control.

With Keycloak’s UMA 2.0 implementation, teams can protect APIs and resources using a standardized, scalable, and user-centric authorization model — without embedding complex permission logic into every service.