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
https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html
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
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
Host: photoz.example.com
…- (4) Resource server responds with the following
HTTP/1.1 401 Unauthorized WWW-Authenticate: UMA realm="example", as_uri="https://as.example.com", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" …
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 Host: as.example.com Authorization: Basic jwfLG53^sad$#f … grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket &ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de
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
{"id":"238af68b-2d2b-49ab-91b1-33529b24a5f8","name":"a1","photos":[],"userId":"2fc1941c-a853-4ba4-b222-272b496b8eee","externalId":"b3b9e27d-c0aa-418e-bba6-b6a06a5c12a2"}
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": [
"https://localhost:8080"
],
"realm_access": {
"roles": [
"uma_authorization",
"user"
]
},
"resource_access": {
"photoz-restful-api": {
"roles": [
"manage-albums"
]
},
"account": {
"roles": [
"manage-account",
"manage-account-links"
]
}
},
"authorization": {
"permissions": [
{
"scopes": [
"album:view",
"album:delete"
],
"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": "jdoe@keycloak.org"
}
7 Illustration of a resource (Keycloak)
A resource is defined by:
• name
◦ it is the resource name
• owner
◦ alice (in this example)
• URI
◦ 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)
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
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
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
JANUA provides better security, build relationships, and enable new cloud, mobile, and IoT offerings from any device or connected thing.
- New Keycloak online training - 19 janvier 2022
- Sizing Keycloak or Redhat SSO projects - 8 juin 2021
- Keycloak.X Distribution - 28 janvier 2021