UMA 2 in Action: Part 2

This is the second part of our article series which explores practical use cases of User-Managed Access (UMA 2.0 or UMA 2). The primary focus of this article is to discuss a UMA 2 specification known as the Federated Authorization for UMA 2. This specification standardizes interactions among the authorization server (AS), the resource server (RS), and the resource owner (RO). Interactions among these entities establish the foundation for UMA 2 grant type, which is covered under UMA 2 Grant for OAuth 2.0 Authorization specification that we have discussed in the first article of this series, to function properly. The UMA 2 Federated Authorization specification defines two new secure APIs called Protection API and Resource API within the AS. Additionally, it also uses the OAuth2 Introspection endpoint for token validation.

The main endpoints are available on the AS

Resource Registration API

The concept of resource, which we discussed in the first article, can refer to any business level data that we intend to secure and manage in such a way that only authorized parties are allowed to access them. Some ideal examples include a photo stored in a photo hosting service, a medical record stored in eMedical service, or a bank account maintained in an online bank.

The resource registration API is a RESTful API hosted in the AS, which facilitates RSs to register the resources that they manage with the AS. (Note that the term resource is used in a very broad and abstract manner here). For the purposes of this article, let’s discuss a healthcare service provider which maintains health reports of registered patents. Further, let’s assume that there is a unique identification number is associated with each and every health report stored in this cloud service. As an initial step, the healthcare service (which is the RS in this case), should register each of these reports (resources) with the AS by sending a resource registration message along with report-id and scopes associated with each report such as view, edit, download, delete, etc.

Example of the content of the resource registration request message

It’s worth discussing more about the resource representation notion of UMA 2 based on the example above. In the message shown,‘resource_scopes’ parameter is the only required parameter which denotes the available scopes for the resource, it is possible to use any strings or a URI as the value. The representation of scope type can have a combination of the following optional parameters:

• Description: A human-readable string describing the resource. This may be used in any user interface which presents to a resource owner.
• Icon_uri: A URI for a graphic icon representing the scope.
• Name: A human-readable string naming the scope.

The following sample message depicts a resource registration message.

Example resource registration request message

The AS, in turn, registers above resource internally and generates a unique identifier called ‘resource-id’ which subsequently returns to the RS within the resource registration response message. The AS can use this resource-id to refer to the above resource in the future to modify or remove the underline resource.

Example resource registration response message

As mentioned above, the resource API further facilitates the modification or removal of resource definitions on the AS. It’s not necessary to discuss this call in detail, as it’s only a matter of making a RESTful call with proper the JSON message according to the specification.

However, if you closely pay attention to the above URL request corresponding to the resource registration message, you would notice that an authorization header passed with the message. This is the usual OAuth2 access token we have used when accessing any other real-world secure APIs. As mentioned previously, the resource API itself is a secured API and without a valid OAuth2 access token, it is not possible to access this API by the RS. This means that in order to access the resource API, the RS should possess a valid OAuth2 token. According to the UMA 2 specification, this token is known as Permission Access Token or PAT.

Permission Access Token ( PAT)

As discussed, the purpose of PAT is facilitating the RS to access Resource API of the AS. To reflect this concept, PAT should have the “UMA-protection” scope associated with it. Otherwise, it’s not possible to access the Resource API.

The RS, in this case acting as an OAuth2 client, can use any OAuth2 grant type supported by the AS to generate a PAT. But it is recommended to use an interactive grant type such as authorization code whenever possible.

Permission API

If you can recall the main UMA 2 flow that we described in the previous article, you may remember that when a particular client tries to access a protected resource in the RS without providing any security credentials, the RS returns the client a HTTP unauthorized message along with a special UMA 2 defined token called the Permission Ticket (PT) as a part of the HTTP header. The client is expected to pass this PT to the AS during future interactions.

The previous article did not discuss in detail how the RS generates or obtains this PT and we will explore this aspect here. Once the RS receives a resource access request without any security credentials, it calls the Permission API on the AS requesting a PT. The following diagram shows this interaction between the RS and AS.

Also note that, as we observed in the previous section, Permission API is also secured with OAuth2, hence the client should pass the PAT which we discussed in the previous section along with the permission requests. The PT is uniquely generated by AS to represent specific resource access by a specific client application.

In the diagram below, the same PT generation flow is given again with the involvement of all three parties.

Token Introspection

Token Introspection is a well-known specification used with the OAuth2 standard, which can be used to query additional details about the particular token by the token recipient parties from the AS that has issued the token. UMA 2 also uses this Token Introspection mechanism to validate RPTs (as discussed, in a generic view, RPT is also yet another OAuth2 Access token). In the context of UMA 2, when a client is trying to access a protected resource by providing a RPT, the RS uses the Introspection endpoint of AS to check the validity of the RPT. Token Introspection can be used to check the validity of any OAuth2 access token, hence it can be used with RPT as well. The following diagram illustrates this interaction among the client, the RS, and the AS.

The token recipients can use Token Introspection endpoint of the AS to query following information about an access token.

1. Active state of an OAuth 2.0 token (this varies important information when making access control decisions at API Gateways)
2. The associated scope of the token
3. Authenticated username
4. Identification of the token issuer
5. The intended audience of the token
6. Some metadata related to the token such as token type, issued time and expiration time, etc.

Access Policy Management

When the RP makes an access token (a RPT to be specific) request from the AS, after authenticating the RP it evaluates existing access policies to decide whether the RP should be allowed to access the particular resource or not. Generally, this evaluation is performed taking into consideration the following factors:

1. The authenticated user, user attributes, and roles associated with the user. In this case, the RP is the user.
2. Identity particular resource that the PR intended to access and associated scopes of the resource.
3. Existing policy definition which identifies the set of conditions that describe what users and roles can access a specific resource and any additional condition that needs to be fulfilled to receive an access token. For example, the time of the day or date within the week can be used as an evaluation factor.

The UMA 2 specification assumes these policies already exist in the AS. This is a very important feature because it facilitates the authorization decisions offline without real-time involvement of the RO. However, although UMA 2 expects the evaluation of access policies before issuing any RPT tokens, it does not specify any standards to define access policies or any concrete mechanism to evaluate access policies and administer these access policies. UMA 2 leaves particular UMA 2 implementers to decide the right mechanism to define, administer, and evaluate access policies. For instance, a fine-grained access control mechanism such as XACML or some other access control mechanism such as RBAC can be used.

UMA 2 and WSO2 Identity Server

From version 5.7.0 onwards, WSO2 Identity Server provides support for the UMA 2 specification which further strengthens privacy related capabilities. The RP and AS are represented as service providers (SP) in WSO2 Identity Server and it’s possible to use XACML as the policy language to define access policies. Alternatively, it is possible to use authentication scripting, which was quite popular with adaptive authentication features, to define more dynamic and simple access policies. You can find configuration details and try-out samples related to UMA 2 from here.

Summary

This article discusses the fundamental concepts of the UMA 2 standard and how these features can be used by business organizations to offer a high degree of privacy for their users. The first article of this series discussed the UMA 2 grant type and the most practical and most important flow in terms of the end user perspective.