Federated Authorization for User-Managed Access (UMA) 2.0

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

Unless otherwise noted, all parameter names and values are case sensitive. JSON [RFC7159] data structures defined in this specification MAY contain extension parameters that are not defined in this specification. Any entity receiving or retrieving a JSON data structure SHOULD ignore extension parameters it is unable to understand. Extension names that are unprotected from collisions are outside the scope of this specification.

The UMA grant defined in [UMAGrant] enhances the abstract protocol flow of OAuth. This specification enhances the UMA grant by defining formal communications between the UMA-enabled authorization server and resource server as they act on behalf of the resource owner, responding to authorization and resource requests, respectively, by a client that is acting on behalf of a requesting party.

A summary of UMA 2.0 communications, combining the UMA grant with federated authorization, is shown in Figure 1.

                                             +------------------+
                                             |     resource     |
       +------------manage (out of scope)----|       owner      |
       |                                     +------------------+
       |                                               |
       |                protection                     |
       |                API access                  control
       |                token (PAT)              (out of scope)
       |                                               |
       v                                               v
+------------+                    +----------+------------------+
|            |                    |protection|                  |
|  resource  |                    |   API    |   authorization  |
|   server   |<-----protect-------| (needs   |      server      |
|            |                    |   PAT)   |                  |
+------------+                    +----------+------------------+
| protected  |                               |        UMA       |
| resource   |                               |       grant      |
|(needs RPT) |          requesting           |  (PCT optional)  |
+------------+          party token          +------------------+
       ^                  (RPT)               ^  persisted   ^
       |                                      |   claims     |
       |                                    push   token     |
       |                                   claim   (PCT)     |
       |                                   tokens         interact
       |                                      +--------+    for
       +------------access--------------------| client |   claims
                                              +--------+  gathering
                                                +---------------+
                                                |  requesting   |
                                                |     party     |
                                                +---------------+

This specification uses all of the terms and concepts in [UMAGrant]. This figure introduces the following new concepts:

protection API

The API presented by the authorization server to the resource server, defined in this specification. This API is OAuth-protected.

protection API access token (PAT)

An OAuth access token with the scope uma_protection, used by the resource server as a client of the authorization server's protection API. The resource owner involved in the UMA grant takes the role of the resource owner authorizing issuance of the PAT.

This specification is designed for use with HTTP [RFC2616], and for interoperability and security in the context of loosely coupled services and applications operated by independent parties in independent domains. The use of UMA over any protocol other than HTTP is undefined. In such circumstances, it is RECOMMENDED to define profiles or extensions to achieve interoperability among independent implementations (see Section 4 of [UMAGrant]).

The authorization server MUST use TLS protection over its protection API endpoints, as governed by [BCP195], which discusses deployment and adoption characteristics of different TLS versions.

The authorization server MUST use OAuth and require a PAT to secure its protection API endpoints.

As defined in [UMAGrant], the resource owner -- the entity here authorizing PAT issuance -- MAY be an end-user (natural person) or a non-human entity treated as a person for limited legal purposes (legal person), such as a corporation. A PAT is unique to a resource owner, resource server used for resource management, and authorization server used for protection of those resources. The issuance of the PAT represents the authorization of the resource owner for the resource server to use the authorization server for protecting those resources.

Different grant types for PAT issuance may be appropriate for different types of resource owners; for example, the client credentials grant is useful in the case of an organization acting as a resource owner, whereas an interactive grant type is typically more appropriate for capturing the approval of an end-user resource owner. Where an identity token is desired in addition to an access token, it is RECOMMENDED to use [OIDCCore] in addition.

Federation of authorization for the UMA grant delivers a conceptual separation of responsibility and authority:

• The resource owner can control access to resources residing at multiple resource servers from a single authorization server, by virtue of authorizing PAT issuance for each resource server. Any one resource server MAY be operated by a party different from the one operating the authorization server.
• The resource server defines the boundaries of resources and the scopes available to each resource, and interprets how clients' resource requests map to permission requests, by virtue of being the publisher of the API being protected and using the protection API to communicate to the authorization server.
• The resource owner works with the authorization server to configure policy conditions (authorization grant rules), which the authorization server executes in the process of issuing access tokens. The authorization process makes use of claims gathered from the requesting party and client in order to satisfy all operative operative policy conditions. (See Section 1.4.1.)

The separation of authorization decision making and authorization enforcement is similar to the architectural separation often used in enterprises between policy decision points and policy enforcement points. However, note that the resource server MAY apply additional authorization controls beyond those imposed by the authorization server. For example, even if an RPT provides sufficient permissions for a particular case, the resource server can choose to bar access to certain additional requesting parties.

