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
2. Requester gets access token from authorization manager
3. Requester wields access token at 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

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] (all WRAP references are temporary; OAuth 2.0 is the goal) 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.

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 and claim formats that the AM generates, and provides an access token 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">
      <Title>WRAP User Authorization URL</Title>
</Link>

<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">
      <Title>UMA Access Token Format produced by this AM</Title>
</Link>

<Link rel="http://kantarainitiative.org/confluence/display/uma/ClaimFormats"
      href="http://www.json.org">
      <Title>UMA Claim Format produced by this AM</Title>
</Link>

<Link rel="http://kantarainitiative.org/confluence/display/uma/ClaimFormats"
      href="http://docs.oasis-open.org/security/saml/v2.0/sstc-saml-approved-errata-2.0.pdf">
      <Title> UMA Claim Format produced by this AM</Title>
</Link>

<Link rel="http://tools.ietf.org/html/draft-hardt-oauth-01"
      href="https://am.example.com/wrapaccesstokenurl">
      <Title>WRAP Access Token URL</Title>
</Link>

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

The user authorization 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. If the host uses the token validation URL to offload token validation in step 3, it will use any access token acquired in this step to make an authorized call to that URL.

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. If the requester is acting on behalf of a requesting party that is a corporation or other legal person, it MUST use one of the "autonomous client" profiles in this phase. If the requester is acting on behalf of a requesting party that is a human being, it MUST use one of the "user delegation" profiles in this phase.

This step extends WRAP to add a third possible response from the AM (WRAP Authorization Server) 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 WRAP (all of its relevant profiles) to specify how the requester must supply wrap_scope values in asking for authorization.

This step has the following substeps:

1. (optional) Requester attempts to access resource at host and is given AM's access token URL
2. Requester visits AM's access token URL, providing desired scope of access
3. AM either provides access token (and refresh 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 WRAP challenge, using the "HTTP 401 Unauthorized" code and the HTTP header "WWW-Authenticate: WRAP" and providing the access token URL.

The requester submits a GET request to the access token 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 (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 "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/*"}]

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 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 either uses AM's token validation URL 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 access token to the host in attempting to access the desired resource, as defined in WRAP. The host either validates the token locally or performs a POST of the access token to the AM's token validation URL (wielding the access token it acquired in step 1 to show that the request is authorized), providing 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.

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

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