In this article, we will try to understand and demistify UMA and Keycloak. UMA is quit new and we will try to understand the new paradigms, use cases and demonstrate its implementation within Keycloak.

1 Presentation – What is UMA ?

UMA stands for User Management Access (UMA)

It defines a means for a client, representing a requesting party, to use a permission ticket to request an OAuth 2.0 access token to gain access to a protected resource asynchronously from the time a resource owner authorizes access.

2 Pointers

3 UMA Key stakeholders

The workflow consists of several part/actors:

• Resource Server
◦ It holds the the resources, and delivers permission ticket when accessing to a resource
• Authorization server
◦ hosting and protecting resource server resources
(Keycloak here)
• client
◦ an application trying to access to a resource protected by the resource server
• Resource owner
◦ person owning the resource, and able to take decision to accept/deny access to the resources
• Requesting Party
◦ person who is asking to access to the resource (which is protected)

4 UMA workflow

UMA and Keycloak

5 UMA typical use case

Below is described a typical use case:

  • (1) Requesting party is logged and accessing client application
  • (2) Requesting party is trying to access to a specific resource on the resource server from client application

• (1) Requesting party is logged and accessing client application
• (2) Requesting party is trying to access to a specific resource on the resource server from client application

  GET /users/alice/album/photo.jpg HTTP/1.1
  • (4) Resource server responds with the following
HTTP/1.1 401 Unauthorized
 WWW-Authenticate: UMA realm="example",

The elements provided in Resource server answer are:

• HTTP/1.1 401 Unauthorized
• WWW-Authenticate: UMA
• as_uri: URI of the authentication server
• ticket: permission ticket

• (5) The client application is contacting the authorisation server uma token end point with the ticket issued before.
  AS output, is delivered a RPT token  
POST /token HTTP/1.1
 Authorization: Basic jwfLG53^sad$#f
HTTP/1.1 200 OK
 Content-Type: application/json
     "access_token": "${rpt}",
  • (6) Using the RPT token to access to the resource

To access to the resource, the user needs to invoke the resource URI with the RPT token

As the resource as been registered within keycloak, the RPT token is evaluated w.r.t to the permission in use on the authorization server to protect the resource.

When the permission is successful, the requesting party is allowed to access to the resource

curl -X GET https://localhost:8080/photoz-restful-api/album/238af68b-2d2b-49ab-91b1-33529b24a5f8  -H 'Authorization: Bearer '$RPT  

6 Illustration of a RPT token (Request Party Token)

An RPT is a kind of special token access token with permission description inside the token

Below the dump of an RPT token

To be notice is that the RPT token contains permission fields

   "jti": "7cbefd03-0d67-4f0d-8bd5-2e40268e11e4",
   "exp": 1558514119,
   "nbf": 0,
   "iat": 1558513819,
   "iss": "https://localhost:8180/auth/realms/photoz",
   "aud": "photoz-restful-api",
   "sub": "3ddb236e-339c-4b91-8224-6e94e8350830",
   "typ": "Bearer",
   "azp": "photoz-html5-client",
   "auth_time": 1558513810,
   "session_state": "7a69e6b8-7c0f-4435-880b-d3161000896c",
   "acr": "1",
   "allowed-origins": [
   "realm_access": {
     "roles": [
   "resource_access": {
     "photoz-restful-api": {
       "roles": [
     "account": {
       "roles": [
   "authorization": {
     "permissions": [
         "scopes": [
         "rsid": "a3b2d138-2222-4e8e-8938-e06104bb2b73",
         "rsname": "italy vacation1"
   "scope": "profile email",
   "email_verified": false,
   "name": "John Doe",
   "preferred_username": "jdoe",
   "given_name": "John",
   "family_name": "Doe",
   "email": ""

7 Illustration of a resource (Keycloak)

A resource is defined by:

• name
◦ it is the resource name
• owner
◦ alice (in this example)
◦ It is the URI used to access to the resource
• scope
◦ It is the kind of action can applied to a resource (album:view and album:delete)

UMA and Keycloak

8 Using permission

Alice is the owner of the resource a4, and jdoe is willing to access a4 resource in view mode (album:view)

At the beginning, Jdoe hasn’t been given by alice the access right to access to A4 resource. Therefore, when Jdoe want to access to A4 resource, the following is happening:

• JDOe gets an error 403 (Unauthorized)
• a permision request is sent to alice

UMA and Keycloak

Alice can approve or deny jdoe request.

Once a a permission requestion has been approved by Alice, Jdoe will be able to access to the resource next time.

9 Request approval or revokation

A resource owner (alice) keeps track of the approved request.
As long as the request remains approved, jdoe can access album:view on a4

But the Alice can also revoke at anytime access request to the resource

UMA and Keycloak

10 UMA with Keycloak – Improve application productivity

UMA is very powerful specification/ mechanism which allows to protect access to resources.

Keycloak implement UMA 2.0 protocol, at a very fine grain level, where it is possible to control access to the resources based upon permission.

The underlying complexity of handling/controlling access and permissions to the resources from applications can now be handled in the keycloak Authorization server.

This is a major step forward, as it will contribute to rationalize applications (which no longer have to deal with permission and access control) and also ease application maintenance as they no longer have the burden of permission and access control maintenances

Les derniers articles par janua (tout voir)