Practical control of access among loosely coupled parties typically requires more than just messaging protocols. It is outside the scope of this specification to define more than the technical contract between UMA-conforming entities. Laws may govern authorization-granting relationships. It is RECOMMENDED for the resource owner, authorization server, and resource server to establish agreements about which parties are responsible for establishing and maintaining authorization grant rules and other authorization rules on a legal or contractual level, and parties operating entities claiming to be UMA-conforming should provide documentation of rights and obligations between and among them. See Section 4 of [UMAGrant] for more information.

1.4.1 Policy Setting and Time-to-Live Management

The protection API defines the following endpoints:

• Resource registration endpoint as defined in Section 3. The API available at this endpoint provides a means for the resource server to put resources under the protection of an authorization server on behalf of the resource owner and manage them over time. The resource server uses this endpoint in an ongoing fashion, but generally registers a resource initially during the request-to-grant phase.
• Permission endpoint as defined in Section 4. This endpoint provides a means for the resource server to request a set of one or more permissions on behalf of the client based on the client's resource request when that request is unaccompanied by a token or is accompanied by an RPT that is insufficient for access to that resource. The resource server uses this endpoint during the request-to-grant phase.
• OPTIONAL token introspection endpoint as defined in [RFC7662] as extended in Section 5. This endpoint provides a means for the resource server to introspect the RPT. The resource server uses this endpoint during the grant-to-resource phase.

Use of these endpoints assumes that the resource server has acquired OAuth client credentials from the authorization server by static or dynamic means, and has a valid PAT.

The authorization server SHOULD respond to each request from the resource server unless it detects a security concern, such as a suspected denial of service attack that can be mitigated by rate limiting.

Note: The resource server generally requires access to the protection API when an end-user resource owner is not available ("offline" access). Thus, the authorization server needs to manage the PAT in a way that ensures this outcome.

The authorization server MUST declare its endpoints in the discovery document (see Section 2).

1.5.1 Permissions

A resource description is a JSON document that describes the characteristics of a resource sufficiently for an authorization server to protect it. A resource description has the following parameters:

scopes

REQUIRED. An array of strings, serving as scope identifiers, indicating the available scopes for this resource. Any of the strings MAY be either a plain string or a URI. While a URI MAY resolve to a scope description document as defined in Section 3.1.1, and thus scope description documents are possible to standardize and reference publicly, the authorization server is not expected to resolve scope description details at resource registration time or at any other run-time requirement. The resource server and authorization server are presumed to have negotiated any required interpretation of scope handling out of band.

description

OPTIONAL. A human-readable string describing the resource at length. The authorization server MAY use this description in any user interface it presents to a resource owner, for example, for resource protection monitoring or policy setting.

icon_uri

OPTIONAL. A URI for a graphic icon representing the resource. The authorization server MAY use the referenced icon in any user interface it presents to a resource owner, for example, for resource protection monitoring or policy setting.

name

OPTIONAL. A human-readable string naming the resource. The authorization server MAY use this name in any user interface it presents to a resource owner, for example, for resource protection monitoring or policy setting.

type

OPTIONAL. A string identifying the semantics of the resource. For example, if the resource is an identity claim that leverages standardized claim semantics for "verified email address", the value of this parameter could be an identifying URI for this claim. The authorization server MAY use this information in processing information about the resource or displaying information about it in any user interface it presents to a resource owner.

The resource server MAY encode human-readable strings using the pattern described in Section 2.2 of [RFC7591] for representing multiple languages and scripts, where language tags are added delimited by a "#" character. It is OPTIONAL for the authorization server to make use of this pattern, if present in registered resources, for run-time dynamic string display effects.

For example, this description characterizes a resource (a photo album) that can potentially be viewed or printed; the scope URI points to a scope description as defined in Section 3.1.1:

{  
   "name":"Photo Album",
   "icon_uri":"http://www.example.com/icons/flower.png",
   "scopes":[  
      "view",
      "http://photoz.example.com/dev/scopes/print"
   ],
   "type":"http://www.example.com/rsrcs/photoalbum"
}

3.1.1 Scope Description

{  
   "name":"View",
   "icon_uri":"http://www.example.com/icons/reading-glasses"
}

The authorization server is REQUIRED to support the following five registration options; any other operations are undefined by this specification. Here, rreguri stands for the resource registration endpoint and _id stands for the authorization server-assigned identifier for the web resource corresponding to the resource at the time it was created, included within the URL returned in the Location header. Each operation is defined in its own section below.

