Abstract

This document defines the User-Managed Access (UMA) 1.0 core protocol. This protocol provides a method for users to control access to their protected resources, residing on any number of host sites, through an authorization manager that makes access decisions based on user policy.

Status

This document is a product of the User-Managed Access Work Group. It is currently under active development on github; please see github or the Working Drafts area of this wiki for current status, as the version on this wiki may be a snapshot of older progress. See the Change History at the end of this document for its revision number.

Editors

• Paul Bryan
• Maciej Machulak
• Eve Maler

Intellectual Property Notice

The User-Managed Access Work Group operates under Kantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND) and the publication of this document is governed by the policies outlined in this option.

Table of Contents

Introduction

The User-Managed Access (UMA) 1.0 core protocol provides a method, based on [OAuth20], for users to control access to their protected resources, residing on any number of host sites, through an authorization manager that makes access decisions based on user policy.

For example, a web user (authorizing user) can authorize a web app (requester) to gain one-time or ongoing access to a resource containing his home address stored at a "personal data store" service (host), by telling the host to act on access decisions made by his authorization decision-making service (authorization manager or AM). The requesting party might be an e-commerce company whose site is acting on behalf of the user himself to assist him in arranging for shipping a purchased item, or it might be his friend who is using an online address book service to collect addresses, or it might be a survey company that uses an online service to compile population demographics.

In enterprise settings, application access management often involves letting back-office applications serve only as policy enforcement points (PEPs), depending entirely on access decisions coming from a central policy decision point (PDP) to govern the access they give to requesters. This separation eases auditing and allows policy administration to scale in several dimensions. UMA makes use of this separation, letting the authorizing user serve as a policy administrator crafting authorization strategies on his or her own behalf.

The UMA protocol profiles and extends [OAuth20], applying two instances of OAuth flow patterns among the entities.

First, UMA allows a host to trust an AM to which it has been introduced dynamically. To accomplish this, the host acquires a host access token that it can subsequently use in interacting with a set of host-specific protected resources at the AM. These resources can be considered an OAuth-protected set of APIs. Thus, when the host accesses these resources, it acts in the role of an OAuth client while the AM acts in the dual roles of an OAuth resource server and authorization server.

Subsequently, when a requester interacts with the AM and the host in the course of getting access to some protected resource on the host, the requester acts in the role of an OAuth client to get and use a requester access token; the host acts in the role of an OAuth resource server; and the AM acts in the role of an OAuth authorization server.

UMA has the following major steps:

1. The authorizing user registers a host at an AM
2. The requester gets an access token from the AM
3. The requester wields the access token at the host to gain access

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119].

Terminology

authorizing user: An UMA-defined variant of an [OAuth20] resource owner; a web user who configures an authorization manager with policies that control how it makes access decisions when a requester attempts to access a protected resource at a host.

authorization manager (AM): An UMA-defined variant of an [OAuth20] authorization server that carries out an authorizing user's policies governing access to a protected resource.

protected resource: An access-restricted resource at a host.

host: An UMA-defined variant of an [OAuth20] resource server that enforces access to the protected resources it hosts, as decided by an authorization manager.

host access token: An access token symbolizing the authorizing user's consent for a host to trust a particular authorization manager for access decisions about resources hosted there.

claim: A statement (in the sense of [IDCclaim]). Claims are conveyed by a requester on behalf of a requesting party to an authorization manager in an attempt to satisfy an authorizing user's policy.

requester: An UMA-defined variant of [OAuth20] client that seeks access to a protected resource.

requester access token: An access token symbolizing the authorizing user's consent for a requester's access to particular resources at a host.

requesting party: A web user, or a corporation (or other legal person), that uses a requester to seek access to a protected resource.

Step 1: Authorizing user registers host at AM

In order for a host to be able to delegate authorization to an AM, the authorizing user must introduce the host to the AM. The result is as follows:

• The host has received metadata about the AM, such as [OAuth20] endpoints.
• The host has received an OAuth access token (known as the host access token) that represents the authorizing user's approval for the host to use this AM in protecting resources. This token is used when the host makes requests at host-specific AM endpoints.
• The AM has received a list of protected resources on the host for which it is supposed to control access on behalf of the user.

The following substeps are performed in order to achieve these results:

