UMA 2 in Action: Part 1

Privacy has become a very significant global concern, not limited to any specific country or geographical area. Massive data breaches, data misuse by some large enterprises, and unauthorized surveillance have fueled large scale social movements that demand better privacy regulations and secure technologies. The General Data Protection Regulation (GDPR) in the European Union and the California Consumer Privacy Act (CCPA) are some of the best examples of modern-day privacy regulations that try to address key privacy concerns at present.

In the context of software systems, User-Managed Access (UMA 2.0 or UMA 2) is a standard which aims to strengthen data privacy based on the well-known privacy by design (PbD) principles. In technical terms, UMA 2 is a ‘party-to-party’ authorization protocol based on the OAuth2 authorization framework.

Let’s look at a common privacy dilemma to explore this topic in detail. Alice maintains an online bank account at Capital Bank and she has granted the following parties to access her online bank account:

• Bob - Alice’s spouse
• Carol - Alice’s accountant
• TouchPay app - NFC based mobile payment application

As you can imagine, each of the above parties accesses Alice’s online account for different purposes. For example, Carol only requires read-only access to account data while the TouchPay application should have the privilege to perform payment transactions. CapitalBank has facilitated Alice to grant the above privileges to each party via an online banking application. This granting process is technically known as ‘party-to-party’ authorization because Alice grants certain access to another specific party to access her bank account. Now that the requirements are clearly outlined, let us now discuss some possible solutions.

UMA 2 and OAuth2: The Difference

OAuth2 is an access delegation protocol which facilitates third-party applications ( OAuth2 Clients) to access protected resources on behalf of the resource owner (RO) using a temporary access token issued by an authorization server (AS) with the resource owner’s approval. Generally, OAuth2 clients access protected resources on behalf of the resource owner (RO), not on own or representing another party. This is why OAuth2 is usually known as an access delegation protocol. In contrast to OAuth2, UMA 2 allows resource owners to delegate access to third parties based on well-defined authorization policies maintained in the authorization server (AS). This is the fundamental difference between OAuth2 and UMA 2. However, in both of the cases, the client receives an access token to be used when accessing a protected resource.

OAuth2 has a concept called ‘Scope’, which can be used to denote various permissions associated with a resource. Yet, there is no defined semantic to represent resources in OAuth2. In contrast to OAuth2, UMA 2 has introduced a notation to represent resources and an API to manage them.

As clearly explained, UMA 2 and OAuth2 are different to each other. They do not compete with each other. UMA 2 is extended from OAuth2 by introducing a new grant type called ‘UMA 2.0 Grant for OAuth 2.0’. This is similar to the way that OpenId Connect protocol crafted an authentication protocol by extending OAuth2.

As UMA 2 is a party-to-party authorization framework, we can assume that the online banking application of CapitalBank uses UMA 2 when Alice performs granting activities.

In the context of UMA 2, Alice (who is our account owner) is known as Resource Owner (RO). The third parties that have access to Alice’s bank account (such as Bob, Carol, and TouchPay app) are known as Relying Parties (RP). Applications used by Bob and Carol to access Alice’s account are known as Clients. When a merchant uses the TouchPay application to authorize a transaction, TouchPay itself acts as an RP. The entity responsible for the generation of various tokens and tickets, the RO and third-party authentication, and access policy evaluation is known as the Authorization Server (AS). Generally, both the AS and RS belong to the same organization or there should be a strong trust relationship between organizations that own the AS and RS functions. Furthermore, Alice can define authorization policies. For example, Carol ( the accountant) can only view account data but can’t perform any transactions, while Bob can perform transaction up to $1000, etc. UMA 2 does not define any standard means to define policies, instead, UMA 2 implementers are free to define the right approach for authorization policies. In the following sections, I will discuss the main flow of UMA 2.

Step 1 - Client Attempts to Access a Protected Resource

Let’s assume that Bob is trying to check the balance of Alice’s account on CapitalBank using an application installed on his mobile phone. As depicted in the above diagram, during this initial step the application sends an HTTP request to the RS, requesting for the account balance without any security tokens.