• Create resource description: POST rreguri/
• Read resource description: GET rreguri/_id
• Update resource description: PUT rreguri/_id
• Delete resource description: DELETE rreguri/_id
• List resource descriptions: GET rreguri/

Within the JSON body of a successful response, the authorization server includes common parameters, possibly in addition to method-specific parameters, as follows:

_id

REQUIRED (except for the List method). A string value repeating the authorization server-defined identifier for the web resource corresponding to the resource. Its appearance in the body makes it readily available as an identifier for various protected-resource management tasks.

user_access_policy_uri

OPTIONAL. A URI that allows the resource server to redirect an end-user resource owner to a specific user interface within the authorization server where the resource owner can immediately set or modify access policies subsequent to the resource registration action just completed. The authorization server is free to choose the targeted user interface, for example, in the case of a deletion action, enabling the resource server to direct the end-user to a policy-setting interface for an overall "folder" of resources where the deleted resource once resided.

If the request to the resource registration endpoint is incorrect, then the authorization server instead responds with an error message by including one of the following error codes with the response (see Section 6):

not_found

The resource requested from the authorization server cannot be found. The authorization server MUST respond with HTTP 404 (Not Found) status code.

unsupported_method_type

The resource server request used an unsupported HTTP method. The authorization server MUST respond with the HTTP 405 (Method Not Allowed) status code.

3.2.1 Create Resource Description

