A Quick Guide To User-Managed Access 2.0

Introduction

User-Managed Access (UMA) 2.0 is a federated authorization standard protocol built on top of Open Authentication (OAuth) 2.0 which enables party-to-party sharing. The award winning protocol was introduced by the Kantara Initiative.

UMA gives a resource owner the ability to control access to resources (digital assets) from a centralized authorization server by creating authorization policies regardless of where the resources reside. For example, a patient sharing health-related data such as medical prescriptions and blood reports with doctors, the insurance company, and family members.

Sharing resources can be done selectively which allows individuals to gain control of their resource sharing reliably and securely. The specialty of this protocol is that resource owners need not be online during access as cross-party sharing is driven by predefined policies.

Using UMA 2.0 standards enables individuals achieve the following:

• Context: The right moment to make the decision to share.
• Control: The power to share only what the resource owner desires.
• Choice: The ability to make an independent decision.
• Respect: Regard for one’s preferences.

UMA Versions

The first version, UMA 1.0, was released in 2015. The Kantara Initiative officially announced the approval and publication of UMA Version 2.0’s technical specifications in February 2018. UMA 2.0 was designed to be closely associated with the well-known OAuth protocol, making it easier to implement while improving its security.

UMA 2.0 Specification

The protocol consists of two specifications:

1. UMA 2.0 Grant for OAuth 2.0 Authorization: Specifies how a client should 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. Federated Authorization for UMA 2.0: Defines a means for an UMA-enabled authorization server and resource server to be loosely coupled, or federated, in a secure and authorized resource owner context. This specification is optional to be used with an UMA grant.

Anatomy of UMA 2.0

The UMA protocol consists of five roles:

1. Resource Owner: An entity which grants access to a protected resource.
2. Requesting Party: A person that seeks access to a protected resource by the support of a client.
3. Client: An application that makes requests for protected resources on behalf of the requesting party with the resource owner’s authorization.
4. Resource Server: A server that hosts protected resources and has the capability of reacting to requests for protected resources.
5. Authorization Server: A server that protects resources hosted by a resource server on behalf of the resource owner.

The manner in which the resource owner manages resources at the resource server and how policies are defined at the authorization server are out of scope for the UMA specification.

The client, acting on behalf of the requesting party, needs to get a token from the authorization server before getting access to a UMA protected resource. The client interacts with the authorization server and provides the necessary claims to satisfy the resource owner’s policies. The client will then receive a token which can be presented to the resource server to obtain the required access.

Figure 1

As depicted in Figure 1, the UMA profile consists of two main components - protection API and UMA grant. Let us review these further.

1. Protection API

This OAuth protected API provides the following endpoints:

a) Resource Registration Endpoint

b) Permission Endpoint

c) Token Introspection Endpoint (optional)

Before interacting with the protection API, the resource server must acquire OAuth client credentials from the authorization server. To access the Resource Registration Endpoint, Permission Endpoint, and Token Introspection Endpoint, the request must come from the resource server to the authorization server, accompanied with an access token called the Protection API Access Token (PAT). PAT represents the resource owner’s authorization to use the protection API. The PAT is simply an OAuth access token with the scope “uma_protection”. It uniquely represents the resource owner, resource server used for resource management, and authorization server used for protecting these resources.

a) Resource Registration Endpoint

Resource registration endpoint provides means for the resource server to place resources under the protection of the authorization server on behalf of the resource owner and manage them over time.

A resource in a resource server falls under the protection of an authorization server by successfully registering the resource at the resource registration endpoint. Protection for the resource ends by deregistering it at the resource registration endpoint. The resource owner can set policy conditions for the registered resource at any time prior to deregistration.

This API supports five registration options, which are:

• Create resource description: Registers a new resource to the authorization server using the POST method.
• Read resource description: Reads a previously registered resource description using the GET method.
• Update resource description: Updates a registered resource description by replacing the previous description, using the PUT method.
• Delete resource description: Deregisters a previously registered resource description using the DELETE method.
• List resource descriptions: Lists all previously registered resource identifiers for a particular resource owner using the GET method.

Figure 2

b) Permission Endpoint