1. The host looks up the AM metadata and learns about API endpoints and supported formats.
2. The host obtains OAuth client credentials and the resource registration API endpoint from the AM. (Unnecessary if the host has preregistered with the AM.)
3. The host obtains an access token from the AM with the authorizing user's consent, by following the OAuth 2.0 web server flow.
4. Using the AM's resource registration API, the host registers the authorizing user's resources to be protected.

Host looks up AM metadata

The host must look up the metadata of the AM before they can begin interacting. The authorizing user might provide the AM's location to get the host started in this process, for example typing a URL into a web form field or clicking a button, or the host might have been configured to work with a single AM without requiring any user input. The exact process is beyond the scope of this specification, and it is up to the host to choose a method.

From the data provided, discovered, or configured, the host then has to retrieve the hostmeta document as described in section 2 of [hostmeta]. For example if the user supplied "am.example.com" as the authorization manager's domain, the host creates the URL "https://am.example.com/.well-known/host-meta" and performs a GET request on it.

The AM MUST provide a XRD 1.0 formatted document at the hostmeta location, documenting the following:

• One set of OAuth 2.0 URI endpoints for the host to use
• One set of OAuth 2.0 URI endpoints for requesters to use, which the host will need to provide to unauthorized requesters
• Optionally, the location of the token validation API for the host to use in validating access tokens received from a requester in step 3
• At least one access token format it produces
• Any claims formats it supports

Properties for access token and claim format information:

Link relationships for the OAuth endpoints for the host:

Link relationships for the OAuth endpoints for requesters:

For example:

<!-- Applies to both hosts and requesters -->
<Property type="http://kantarainitiative.org/confluence/display/uma/token_formats">saml</Property>
<Property type="http://kantarainitiative.org/confluence/display/uma/claim_formats">json</Property>

<!-- Host "authorization API" -->
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_token_uri"
      href="https://am.example.com/host/token_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_user_uri"
      href="https://am.example.com/host/user_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_resource_details_uri"
      href="https://am.example.com/host/resource_details_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_token_validation_uri"
      href="https://am.example.com/host/token_validation_uri"></Link>

<!-- Requester token-getting endpoints -->
<Link rel="http://kantarainitiative.org/confluence/display/uma/req_token_uri"
      href="https://am.example.com/requester/token_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/req_user_uri"
      href="https://am.example.com/requester/user_uri"></Link>

Host obtains OAuth client credentials and related information

To Be Supplied Make sure to record issue about whether to supply resource registration API endpoint here. Rationale for doing so: Allows endpoint to be specific to each host (and independent of any users that use that host) Most efficient possible way to convey such an endpoint to the host during dynamic association

Host obtains authorizing user's consent to trust AM for access decisions

The host gets a host access token from the AM that represents the approval of the authorizing user for the host to trust this AM for protecting the resources it manages for this user.

NOTE: The host is free to offer the option to protect any subset of the user's resources using different AMs or other means entirely; any such partitioning is outside the scope of this specification.

The host MUST use the [OAuth20] web server flow (@@TBS: subsequently profile it to use UMA recursively for claims-getting purposes?), utilizing the host_user_uri and host_token_uri endpoints. The host acts in the role of an OAuth client; the authorizing user acts in the role of an OAuth end-user resource owner; and the AM acts in the role of an OAuth authorization server.

If the host has not already received client credentials from the AM prior to entering the web server flow, it MUST wield the client_id "uma_host_anonymous_client" and no client_secret (@@TBS: Explain how to do dynamic association to get unique client credentials).

Host supplies resource details to AM

Once the host has received an access token, it MAY, immediately or at any time until user authorization is revoked, wield the token at the AM's host_resource_details_uri endpoint to POST an XRD (@@TBS: JRD eventually?) structure to the AM describing the authorizing user's resources currently managed at that host in order to assist the AM in letting the authorizing user configure policies specific to those resources.

Step 2: Requester gets access token from AM

This step involves the AM and requester in the role of OAuth authorization server and client respectively. If the requester is acting on behalf of a requesting party that is a corporation or other legal person, or a natural person who is not the same as the authorizing user, it MUST use one of the "autonomous client" profiles in this phase (@@TBS: examine whether special-case autonomous profiles need to be developed). If the requester is acting on behalf of a natural person who is the same person as the authorizing party, it MUST use one of the "user delegation" profiles in this phase.

This step extends OAuth to add a third possible response from the AM in addition to successful vs. unsuccessful access token responses: the third option is to ask for more information from the requesting party, in the form of claims. It also profiles OAuth (all of its relevant profiles) to specify how the requester must supply scope values in asking for authorization.

