Getting started with User Managed Access (UMA)

User Managed Access is an OAuth-based access management protocol that allows owners of resources to passively authorize access to their resources by third parties. To understand how User Managed Access works, it is paramount that you understand how OAuth 2.0 works.

What is OAuth 2.0?

OAuth 2.0 allows a resource owner to let client applications access resources belonging to them on behalf of them. For example, a user may grant an online photo editing app access to their Facebook account in order to edit photos stored in their Facebook account using the photo editing app. What is important to note is that, here, it is the resource owner who is actually accessing his own photos through the editing app.

Now, imagine a scenario in which you want a professional photo editor to edit your photos stored in your Facebook account through the online photo editing app. How do you grant the professional access to your photos? The obvious way is to authenticate using your login credentials and consent to Facebook sharing your photos with the editing app, and then let the professional editor edit your photos.

However, this is not a very convenient way of doing it. What if the editor is in a different place? Sharing your private credentials with someone else is not safe and not something everyone would want to do, and rightly so. Furthermore, this requires the user’s intervention every time a third party wants to access their resources.

How can User Managed Access solve this problem?

User Managed Access was formulated to address such scenarios where resource owners may want to allow third parties to access their resources. This protocol is built on top of OAuth 2.0.

With User Managed Access, a resource owner can create policies in the authorization server and specify which person can access which resource and what they can do with that resource. In this example, the resource owner can create a policy in the authorization server that allows the professional editor to view their Facebook photos using their own user account. Thus, the professional editor can log in using their account and access the owner’s resource. However, the editor won’t be able to delete or modify the photos because the policy only allows the editor to view them.

How does User Managed Access work?

Now, let’s see how User Managed Access actually implements this.

There are five parties that are involved in this flow, viz.,

1. Authorization server—here is where policies regarding resource access are defined, and third parties are authorized to access protected resources
2. Resource server—this hosts the resources
3. Resource Owner—the person to whom the resources belong
4. Requesting party—the third party that wants to access the resource owner’s resource
5. Client—an application that requests access to the protected resources on behalf of the requesting party

Getting a Protection API Access Token (PAT)

First, the resource server obtains its OAuth 2.0 credentials from the authorization server by registering itself with the authorization server. Then, the resource server obtains an access token from the authorization server by presenting its client key and secret, and with the scope set to “uma_protection”.

This access token is called the Protection API Access Token (PAT). This token is unique to the resource owner, resource server and the authorization server, and is necessary to access the Protection API of the authorization server. We shall learn more about the Protection API as we go through the UMA flow.

Resource registration

Next, the resource owner would register a resource with the authorization server through the resource server. To that end, the resource server will send a request to the Resource Registration Endpoint of the authorization server with the PAT and the details regarding the resource. Following that, the authorization server will respond with the ID of the registered resource. It is important to note that this Resource Registration Endpoint is one of the three endpoints of the Protection API.

When a client makes a request to the resource server to access a resource, the resource server would check to see if the request has a Requesting Party Token (RPT). If it doesn’t, the resource server would query the Permission endpoint, which is another endpoint provided by the Protection API, of the authorization server with the PAT, requested resource’s ID and the scope. Thereafter, the authorization server responds with a Permission Ticket with the requested scope.

Next, the resource server sends the Permission Ticket and the URL of the authorization server to the client.

Before the client can interact with the authorization server, it must have obtained its OAuth 2.0 credentials from the authorization server. Then, using OAuth 2.0, the requesting party authenticates itself with the authorization server and obtains an access token.

The Requesting Party Token (RPT)

Once that’s done, the client sends a request for a Requesting Party Token (RPT) to the authorization server with the grant type set to urn:ietf:params:oauth:grant-type:uma-ticket, along with the Permission Ticket and the obtained access token (called claims token).

This grant type is called the UMA grant and is an extension of the OAuth 2.0 grant. Once the authorization server receives the grant request, it sees if the claims provided by the request, the scope, and the resource requested all comply with the policies. In other words, it examines if the resource owner has granted that particular user the requested permission for the requested resource. If everything is okay, the authorization server issues the RPT.

Then, the client sends another request to the resource server to access the resource, but this time with the RPT. The resource server, then, queries the Token Introspection Endpoint, which is the third endpoint provided by the Protection API, of the authorization server with the RPT and the PAT. If the RPT is valid, the authorization server sends a response in the affirmative.

Subsequently, if the client’s request corresponds with the scope of the RPT, the resource server grants the client access to the requested resource.

As can be seen, the UMA doesn’t involve the resource owner taking an active part in the flow. Consequently, this allows UMA to be used in various use cases. The application of it can be seen in the health sector where patients can allow doctors, insurance companies and applications that monitor health access to their health-related data. Besides, this also has implications in user-privacy management as the user can be granted control over who gets to access what data of theirs.