Introduction

The User-Managed Access (UMA) 1.0 core 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.

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). 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.

UMA has the following major steps:

1. User registers host at an authorization manager (using [hostmeta], and profiling [WRAP] to define how a host accepts an authorizing user's chosen authorization manager as an access decision-maker)
2. Requester gets access token from authorization manager (extending WRAP to define how the requester can satisfy user policy by providing additional information to the AM)
3. Requester wields access token at host to gain access (extending WRAP to allow the host to validate the token at the authorization manager)

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

Terms are capitalized here for clarity of definition, but are lowercase in the main body of the specification for readability. Note that in this specification, the word "profile" is used not only to refer to WRAP client profiles, but also for the result of choosing one out of several options in a referenced specification in order to increase interoperability.

Authorizing User: 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 a WRAP Authorization Server that carries out an Authorizing User's policies governing access to a Protected Resource.

Protected Resource: A resource (at a Host) whose access is restricted. (Note that this differs from WRAP's definition of the same term.)

Host: An UMA-defined variant of, respectively, a WRAP Protected Resource and WRAP Client, that enforces access to the Protected Resources it hosts, as decided by an Authorization Manager.

Claim: A statement (in the sense of IDCclaim) conveyed by a Requester on behalf of a Requesting Party to an Authorization Manager in an attempt to satisfy user policy.

Requester: An UMA-defined variant of a WRAP Client that seeks access to a Protected Resource.

Requesting Party: A web user, or a corporation (or other legal person), that uses a Requester to seek access to a Protected Resource.

URLs

Token Validation URL: The URL at an Authorization Manager that a Host uses to validate an access token.

Authorization Bootstrap URL: The URL at an Authorization Manager that a Requester uses to discover the Authorization Negotiation URL to use.

Authorization Negotiation URL: The URL at an Authorization Manager at which a Requester negotiates for authorization and receives refresh tokens and initial access tokens; an UMA-defined variant of the WRAP Access Token URL.

Protocol Steps

Step 1: User registers host at AM

This step involves an embedded instance of WRAP within the main UMA flow. It profiles WRAP to define how a host comes to trust an authorization manager chosen by the authorizing user, and how it learns which access token formats are supported. The user introduces the host (as a WRAP Client) to the AM (as a WRAP Authorization Server) using any of the "user delegated" profiles. This step has the following substeps:

1. User provisions host with AM location (out of band)
2. Host constructs hostmeta metadata URL as necessary
3. Host retrieves hostmeta metadata and learns AM's user authorization URL
4. Host, AM, and user engage in a WRAP user-delegated profile interaction to establish user's authorization for host to use AM to protect resources hosted there

The substep detail is as follows.

In an out-of-band fashion, an authorizing user provides a host with enough information for it to construct the well-known location for the AM's "host-meta" metadata (as defined in [hostmeta]). For example, an authorizing user may provide the URL "https://am.example.com" to a host web app by typing into a text field on a web page, transmitting through an information card, or conveying on a physical magnetic-stripe card.

The host then constructs the well-known location from the information it was given if the information was not itself the well-known location, for example, "https://am.example.com/.well-known/host-meta", and obtains the AM's metadata from this location.

The AM MUST provide metadata at that location that offers a WRAP user authorization URL, documents the one or more access token formats that the AM generates, and provides an authorization bootstrap URL and token validation URL, in the following general pattern:

<Link rel="http://tools.ietf.org/html/draft-hardt-oauth-01"
      href="https://am.example.com/wrapuserauthz" />

<Link rel="http://kantarainitiative.org/confluence/display/uma/AccessTokenFormats"
      href="http://docs.oasis-open.org/security/saml/v2.0/sstc-saml-approved-errata-2.0.pdf" />

<Link rel="http://kantarainitiative.org/confluence/display/uma/AuthzBootstrapURL"
      href="https://am.example.com/umaauthzbootstrap" />

<Link rel="http://kantarainitiative.org/confluence/display/uma/TokenValidationURL"
      href="https://am.example.com/umatokenvalidation" />

The user authorization URL, authorization bootstrap URL, and token validation URL MUST be HTTPS URLs.

The host MUST follow one of the WRAP "user delegation" profiles in obtaining the user's authorization to use that AM to protect the resources it hosts on behalf of that user.

Step 2: Requester gets access token from AM

This step involves the AM and requester in the role of WRAP Authorization Server and Client respectively, using the "client account and password" profile with anonymous credentials. This step extends WRAP to allow for negotiation prior to authorization; specifically, the extensions allow the AM to specify claims it needs from the requester and for the requester to make the appropriate responses. It also profiles WRAP to specify how the requester must supply wrap_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 authorization bootstrap URL
2. Requester visits AM's authorization bootstrap URL, providing desired scope of access, and learns authorization negotiation URL
3. Through authorization negotiation resource, AM either provides access token (and refresh token), rejects authorization, or asks requester for claims
4. Requester provides claims if requested, until access token request either succeeds or fails definitively

The substep detail is as follows.

If the requester knows, by whatever means, the authorization bootstrap 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 WRAP challenge, using the "HTTP 401 Unauthorized" code and the HTTP header "WWW-Authenticate: WRAP" and providing the authorization bootstrap URL.

The requester submits a GET request to the authorization bootstrap URL, providing the desired scope of access in the "wrap_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. If any additional members are present, they do not affect the interpretation of these two.

For example, the following "wrap_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/bar"}]

The AM responds with an authorization negotiation URL for a short-lived resource created specifically for this attempt to get authorization to access this particular set of resources using these particular methods. The authorization negotiation URL MUST be an HTTPS URL. To manage security risks, the AM MAY delete the resource at any time, requiring the requester to start at the beginning even if the negotiation was not successfully concluded, but it is assumed that the negotiation will be conducted with alacrity.

The requester performs a GET on the authorization negotiation 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 WRAP 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 WRAP 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 in its initial GET.

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 WRAP Client and Protected Resource respectively. This step extends WRAP to allow the host to validate the token at the authorization manager. This step has the following substeps:

1. Requester presents access token in attempting to access resource
2. Host uses AM's token validation URL to ask for validation
3. Host either allows access or generates an error

The substep detail is as follows.

The requester presents the access token to the host in attempting to access the desired resource, as defined in WRAP. The host performs a POST of the access token to the AM's token validation URL, providing a description of the resource and method attempted to the AM. 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.

References

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

[WRAP]
http://tools.ietf.org/html/draft-hardt-oauth-01

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