A Quick Guide To User-Managed Access 2.0
By Dewni Weeraman
- 10 Dec, 2018
User-Managed Access 2.0 or UMA is a new federated authorization standard protocol built on top of OAuth 2.0 which enables party-to-party sharing. Kantara Initiative has introduced this award winning protocol.
UMA gives a resource owner the ability to control who can access his or her protected resources (digital assets) from a centralized authorization server by creating authorization policies no matter where the resources reside. For example, an elderly person sharing health-related data (such as medical prescriptions and blood reports) with doctors, his or her insurance company, and family members.
Sharing of resources can be done selectively which helps individuals gain control of their resource sharing in a reliable and secured manner. The specialty of this protocol is that resource owners need not to be present online at the access time as the cross-party sharing is driven by predefined policies.
Using UMA 2.0 standards enables you to 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.
The first version, UMA 1.0, was released in 2015. Kantara Initiative officially announced the approval and publication of the UMA Version 2.0 technical specifications in February 2018. UMA 2.0 was designed to be closely associated with the well-known OAuth protocol, making it easier for implementation purposes and improving its security aspects.
UMA 2.0 Specification
The protocol consists of 2 specifications:
- 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.
- 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 UMA grant.
Anatomy of UMA 2.0
UMA protocol consists of 5 roles:
- Resource Owner: An entity which grants access to a protected resource.
- Requesting Party: A person that seeks access to a protected resource by the support of a client.
- Client: An application that makes requests for protected resources on behalf of the requesting party with the resource owner’s authorization.
- Resource Server: A server that hosts protected resources and it has the capability of reacting to requests for protected resources.
- Authorization Server: A server that protects resources hosted by resource server on behalf of the resource owner.
The manner in which the resource owner manages his/her resources at the resource server and the manner in which the resource owner defines policies 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 that satisfies the resource owner’s policies. The client will then receive a token which it can present to the resource server in order to obtain the required access.
As depicted in the above diagram, UMA profile consists of two main components - protection API and UMA grant.
This OAuth protected API provides the following endpoints:
- Resource Registration Endpoint
- Permission Endpoint
- Token Introspection Endpoint (optional)
Prior to interacting with the protection API of the authorization server, the resource server should have acquired OAuth client credentials from the authorization server. To access the Resource Registration Endpoint, Permission Endpoint, and Token Introspection Endpoint, it is a must for the request made by the resource server to the authorization server to be accompanied with an access token, namely Protection API Access Token (PAT). PAT represents the resource owner’s authorization to use the protection API. The PAT token 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 protection of these resources.
Resource Registration Endpoint
Resource registration endpoint provides a means for the resource server to put resources under the protection of the authorization server on behalf of the resource owner and manage them over time.
A resource residing at a resource server falls under the protection of an authorization server by successful registration of the resource at the resource registration endpoint. The protection for the resource ends by de-registration at the resource registration endpoint. The resource owner can set policy conditions for the registered resource anytime before de-registration.
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 completely replacing the previous resource 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 this resource owner using the GET method.
This endpoint provides a means for the resource server to request permission(s) when the client’s resource request is unaccompanied by RPT (Requesting Party Token) 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 for access to the resources belonging to a single resource owner, protected by a single authorization server. As the response, the resource server receives a permission ticket which represents the same permissions that the resource server requested.
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.
UMA grant can simply be defined as an extension of OAuth 2.0 grant. The 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 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 Requesting Party Token (RPT) from the authorization server by presenting the received permission ticket and any other required claims. RPT will be issued with successful evaluation of policy conditions, scopes, claims, and any other relevant information.
A 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 some number of granted permissions.
For issuance of RPT, claims collection is required. The UMA grant specification mentions that this can be achieved by a client directly pushing claims or by supporting an interactive claims gathering with an end-user requesting party.
How Does UMA Work in WSO2 Identity Server?
As shown in the above diagram, WSO2 Identity Server acts as the authorization server supporting Protection API endpoints and UMA grant in the UMA flow.
- Resource server puts resources and their available scopes under authorization server protection. Once the resource is registered, the resource owner can set policy conditions at the authorization server.
- Client acting on behalf of the requesting party makes an access request to the protected resource (with invalid/no RPT access token).
- Resource server requests permissions (resources and scopes bound to that resource).
- Authorization server returns a permission ticket.
- Resource server returns authorization server uri and permission ticket.
- Client requests access token by providing the permission ticket and any required claims.
- Authorization server issues an RPT.
- Client requests for the protected resource with RPT.
- Resource server introspects RPT at the authorization server.
- Authorization server returns token introspection status.
- Resource server gives access to the protected resource.
The UMA grant specification mentions the use of a token named as PCT (Persisted Claims Token) 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 end-user 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 OIDC (OpenID Connect) tokens.
Kate is a senior citizen who needs to share her health-related information (present digitally) with various different parties which includes her son, doctors, and insurance company. She has the requirement to share these information in a fine-grained manner. For example, she wants to share her medical prescription with her son and hospital bill charges with the insurance company. Kate finds it frustrating to be present online every time it is required to share information with these parties.
There’s a solution that gives Kate the ability to control her resources pro-actively and sharing resources in a selective manner from a single hub no matter where the resources reside. The solution is UMA. With UMA, Kate can easily define who can access her resources under which permission scopes. Now Kate can share her medical data in a secured manner and she doesn’t have to be present online every time access to her digital data is needed by any relevant parties.
WSO2 Identity Server is a highly extensible, leading open source IAM solution to federate and manage identities across both enterprise and cloud environments. It now provides support for the award winning OAuth based protocol, User-Managed Access (UMA 2.0). UMA is a new federated authorization framework for resource sharing. With UMA, a resource owner can easily share resources with other requesting parties.
- Dewni Weeraman
- Software Engineer