This endpoint provides a means for the resource server to request permission(s) when the client’s resource request is unaccompanied by a Requesting Party Token (RPT) or is accompanied by an invalid RPT.

A permission represents a resource identifier and its corresponding scopes. At a single instance, the resource server can only request permissions to access resources belonging to a single resource owner, protected by a single authorization server. As a response, the resource server receives a permission ticket representing the same permissions asked by the resource server. This is illustrated in Figure 3.

Figure 3

c) Token Introspection Endpoint

This endpoint provides a means for the resource server to introspect the RPT which is required to access a UMA protected resource, and is explained by Figure 4.

Figure 4

2. UMA Grant

UMA grant can be defined as an extension of the OAuth 2.0 grant. The UMA grant enhances OAuth capabilities in the following ways:

• Enables party-to-party authorization. The resource owner authorizes access to his/her protected resource for clients used by entities that are in a requesting party role.
• Enables a resource owner to configure an authorization server with authorization grant rules (policy conditions) at will, rather than authorizing access token issuance synchronously after authenticating. The authorization server and resource server interact with the client and requesting party in a way that is asynchronous with respect to resource owner interactions.

When a client, acting on behalf of the requesting party, makes an initial resource request at the authorization server without access token or invalid access token, the client receives a permission ticket and the authorization server location. The client can then obtain a RPT from the authorization server by presenting the received permission ticket and other required claims. An RPT will be issued with successful evaluation of policy conditions, scopes, claims, and other relevant information.

An RPT is an OAuth access token associated with the UMA grant. An RPT is unique to a requesting party, client, authorization server, resource server, and resource owner. This token represents a selected number of granted permissions.

For issuing an RPT, claims collection is required. The UMA grant specification states that this can be achieved by a client directly pushing claims or by supporting an interactive claims gathering with the requesting party, as shown in Figure 5.

Figure 5

How Does UMA Work in WSO2 Identity Server?

Figure 6

As shown in Figure 6, WSO2 Identity Server acts as the authorization server supporting Protection API endpoints and UMA grants in the UMA flow.

1. The Resource server places resources and their available scopes under the protection of the authorization server. Once the resource is registered, the resource owner can set policy conditions at the authorization server.
2. The client acting on behalf of the requesting party makes an access request to the protected resource (with invalid/no RPT access token).
3. The resource server requests permissions (limited to resources and scopes bound to that resource).
4. The authorization server returns a permission ticket.
5. The resource server returns authorization server url and permission ticket.
6. The client requests an access token by providing the permission ticket and any required claims.
7. The authorization server issues an RPT.
8. The client requests for the protected resource with the RPT.
9. The resource server introspects RPT at the authorization server.
10. The authorization server returns token introspection status.
11. The resource server gives access to the protected resource.

The UMA grant specification mentions the use of a Persisted Claims Token (PCT) to represent a set of claims collected during one authorization process to be used by the client in future attempts for requesting RPT from the authorization server. The specification also defines an optional endpoint, claims interaction endpoint, to allow the end-user or the requesting party to interact with the authorization server to provide any required claims. As at the time of writing this article, WSO2 Identity Server doesn’t support the use of PCT and claims interaction endpoint. Claims are gathered by the use of OpenID Connect (OIDC) tokens.

Sample User Managed Access (UMA) Use Case

Kate is a senior citizen who needs to share her health information (available digitally) with different parties including her son, doctors, and the insurance company. She needs to selectively share this personal data in a fine-grained manner and manage sharing preferences. For example, Kate wants to share her medical prescription with her son and hospital bill charges with the insurance company. Understandably, Kate finds it frustrating to be present online every time she needs to share information with these parties.

UMA gives Kate the ability to control her resources proactively and to share resources selectively from a single hub, regardless of where the resources reside. With UMA, Kate can easily define who can access her resources under which permission scopes. Now, Kate can share her medical data securely and doesn’t need to go online whenever the relevant parties need access to her digital data.

Conclusion

WSO2 Identity Server is a highly extensible, leading open source IAM solution to federate and manage identities across both enterprise and cloud environments. The solution provides support for the award-winning OAuth based protocol, User-Managed Access (UMA 2.0). UMA is a federated authorization framework for resource sharing. With UMA, a resource owner can easily share resources with other requesting parties.

References

https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html