POST /rs/ HTTP/1.1 Content-Type: application/json
Authorization: Bearer MHg3OUZEQkZBMjcx
...
{  
   "name":"Tweedl Social Service",
   "icon_uri":"http://www.example.com/icons/sharesocial.png",
   "scopes":[  
      "read-public",
      "post-updates",
      "read-private",
      "http://www.example.com/scopes/all"
   ],
   "type":"http://www.example.com/rsrcs/socialstream/140-compatible"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /rs/KX3A-39WE
...
{  
   "_id":"KX3A-39WE",
   "user_access_policy_uri":"http://as.example.com/rs/222/resource/KX3A-39WE/policy"
}

3.2.2 Read Resource Description

GET /rs/KX3A-39WE HTTP/1.1
Authorization: Bearer MHg3OUZEQkZBMjcx
...

HTTP/1.1 200 OK
Content-Type: application/json
...
{  
   "_id":"KX3A-39WE",
   "name":"Tweedl Social Service",
   "icon_uri":"http://www.example.com/icons/sharesocial.png",
   "scopes":[  
      "read-public",
      "post-updates",
      "read-private",
      "http://www.example.com/scopes/all"
   ],
   "type":"http://www.example.com/rsrcs/socialstream/140-compatible"
}

3.2.3 Update Resource Description

PUT /rs/9UQU-DUWW HTTP/1.1
Content-Type: application/json
Authorization: Bearer 204c69636b6c69
...
{  
   "name":"Photo Album",
   "icon_uri":"http://www.example.com/icons/sky.png",
   "scopes":[  
      "http://photoz.example.com/dev/scopes/view",
      "public-read"
   ],
   "type":"http://www.example.com/rsrcs/photoalbum"
}

HTTP/1.1 200 OK
...
{  
   "_id":"9UQU-DUWW"
}

3.2.4 Delete Resource Description

DELETE /rs/9UQU-DUWW
Authorization: Bearer 204c69636b6c69
...

HTTP/1.1 204 No content
...

3.2.5 List Resource Descriptions

GET /rs/ HTTP/1.1
Authorization: Bearer 204c69636b6c69
...

HTTP/1.1 200 OK
...
[  
   "KX3A-39WE",
   "9UQU-DUWW"
]

The following is a non-normative example of resource registration.

This example contains some steps that are exclusively in the realm of user experience to achieve realistic illustration. These steps are labeled "user experience only". Some other steps are exclusively internal to the operation of the entity being discussed. These are labeled "internal only".

A resource owner, Alice Adams, has just uploaded a photo of her new puppy to a resource server, Photoz.example.com, and wants to ensure that this specific photo is not publicly accessible.

Alice has already introduced this resource server to her authorization server, ShareHub.example.com. However, Alice has not previously instructed Photoz to use ShareHub to protect any photos of hers.

ShareHub has a "default-deny" setup, so until such time as Alice maps some other more permissive policies to any resources registered by Photoz, the policy is not to share them. Policies she may eventually map to particular photos or albums might be "Share only with husband@email.example.net" or "Share only with people in my 'family' group".

Photoz has a publicly documented application-specific API that offers two dozen different methods that apply to single photos, such as addTags and getSizes, but rolls them up into two photo-related scopes of access: "view" (consisting of various read-only operations) and "print" (consisting of various printing operations). It defines two scope descriptions that represent these scopes, which it is able to reuse for all of its users (not just Alice), and ensures that these scope description documents are available through HTTP GET requests that may be made by authorization servers.

Photoz constructs scope description documents for the scopes in order to provide data that will help them be displayed in user interfaces. (This means that any scope strings it supplies in resource registration descriptions will need to be URIs referring to these documents. The alternative would have been simple scope strings without the additional user interface data.)

The "name" parameter values in the scope descriptions are intended to be seen by Alice when she maps authorization constraints to specific resources and scopes while visiting ShareHub, such that Alice would see the strings "View Photo and Related Info" and "Print Photo", likely accompanied by the referenced icons, in the ShareHub interface. (Other users of Photoz might similarly see the same labels at ShareHub or whatever other authorization server they use. Photoz could distinguish natural-language labels per user if it wishes, by pointing to scopes with differently translated names.)

{  
   "name":"View Photo and Related Info",
   "icon_uri":"http://www.example.com/icons/reading-glasses.png"
}

{  
   "name":"Print Photo",
   "icon_uri":"http://www.example.com/icons/printer.png"
}

While visiting Photoz, Alice selects a link or button that instructs the site to "Protect" or "Share" this single photo (user experience only; Photoz could have made this a default or preference setting).

As a result, Photoz defines for itself a resource that represents this photo (internal only; Photoz is the only application that knows how to map a particular photo to a particular resource). Photoz also prepares the following resource description, which is specific to Alice and her photo. The "name" parameter value is intended to be seen by Alice in mapping authorization policies to specific resources and scopes when she visits ShareHub. Alice would see the string "Steve the puppy!", likely accompanied by the referenced icon, in the ShareHub interface. The possible scopes of access on this resource are indicated with URI references to the scope descriptions, as shown just above.

{  
   "name":"Steve the puppy!",
   "icon_uri":"http://www.example.com/icons/flower.png",
   "scopes":[  
      "http://photoz.example.com/dev/scopes/view",
      "http://photoz.example.com/dev/scopes/print"
   ]
}

Photoz uses the Create method of ShareHub's standard OAuth resource registration API, presenting its Alice-specific access token to use the API to register and assign an identifier to the resource description.

POST /rs/ HTTP/1.1
Content-Type: application/json
...
{  
   "name":"Steve the puppy!",
   "icon_uri":"http://www.example.com/icons/flower.png",
   "scopes":[  
      "http://photoz.example.com/dev/scopes/view",
      "http://photoz.example.com/dev/scopes/print"
   ]
}

If the registration attempt succeeds, ShareHub responds in the following fashion.

HTTP/1.1 201 Created
Content-Type: application/json
...
{  
   "_id":"112210f47de98100",
   "user_access_policy_uri":"http://as.example.com/rs/222/resource/112210f47de98100/policy"
}

At the time Alice indicates she would like this photo protected, Photoz can choose to redirect Alice to ShareHub for further policy setting, access auditing, and other authorization server-related tasks (user experience only).

Once it has successfully registered this description, Photoz is responsible for outsourcing protection to ShareHub for resource requests made to this photo.

Over time, as Alice uploads other photos and creates and organizes photo albums, Photoz can use additional methods of the resource registration API to ensure that ShareHub's understanding of Alice's protected resources matches its own.

For example, if Photoz suspects that somehow its understanding of the resource has gotten out of sync with ShareHub's, it can ask to read the resource description as follows.

GET /rs/112210f47de98100 HTTP/1.1
Host: as.example.com
...

Example of an HTTP response to a "read resource description" request, containing a resource description from the authorization server:

HTTP/1.1 200 OK
Content-Type: application/json
...
{  
   "_id":"112210f47de98100",
   "name":"Steve the puppy!",
   "icon_uri":"http://www.example.com/icons/flower.png",
   "scopes":[  
      "http://photoz.example.com/dev/scopes/view",
      "http://photoz.example.com/dev/scopes/print"
   ]
}

GET /rs/ HTTP/1.1
Host: as.example.com
...

HTTP/1.1 200 OK
...
[  
   "112210f47de98100",
   "34234df47eL95300"
]

If Alice later changes the photo's title (user experience only) on Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz would use the Update method to ensure that Alice's experience of policy-setting at ShareHub remains consistent with what she sees at Photoz. Following is an example of this request. Note that the entire updated resource description has to be included in the PUT request.

PUT /rs/112210f47de98100 HTTP/1.1
Content-Type: application/json
Host: as.example.com
...
{  
   "name":"Steve on October 14, 2011",
   "icon_uri":"http://www.example.com/icons/flower.png",
   "scopes":[  
      "http://photoz.example.com/dev/scopes/view",
      "http://photoz.example.com/dev/scopes/print"
   ]
}

ShareHub would respond as follows.

HTTP/1.1 201 Created
Content-Type: application/json
...
{  
   "_id":"112210f47de98100"
}

There are other reasons Photoz might want to update resource descriptions, having nothing to do with Alice's actions or wishes. For example, it might extend its API to include new features such as photo resizing, and want to add new scopes to all of Alice's and other users' resource descriptions.

DELETE /rs/112210f47de98100 HTTP/1.1
Host: as.example.com
...

ShareHub would respond as follows.

HTTP/1.1 204 No content
...

The resource server uses the POST method at the permission endpoint. The body of the HTTP request message contains a JSON object (for a request containing a single resource identifier) or array of objects (for a request containing more than one resource identifier) providing the request, using a format derived from the resource description format specified in Section 3.1, as follows. The object used in both forms has the following parameters:

resource_id

REQUIRED. The identifier for a resource to which the resource server is requesting permission on behalf of the client. The identifier MUST correspond to a resource that was previously registered.

resource_scopes

REQUIRED. An array referencing one or more identifiers of scopes to which the resource server is requesting access for this resource on behalf of the client. Each scope identifier MUST correspond to a scope that was previously registered by this resource server for the referenced resource.

Example of an HTTP request for a single permission at the authorization server's permission endpoint, with a PAT in the header:

POST /host/rsrc HTTP/1.1
Content-Type: application/json
Host: as.example.com
Authorization: Bearer 204c69636b6c69
...

{  
   "resource_id":"112210f47de98100",
   "resource_scopes":[  
      "view",
      "http://photoz.example.com/dev/actions/print"
   ]
}

Example of an HTTP request for multiple permissions at the authorization server's permission endpoint, with a PAT in the header:

POST /host/rsrc HTTP/1.1
Content-Type: application/json
Host: as.example.com
Authorization: Bearer 204c69636b6c69
...

[  
   {  
      "resource_id":"7b727369647d",
      "resource_scopes":[  
         "view",
         "crop",
         "lightbox"
      ]
   },
   {  
      "resource_id":"7b72736964327d",
      "resource_scopes":[  
         "view",
         "layout",
         "print"
      ]
   },
   {  
      "resource_id":"7b72736964337d",
      "resource_scopes":[  
         "http://www.example.com/scopes/all"
      ]
   }
]

If the authorization server is successful in creating a permission ticket in response to the resource server's request, it responds with an HTTP 201 (Created) status code and includes the ticket parameter in the JSON-formatted body.

For example:

HTTP/1.1 201 Created
Content-Type: application/json
...

{  
   "ticket":"016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}

If the resource server's permission registration request is authenticated properly but fails due to other reasons, the authorization server responds with an HTTP 400 (Bad Request) status code and includes one of the following error codes (see Section 6 for more information about error codes and responses):

invalid_resource_id

At least one of the provided resource identifiers was not found at the authorization server.

invalid_scope

At least one of the scopes included in the request was not registered previously by this resource server for the referenced resource.

Note: In order for the resource server to know which authorization server, PAT (representing a resource owner), and endpoint to use in making the token introspection API call, it may need to interpret the client's resource request.

Example of the resource server's request to the authorization server for introspection of an RPT, with a PAT in the header:

POST /rs/status HTTP/1.1
Host: as.example.com
Authorization: Bearer 204c69636b6c69
...
token=sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv
}

5.1.1 Authorization Server Response to Resource Server on Token Introspection Success

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
...

{  
   "active":true,
   "exp":1256953732,
   "iat":1256912345,
   "permissions":[  
      {  
         "resource_id":"112210f47de98100",
         "resource_scopes":[  
            "view",
            "http://photoz.example.com/dev/actions/print"
         ],
         "exp":1256953732
      }
   ]
}

This specification registers OAuth 2.0 authorization server metadata defined in Section 2, as required by Section 7.1 of [OAuthMeta].

9.1.1 Registry Contents

This specification registers the claim defined in Section 5.1.1, as required by [OIDCCore].

9.2.1 Registry Contents

This specification registers the claim defined in Section 5.1.1, as required by Section 3.1 of [RFC7662].

9.3.1 Registry Contents