In response, the RS sends the client HTTP 401 (Unauthorized) status code along with the address (URL) of the AS and a special token that is known as the permission ticket (PT).

• The value of WWW-Authenticate header is set to value “UMA,” which indicates that the particular resource is protected using UMA 2.
• The value of attribute “as_uri” indicates the URL of the AS where the client should reach for further interactions to get an access token.
• The value of ‘ticket’ attribute contains the permission ticket (PT) for this particular resource access interaction by this particular client on behalf of a specific relying party (Bob).

At this point, it’s worth discussing PT further. in appearance, PT looks like a randomly generated string. The PT is passed from the RS to the client and the client supposes to send the PT to the AS during further interactions. However, Let’s not much worry about how this value gets generated.

Step 2 - Client Interacts with AS to Get an Access Token

After processing the response message, the client could realize that it has to possess an access token in order to access the above resource and that it has to use UMA 2 protocol to interact with the AS.

In this step, the client makes an OAuth2 token request to the token endpoint (note that, the client can obtain this address from “as_uri” of the previous response) of the AS along with the PT. In this OAuth2 request, the client should use the value “urn:ietf:params:oauth:grant-type:uma-ticket” as the value of “grant_type” parameter. Other than the UMA 2 grant type value and UMA 2 defined “ticket’ parameter, all other parameters are identical to the standard OAuth2 request parameters.

Additionally, we have to make the following assumptions about the client:

• The client has already registered with the AS and obtained the OAuth2 client credentials (client_id and client_secret ) from the AS. To achieve this task, it is possible to use another OAuth2-related specification called OAuth 2.0 Dynamic Client Registration Protocol, which defines a RESTful API on the AS to facilitate client registration or any other approach supported by the particular authorization server.
• The client processes knowledge about the configuration of AS such as supported authentication mechanisms, supported grant types and endpoint URLs.

Upon receiving the OAuth2 request, the AS carries out the following procedure before replying to the client:

• Authenticate the client and validate the request message according to both OAuth2 and UMA 2 specifications.
• Authenticate the RP (in this case Bob) by redirecting the RP to the authentication endpoint of the AS. However, the underlying authentication mechanism is out of the scope of the UMA 2 standard.
• Upon successful authentication, the AS may try to gather claims from the RP interactively.
• Evaluate authorization policies in the context of authenticated RP (Bob), requested resource, scopes, and some other criteria. Once all of the above checks are completed, AS returns an access token. According to the UMA 2 standard, this access token is known as the Relying Party Token (RPT).

In addition to the RPT, the AS may return the following tokens as well:

• Refresh token - Same as the refresh token used in OAuth2, the purpose is to generate an active RPT by only providing this refresh token without repeating the whole token generation process.
• Persisted Claims Token (PCT) - An optional reference handle which represents the claims gathered during the above-mentioned claim gathering process. The client can send the PCT token when it sends the UMA 2 token request next time to skip claim gathering steps. In this article, we don’t discuss further details on PCT.

Step 3 - Client Attempts to Access a Protected Resource by Sending RPT to RS

This is similar to step 1. The only addition here is that the client sends the RPT value along with the resource access request through the Authorization HTTP header.

Authorization: Bearer sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv

Once the RS receives a request similar to the above one, it extracts the access token ( RPT) and validates it. In case of token validation, the RS can interact with the AS via the OAuth2 Introspection endpoint. After this token gets validated, the AS returns the requested resource to the client. In most of the practical cases, it’s recommended to cache the result of token Introspection call in order to improve the performance of the business activity.

You can also learn more about these aspects here.

Up to now, we have covered most of the important aspects related to the RP and the client when interacting with the RS and the AS. These aspects are discussed in the UMA specification called User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization. In this article, I provided an introduction to UMA 2. There’s an additional UMA specification called Federated Authorization for User-Managed Access (UMA) 2.0, which standardizes various interactions of the RS and RO (Resource Owner) with the AS. This specification will be discussed in the second part of this article series.