User-Managed Access (UMA, pronounced “OOH-mah”) is an OAuth 2.0 profile. OAuth 2.0 decouples the resource server from the authorization server. UMA takes one step forward: it lets you control a distributed set of resource servers from a centralized authorization server. It also enables the resource owner to define a set of policies at the authorization server, which can be evaluated at the time a client is granted access to a protected resource. This eliminates the need for the resource owner’s presence to approve access requests from arbitrary clients or requesting parties. The authorization server can make the decision based on the policies defined by the resource owner.
ProtectServe
UMA has its roots in the Kantara Initiative. The Kantara Initiative is a nonprofit professional association focused on building digital identity management standards. The first meeting of the UMA working group was held on August 6, 2009. There were two driving forces behind UMA: ProtectServe and vendor relationship management (VRM). ProtectServe is a standard that was heavily influenced by VRM. The goal of ProtectServe was to build a permission-based data-sharing model that was simple, secure, efficient, RESTful, powerful, OAuth-based, and system identity agnostic. ProtectServe defines four parties in its protocol flow: the user, the authorization manager, the service provider, and the consumer.
The service provider (SP) manages the user’s resources and exposes them to the rest of the world. The authorization manager (AM) keeps track of all service providers associated with a given user. The user is the resource owner, who introduces all the service providers (or the applications he or she works with) to the authorization manager and builds access control policies that define the basis on which to share resources with others. The consumer consumes the user’s resources via the SP. Before consuming any services or resources, the consumer must request an access grant from the AM. The requested access grant is evaluated against the policies defined on the associated service by its owner, at the AM. ProtectServe uses OAuth 1.0 (see Appendix B) as the protocol for access delegation.
The steps in the ProtectServe protocol flow are as follows:
- 1.
The user provides the metadata URL of the AM to the SP.
- 2.
The SP talks to the metadata endpoint of the AM and gets details related to the consumer key issuer, the request token issuer, the access token issuer, and the associated policies (OAuth 1.0 specification defines consumer key, request token, and access token).
- 3.
The SP initiates an OAuth 1.0 flow by requesting an OAuth request token from the request token issuer (which could be the same AM).
- 4.
The AM generates an authorization request token and sends it back to the SP along with other parameters defined under OAuth 1.0 specification.
- 5.
The SP redirects the user to the AM with a token reference along with other parameters defined under OAuth 1.0 specification, to get it authorized.
- 6.
Once authorized by the user, the authorization manager returns the authorized request token along with other parameters defined under OAuth 1.0 specification to the SP.
- 7.
To complete the OAuth 1.0 flow, the SP exchanges the authorized request token for an access token, with the AM.
- 8.
Once the OAuth flow is completed, the SP talks to the AM endpoint (which is secured with OAuth 1.0) to get an SP handle.
- 9.
The AM validates the OAuth signature and, once verified, issues an SP handle to the SP. An SP handle is a unique identifier generated by the AM to identify the SP in future communications.
Note
The service provider handle is a key that uniquely identifies the service provider at the authorization manager. This information is publicly available. A given service provider can have multiple service provider handles—one for each associated authorization manager.
- 1.
The consumer tries to access a protected resource hosted in an SP.
- 2.The SP detects the unauthenticated access attempt and returns an HTTP 401 status code with required details to get the SP metadata (see Figure D-2).
- 3.
With the details in the 401 response, the consumer talks to the SP’s metadata endpoint (see Figure D-2).
- 4.
The SP metadata endpoint returns the SP handle (which is registered at the AM) and the corresponding AM endpoint.
- 5.
The consumer talks to the AM endpoint to obtain a consumer key and a consumer secret (see Figure D-3).
- 6.
The consumer requests an access token from the AM, with its consumer key and the SP handle. The request must be digitally signed by the corresponding consumer secret.
- 7.
The AM validates the parameters in the access token request and issues an access token and a token secret to the consumer.
- 1.
The consumer tries to access the protected resource in the SP with its access token, signed with the access token secret.
- 2.
The SP talks to the AM and gets the secret key corresponding to the consumer’s access token. If required, the SP can store it locally.
- 3.
The SP validates the signature of the request using the access token secret.
- 4.
If the signature is valid, the SP talks to the policy decision endpoint of the AM, passing the access token and the SP handle. The request must be digitally signed by the corresponding access token secret.
- 5.
The AM first validates the request, next evaluates the corresponding policies set by the user or the resource owner, and then sends the decision to the SP.
- 6.
If the decision is a Deny, the location of the terms is returned to the SP, and the SP returns the location to the consumer with a 403 HTTP status code.
- 7.
The consumer requests the terms by talking to the terms endpoint hosted in the AM. The request includes the consumer key, signed with the consumer secret.
- 8.
When the consumer receives the terms, it evaluates them and talks to the AM with additional information to prove its legitimacy. This request includes the consumer key and is signed with the consumer secret.
- 9.
The AM evaluates the additional information and claims provided by the consumer. If those meet the required criteria, the AM creates an agreement resource and sends the location of the agreement resource to the consumer.
- 10.
If this requires the user’s consent, the AM must send it for the user’s approval before sending the location of the agreement resource.
- 11.
Once the consumer receives the location of the agreement resource, it can talk to the corresponding endpoint hosted in the AM and get the agreement resource to see the status.
- 1.
The consumer tries to access the protected resource at the SP with its access token, signed with the access token secret.
- 2.
The SP talks to the AM and gets the secret key corresponding to the consumer’s access token. If required, the SP can store it locally.
- 3.
The SP validates the signature of the request using the access token secret.
- 4.
If the signature is valid, the SP talks to the policy decision endpoint of the AM, passing the access token and SP handle, signed with the corresponding access token secret.
- 5.
The AM first validates the request, next evaluates the corresponding policies set by the user or the resource owner, and then sends the decision to the SP.
- 6.
If the decision is an Allow from the AM, the SP returns the requested resource to the corresponding consumer.
- 7.The SP can cache the decision from the AM. Subsequent calls by the same consumer for the resource can utilize the cache instead of going to the AM.
UMA and OAuth
Over the years, ProtectServe evolved into UMA. ProtectServe used OAuth 1.0 to protect its APIs, and UMA moved from OAuth 1.0 to OAuth WRAP to OAuth 2.0. The UMA specification, which was developed under the Kantara Initiative for almost three years, was submitted to the IETF OAuth working group on July 9, 2011, as a draft recommendation for a user-managed data access protocol.
UMA 1.0 Architecture
UMA 1.0 Phases
The first phase of UMA1 is to protect the resource. The resource owner initiates this phase by introducing the resource servers associated with him or her to a centralized authorization server.
The client initiates the second phase when it wants to access a protected resource. The client talks to the authorization server and obtains the required level of authorization to access the protected resource that’s hosted in the resource server. Finally, in the third phase, the client directly accesses the protected resource.
UMA Phase 1: Protecting a Resource
Resources are owned by the resource owner and may be at different resource servers. Let’s look at an example. Suppose my photos are with Flickr, my calendar is with Google, and my friend list is with Facebook. How can I protect all these resources, which are distributed across different resource servers, with a centralized authorization server? The first step is to introduce the centralized authorization server to Flickr, Google, and Facebook—to all the resource servers. The resource owner must do this. The resource owner can log in to each resource server and provide the authorization server configuration endpoint to each of them. The authorization server must provide its configuration data in JSON format.
Once the resource server is introduced to the authorization server via its configuration data endpoint, the resource server can talk to the dynamic client registration (RFC 7591) endpoint (dynamic_client_endpoint) to register it at the authorization server.
Note
You aren’t required to use the Dynamic Client Registration API. Resource servers can use any method they prefer to register at the authorization server. The registration at the authorization server is one-time operation, not per resource owner. If a given resource server has already been registered with a given authorization server, then it doesn’t need to register again at the authorization server when the same authorization server is introduced by a different resource owner.
Note
The scope of the PAT token must be http://docs.kantarainitiative.org/uma/scopes/prot.json. This must be included in the scope value of the authorization code grant request.
UMA Phase 2: Getting Authorization
Note
You aren’t required to use the Dynamic Client Registration API. The client can use any method it prefers to register at the authorization server. The registration at the authorization server is one-time operation and not per resource server or per requesting party. If a given client has already been registered with a given authorization server, then it doesn’t need to register again when a different requesting party uses the same authorization server. The AAT is per client per requesting party per authorization server and is independent from the resource server.
Note
The RPT endpoint is defined under the rpt_endpoint attribute of the authorization server’s configuration.
When the client is in possession of the initial RPT, it can once again try to access the resource. In this case, the RPT goes as an OAuth 2.0 bearer token in the HTTP Authorization header. Now the resource server extracts the RPT from the resource request and talks to the Introspection API exposed by the authorization server. The Introspection API can tell whether the RPT is valid and, if it is, the permissions associated with it. In this case, because you’re still using the initial RPT, there are no permissions associated with it, even though it’s a valid token.
Note
The Introspection API exposed by the authorization server is OAuth 2.0 protected. The resource server must present a valid PAT to access it. The PAT is another bearer token that goes in the HTTP Authorization header.
If the RPT doesn’t have enough permission to access the resource, the resource server talks to the Client Requested Permission Registration API exposed by the authorization server and registers the required set of permissions to access the desired resource. When permission registration is successfully completed, the authorization server returns a permission ticket identifier.
Note
The Client Requested Permission Registration endpoint is defined under the permission_registration_endpoint attribute in the authorization server’s configuration. This endpoint, which is part of the UMA Protection API, is secured with OAuth 2.0. The resource server must present a valid PAT to access the API.
Note
The RPT endpoint of the authorization server is secured with OAuth 2.0. To access the RPT endpoint, the client must use an AAT in the HTTP Authorization header as the OAuth bearer token.
UMA Phase 3: Accessing the Protected Resource
At the end of phase 2, the client got access to a valid RPT with the required set of permissions. Now the client can use it to access the protected resource. The resource server again uses the Introspection API exposed by the authorization server to check the validity of the RPT. If the token is valid and has the required set of permissions, the corresponding resource is returned to the client.
UMA APIs
Protection API
The Protection API is the interface exposed to the resource server by the authorization server. It consists of three subelements: the OAuth Resource Set Registration endpoint,2 the Client Requested Permission Registration endpoint, and the OAuth Token Introspection (RFC 7662) endpoint.
This JSON message is also known as the resource description. Each UMA authorization server must present a REST API to create (POST), update (PUT), list (GET), and delete (DELETE) resource set descriptions. The resource server can utilize this endpoint either during phase 1 or in an ongoing manner.
The resource server accesses the Client Requested Permission Registration endpoint during phase 2 of UMA flow. The resource server uses this API to inform the authorization server about the level of permissions required for the client to access the desired resource. The resource server uses the Introspection API to check the validity of the RPT.
Authorization API
The Authorization API is the interface between the client and the authorization server. The main responsibility of this API is to issue RPTs.