This step has the following substeps:

1. Requester attempts to access resource at host and is given AM's requester_token_uri endpoint
2. Requester visits this endpoint, providing its desired scope of access
3. AM either provides access token, rejects authorization, or asks requester for claims
4. Requester provides claims as requested, until access token request either succeeds or fails definitively

The substep detail is as follows.

If the requester knows, by whatever means, the access token URL for the AM that is protecting the desired resource without first approaching the host, it MAY proceed directly to that URL. Alternatively, it MAY attempt to access the resource directly at the host; if it does not present an access token, the host MUST respond with a challenge, using the "HTTP 401 Unauthorized" code and providing the requester_token_uri endpoint (and the requester_user_uri endpoint if appropriate) in the HTTP header "WWW-Authenticate".

The requester submits a GET request to the access token URL, providing the desired scope of access in the "scope" parameter. The value of this parameter is a URL-encoded JSON array of one or more objects, each consisting of at least two members: a "method" string with an HTTP access method value and a "uri" string with a resource URI value (which MAY have a "*" as the last path component in order to indicate all resources available in that directory on the host). If any additional members are present, they do not affect the interpretation of these two.

For example, the following "scope" parameter value describes two different resources and different access methods for them, for which a single refresh token is sought (the example is not URL-encoded, for readability):

[{"method": "GET", "uri": "http://example.com/foo"},
{"method": "POST", "uri": "http://example.com/*"}]

The requester performs a GET on the access token URL, using the standard HTTP "Accept" header to express the acceptable media type(s) of any claims-required list. The AM responds in one of three ways:

• If the AM requires no claims from the requester in order to grant authorization based on user policy, it responds with a successful access token response. The response MUST include a refresh token URL for the requester to attempt to use subsequently in reusing this authorization to generate future access tokens.

• If the requester is definitively not authorized according to user policy, the AM responds with an unsuccessful access token response and the authorization negotiation phase ends.

• If user policy demands more information from the requester, the AM responds with a claims-required response containing a claims-required list. The list SHOULD use the media type that was indicated by the requester as acceptable. (@@TBS: We don't want claims to have to be supplied every time for an access token, just a refresh token or equivalent. How to do this?)

On receiving a claims-required list, the requester performs a POST to the authorization negotiation URL supplying a claims document, specifying its type in the "Content-Type" header. The AM rejects the document if it does not recognize its type. If the AM accepts the document, it responds with a successful or unsuccessful access token response as detailed above, or with another claims-required response.

If the access token request is successful, the access token supplied MUST be in one of the formats contemporaneously advertised in the AM's host-meta metadata.

This specification does not define the formats of required-claims lists and claims documents. It may ultimately put minimum conformance requirements on requesters and AMs to handle particular claim formats defined in other specifications, as well as specifying requirements that claim formats seeking consideration for use in UMA must meet.

Step 3: Requester wields access token at host to gain access

This step involves the requester and host in the role of OAuth client and resource server respectively. This step extends OAuth to allow the host to validate the token at the authorization manager. This step has the following substeps:

1. Requester presents requester access token in attempting to access resource
2. Host either wields host access token at AM's token validation endpoint to ask for validation or validates the token locally
3. Host either allows access or generates an error

The substep detail is as follows.

The requester presents the requester access token to the host in attempting to access the desired resource, as defined in OAuth.

The host either validates the token locally or wields its host access token in POSTing a validation request to the AM's token validation endpoint, providing the requester access token plus a description of the resource and method attempted.

The AM responds in one of two ways: the token is valid, or the token is invalid. Correspondingly, the host either allows access or rejects the requesters' attempt. The requester is free to seek authorization or to refresh its access token at the AM if it feels the rejection was in error.

(@@TBS: Obviously much detail still needed here.)

Security Considerations

@@TODO: Provide commentary on any requirements layered on the forthcoming OAuth security considerations section; discuss UMA-layer implications for more meaningful authentication of requesters/requesting parties; discuss implications of user-mediated AM/host trust model; ...

References

[RFC2119]
http://www.ietf.org/rfc/rfc2119.txt

[OAuth20]
http://tools.ietf.org/html/draft-ietf-oauth-v2

[hostmeta]
http://tools.ietf.org/html/draft-hammer-hostmeta

[IDCclaim]
http://wiki.idcommons.net/Claim

Change History