User-Managed Access (UMA) 2.0

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 multiple domains. The following are REQUIRED:

• The authorization server MUST expose its endpoints over HTTP.
• The authorization server MUST use TLS protection over its endpoints, as governed by [BCP195], which discusses deployment and adoption characteristics of different TLS versions.
• The authorization server MUST use OAuth (or an OAuth-based authentication protocol) to secure its protection API endpoints. For those OAuth protection use cases where an identity token is desired in addition to an access token, it is RECOMMENDED that an OAuth-based authentication protocol such as OpenID Connect [OIDCCore] be used.
• The resource server MUST expose its protected resources through an HTTP service.

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

The resource server is privy to information about resource semantics and structure, of which it exposes only a subset through resource registration and API documentation. Thus, it is responsible for certain resource and scope interpretation tasks.

The resource server MAY register a single resource for protection that, from its perspective, has multiple parts, or has dynamic elements such as the capacity for querying or filtering, or otherwise has internal complexity. The resource server alone is responsible for maintaining any required mappings between internal representations and the resource identifiers and scopes known to the authorization server.

Because access attempts on resources by clients are unaware of resource identifiers, the process of making a permission request also requires interpretation by the resource server in order to establish a suitable resource identifier, resource owner, and authorization server. Section 1.4 discusses relevant requirements on the protected resources given this resource server task, and Section 3.4 discusses how the resource server should communicate expectations regarding permission requests to the client.

For its part, in order for the client to have a scope considered by the authorization server as part of an authorization assessment calcultion, it MUST pre-register for the scope at the authorization server (at which point the client acts on its own behalf) and also request the scope during an RPT request at the token endpoint (at which point it acts on the requesting party's behalf).

A variety of authorization, security, and time-to-live policies could be managed on a per-resource owner basis or a per-authorization server basis, as the entities see fit. Validity periods of PATs, RPTs, refresh tokens, permissions, caching periods for responses, and even OAuth client credentials are all subject to management. Different time-to-live strategies may be suitable for different resources and scopes of access. These options are all outside the scope of this specification; where deployment ecosystems using independent implementations seek a consistent high level of security, profiling is RECOMMENDED (see Section 5).

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

The authorization server's protection API consists of three endpoints:

• Resource registration endpoint as defined by [OAuth-resource-reg] and profiled by this specification, specifically regarding the mechanism of authentication to the endpoint
• Permission endpoint as defined by Section 3.4
• Token introspection endpoint as defined by [RFC7662] and Section 3.8.1

The resource server is the client of this API. As noted in Section 1.3, the authorization server MUST apply TLS and OAuth protection to this API. The authorization server MUST require a PAT for API access. Thus, the resource server is an OAuth client; it MUST have OAuth client credentials from the authorization server and the ability to obtain an OAuth access token with at least the scope uma_protection (that is, a PAT). If a request to a protection API endpoint fails due to an invalid, missing, or expired PAT, or requires higher privileges at this endpoint than provided by the PAT, the authorization server responds with an OAuth error.

The PAT binds the resource owner, the resource server used for resource management, and the 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. A different OAuth authorization grant type 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.

The resource server MAY protect any subset of the resource owner's resources using different authorization servers or other means entirely, or to protect some resources and not others. Additionally, the choice of protection regimes MAY be made explicitly by the resource owner or implicitly by the resource server. Any such partitioning by the resource server or owner is out of scope of this specification.

Note: Except for PAT issuance, the resource owner-authorization server and resource owner-resource server interfaces are out of scope of this specification. A variety of flows and user interfaces for policy condition setting involving user agents for both of these servers are possible, each with different privacy consequences for end-user resource owners. Some elements of the resource registration API and its data formats enable the building of user interfaces for policy condition setting.

Note: The resource server is responsible for managing the process and timing of registering resources, maintaining the registration of resources, and deregistering resources at the authorization server. See [UMA-Impl] for a discussion of resource registration options.

The UMA grant (defined throughout Section 3.6) consists of the following endpoints:

• OAuth token endpoint as defined by [RFC6749] and Section 3.6. The token endpoint handles client requests for, and issues, RPTs. The UMA grant type is defined for use on the requesting party's behalf rather than the resource owner's behalf, as in the case of grants defined in [RFC6749].
• OPTIONAL claims interaction endpoint as defined by Section 3.6.3. This endpoint plays a role in UMA somewhat similar to OAuth's authorization endpoint, but it is defined for use by the requesting party rather than the resource owner. For interactive claims-gathering, the client SHOULD register a claims_redirect_uri with the authorization server (as further defined in Section 3.6.3).

The authorization server's function is to perform authorization on behalf of one or more resource owners. The RPT resulting from successful authorization binds the requesting party, the client, the authorization server, the resource server, and the resource owner.

The authorization process is the process through which the client attempts to obtain an RPT from the authorization server in order to access a protected resource on behalf of a requesting party. The client and resource server both have opportunities to influence the set of permissions ultimately requested as part of the RPT request. The client also has an opportunity to seek upgrading of an existing RPT by providing that RPT on its request.

It is OPTIONAL for the authorization server to issue a persisted claims token (PCT) to the client when issuing an RPT in order to optimize a future RPT request. The PCT represents the set of claims collected by the authorization server during current authorization process. It is intended to be used at the same authorization server as appropriate when the same client seeks an RPT for the same requesting party in a subsequent authorization process, even if for a different resource or at a different resource server entirely.

The authorization server conducts the authorization process in three phases, with some potential variation in order and looping as follows:

• A claims collection phase. Two kinds of claims collection involving UMA flows are possible: claims pushing by a client and interactive claims gathering with an end-user requesting party. This phase occurs first in the authorization process in the following circumstances:
  • When the client redirects an end-user requesting party to the authorization server for interactive claims gathering as its first step after receiving a permission ticket. For this to happen, the client needs the authorization server to have statically declared a claims redirection endpoint in its configuration document.
  • When the client requests an RPT at the token endpoint with pushed claims as its first step after receiving a permission ticket.
• An authorization assessment phase (as defined in Section 3.6.5). This phase involves the authorization server assembling and evaluating policy conditions, scopes, claims, and other relevant information in evidence in order to mitigate access authorization risk. This phase occurs first in the authorization process when the client requests an RPT at the token endpoint as its first step after receiving a permission ticket without pushing any claims.
• An authorization result phase (as defined in Section 3.6.5). In this phase, the authorization server either returns a success code (as defined in Section 3.6.6), an RPT, and an optional PCT, or an error code (as defined in Section 3.6.7). If the error code is need_info, the authorization server provides a permission ticket, giving the client an opportunity once again to loop within the same authorization process.

Different choices of phase order, claim collection style, and use of the error_details hints inside need_info might be best suited for different deployment ecosystems. For example, where no pre-established relationship is expected between the resource owner's authorization server and the requesting party, initial requesting party redirection and a redirect_user hint may be a useful pattern, at which point the authorization server might either authenticate the requesting party locally or serve as a relying party for a remote identity provider. Where a common authorization server also functions as an identity provider for all resource owners and requesting parties, having the client push claim tokens sourced from that central server itself with a pre-negotiated format and contents may be an alternate useful pattern.

As noted in Section 1.3, this specification defines flows for protecting resources exposed only in the form of an HTTP service. The digital resources MAY take any form (for example, API endpoints).

Once a resource is registered for protection, and until it has been deregistered, the resource server MUST require the client to present a valid RPT with sufficient permissions before giving access.

Note: The following aspects of the resource server-client relationship are out of scope of this specification:

• How the client acquired knowledge of the resource server's interface and the specific endpoint of the desired protected resource. For example, the resource server might have a formally documented API or it might serve up a simple web page, and the resource owner might have advertised the endpoint publicly on a blog or other website, listed it in a discovery service, or emailed a link to a particular intended requesting party.
• The impetus for the client's access attempt. For example, an end-user requesting party might have clicked on a publicly available thumbnail representation of a graphics-based resource to retrieve a protected higher-resolution version.

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 (for a request containing more than one resource identifier) providing the request, using a format derived from the resource description format specified in [OAuth-resource-reg], as follows. The object used in both forms has the following properties:

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"
      ]
   }
]

The authorization server uses a permission ticket to maintain the state of a set of requested permissions, initially conveyed on the client's behalf by the resource server at attempted resource access time, for the period of time that the client continues to seek authorization for that attempted access.

The authorization server MUST make permission ticket values unguessable by resource servers and clients. Within these constraints, however, the authorization server MAY format the ticket however it chooses, for example either as a random string that references data held on the server or by including data within the ticket itself.

Permission tickets MUST be single-use. This prevents susceptibility to a session fixation attack.

The authorization server MUST invalidate a permission ticket when the client presents the permission ticket to either the token endpoint or the interactive claims endpoint; or when the permission ticket expires, whichever occurs first.

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 property 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 UMA error codes (see Section 4 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.

If the resource server successfully obtained a permission ticket from the authorization server, it responds to the client by providing a WWW-Authenticate header with the authentication scheme UMA, with the issuer URI from the authorization server's configuration document in an as_uri parameter and the just-received permission ticket in a ticket parameter.

For example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="example",
  as_uri="https://as.example.com",
  ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de"
...

If the resource server received an error of any kind when trying to request permissions such that it did not receive a permission ticket, then it is unable to create a WWW-Authenticate: UMA header and includes a header of the following form in its response to the client: Warning: 199 - "UMA Authorization Server Unreachable".

For example:

HTTP/1.1 403 Forbidden
Warning: 199 - "UMA Authorization Server Unreachable"
...

The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format per [RFC6749] Appendix B with a character encoding of UTF-8 in the HTTP request entity-body:

grant_type

REQUIRED. MUST be the value urn:ietf:params:oauth:grant-type:uma-ticket.

ticket

REQUIRED. The permission ticket.

rpt

OPTIONAL. Supplying an existing RPT gives the authorization server the option of upgrading that RPT instead of issuing a new one (see Section 3.6.5 for more about this option). Note: An RPT is bound to a specific resource owner, but it is out of scope of this specification for a protected resource's location to reveal the resource owner's identity to the client, so the client may not be aware of which RPT it received is bound to which resource owner.

scope

OPTIONAL. A string of space-separated values representing requested scopes. For any requested scope to be considered, the client MUST have pre-registered the same scope with the authorization server. The client should consult the resource server’s API documentation for details about permissions and their scopes expected to be included in permission requests.

claim_tokens

OPTIONAL. Claims pushed directly from the client to the authorization server. This allows the client to provide information relevant to the authorization process already in its possession to the authorization server. It MAY provide this information on a first or subsequent request to this endpoint. See Section 3.6.2 for information on providing pushed claims in claim tokens.

pct

OPTIONAL. If the authorization server previously returned a PCT along with an RPT, the client MAY include the PCT in order to optimize the process of seeking a new RPT. Given that some claims represented by a PCT are likely to contain identity information about a requesting party, a client supplying a PCT in its RPT request MUST make a best effort to ensure that the requesting party using the client now is the same as the requesting party that was associated with the PCT when it was issued. See Section 6.1.2 for additional PCT security considerations. See Section 3.6.6 for the form of the authorization server's response with a PCT.

Example of a request message containing a permission ticket and no optional parts:

POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic jwfLG53^sad$#f
...
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket&
ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de

Example of a request message containing a permission ticket and an RPT for upgrading:

POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic jwfLG53^sad$#f
...
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket&
ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de
&rpt=sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv

In order to push claims to the authorization server, the client provides the claim_tokens property in the body of its request message to the token endpoint as follows:

claim_tokens

REQUIRED. An array of objects with the following properties:

format

REQUIRED. A string specifying the format of the accompanying claim tokens. The string MAY be a URI.

token

REQUIRED. A string containing the claim information in the indicated format, base64url encoded if it is not already so encoded. If claim token format features are included that require special interpretation, the client and authorization server are assumed to have a prior relationship that establishes how to interpret these features. For example, if the referenced format equates to SAML 2.0 assertions and the claim token contains audience restrictions, it is the joint responsibility of the client and authorization server to determine the proper audience values that enable successful token consumption (see for Section 6.5.1 relevant security considerations).

Example:

POST /token HTTP/1.1
Host: www.example.com
Authorization: Bearer jwfLG53^sad$#f
...

{  
   "rpt":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
   "ticket":"016f84e8-f9b9-11e0-bd6f-0021cc6004de",
   "claim_tokens":[  
      {  
         "format":"http://openid.net/specs/openid-connect-core-1_0.html#IDToken",
         "token":"..."
      }
   ]
}

This specification provides a way to define profiles of claim token formats for use with UMA (see Section 5). The authorization server SHOULD document the profiles it supports in its configuration document.

The client redirects an end-user requesting party' to the claims interaction endpoint for whatever interactive claims-gathering processes the authorization server requires, such as presenting a questionnaire, a local or federated login form, or an opportunity to authorize persistent storage of claims for use in later authorization processes (the latter potentially being associated with a PCT). One motivation for such redirection could have been receipt of an authorization failure response containing an error_details structure with a redirect_user hint (see Section 3.6.7).

The client constructs the request URI by adding the following parameters to the query component of the claims interaction endpoint URI using the application/x-www-form-urlencoded format:

client_id

REQUIRED. The client's identifier issued by the authorization server.

claims_redirect_uri

OPTIONAL. The URI to which the client wishes the authorization server to direct the requesting party's user agent after completing its interaction. The URI MUST be absolute, MAY contain an application/x-www-form-urlencoded-formatted query parameter component that MUST be retained when adding additional parameters, and MUST NOT contain a fragment component. The authorization server SHOULD require all clients to register their claims redirection endpoint. Claims redirection URIs are different from the redirection URIs defined in [RFC6749] in that they are intended for the exclusive use of requesting parties and not resource owners. Therefore, authorization servers MUST NOT redirect requesting parties to pre-registered redirection URIs defined in [RFC6749] unless such URIs are also pre-registered specifically as claims redirection URIs. If the URI is pre-registered, this URI MUST exactly match one of the pre-registered claims redirection URIs, with the matching performed as described in Section 6.2.1 of [RFC3986] (Simple String Comparison).

ticket

REQUIRED. The latest permission ticket associated with the client's current request for this requesting party.

state

RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user agent back to the client. The use of this parameter is for preventing cross-site request forgery.

See Section 3.6.4 for the authorization server's mechanism for redirecting the requesting party back to the client.

Example of a request issued by a client application (line breaks are shown only for display convenience):

GET /rqp_claims?client_id=some_client_id&state=abc
&ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de
&claims_redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect_claims HTTP/1.1
Host: as.example.com

At the conclusion of its interaction with the requesting party, the authorization server returns the requesting party to the client, adding the following parameters to the query component of the claims redirection URI using the application/x-www-form-urlencoded format:

authorization_state

REQUIRED. Indicates that the authorization server completed its claims-gathering interaction with the requesting party with the indicated state:

claims_submitted

The client is free to return to the token endpoint to seek permissions once again.

not_authorized

The client is not authorized to have the desired permissions added.

need_info

The authorization server needs additional information in order to determine whether the client is authorized to have these permissions. This response directs the client to return to the token endpoint, where it might be provided with error_details hints about additional information needed.

request_submitted

The authorization server requires intervention by the resource owner to determine whether permissions can be added. Further immediate interaction between the client, requesting party, and authorization server is out of scope of this specification.

ticket

REQUIRED. A permission ticket that allows the client to make further requests to the authorization server during this attempted authorization. The value MUST NOT be the same as the one the client used to make its request.

state

OPTIONAL. The same state value that the client provided in the request. It MUST be present if and only if the client provided it.

Note: Interactive claim gathering processes are out of scope of this specification. The purpose of the interaction is for the authorization server to gather information for its own authorization assessment purposes. This redirection does not involve sending any of the information back to the client.

Prior to its redirecting the end-user requesting party back and preparatory to issuing a PCT, the authorization server MAY use the interactive claims-gathering process to gather authorization for persisting claims across authorization processes.

The client MUST ignore unrecognized response parameters. If the request fails due to a missing, invalid, or mismatching claims redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the requesting party of the error and MUST NOT automatically redirect the user agent to the invalid redirection URI. If the request fails for reasons other than a missing or invalid claims redirection URI, the authorization server informs the client by adding an error parameter to the query component of the claims redirection URI using the application/x-www-form-urlencoded format, containing one of the following ASCII error codes:

invalid_request

The request is missing a required parameter, includes an invalid parameter value (such as an invalid or expired ticket), includes a parameter more than once, or is otherwise malformed.

server_error

The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because an HTTP 500 (Internal Server Error) status code cannot be returned to the client via an HTTP redirect.)

temporarily_unavailable

The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because an HTTP 503 (Service Unavailable) status code cannot be returned to the client via an HTTP redirect.)

Example of a response issued by an authorization server (line breaks are shown only for display convenience):

GET /redirect_claims?&state=abc
&authorization_state=claims_submitted HTTP/1.1
Host: client.example.com

When the authorization server has received a request for an RPT from a client, it assesses whether the client is authorized to receive the requested RPT and determines the results.

The authorization server MUST apply the following conceptual authorization assessment calculation in determining authorization results. Note: As this calculation is internal to authorization server operations, its particulars are out of scope of this specification.

In this assessment calculation, let a set called ClientRegistered stand for the scopes for which the client pre-registered at the authorization server, either dynamically or through some static process. Let a set called ClientRequested stand for the scopes the client most recently requested at the token endpoint. Let a set called PermissionTicket stand for the scopes associated with the most recent permission ticket presented by the client at the token endpoint.

1. Determine the set of requested scopes as follows: RequestedScopes = PermissionTicket ∪ (ClientRequested ∩ ClientRegistered).
2. Determine all operative policy conditions, and claims and other relevant information serving as input to them, for each scope assocated with RequestedScopes and evaluate its authorization status. Note: Claims and other information gathered during one authorization process may become out of date in terms of their relevance for future authorization processes. The authorization server is responsible for managing such relevance wherever information associated with a PCT, or other persistently stored information, is used as input to authorization, including policy conditions themselves. Note: Since the authorization server's policy expression and evaluation capabilities are out of scope, any one implementation might take a simple or arbitrarily complex form, with varying abilities to combine or perform calculations over claims and their values. For example, logical operations such as accepting "either claim value A or B" as correct may be possible.
3. For each scope that passes the evaluation, add it to a set called CandidateGrantedScopes.

In the authorization results phase, the authorization server examines the CandidateGrantedScopes set to determine whether to issue an RPT and what permissions should be associated with it.

• If the value of CandidateGrantedScopes is null, the result is authorization failure and the authorization server MUST subsequently issue one of the error codes (Section 3.6.7).
• If the value is non-null and CandidateGrantedScopes = RequestedScopes, then the authorization server MUST subsequently respond with a success code and issue an RPT (upgrading as appropriate; see below).
• If the value is non-null and CandidateGrantedScopes < RequestedScopes, the authorization server MUST subsequently issue either an RPT containing CandidateGrantedScopes (upgrading as appropriate; see below), or one of the error codes. The reason for the two options is that granting only partial scopes may not be useful for the client's and requesting party's purposes in seeking authorization for access.

The authorization server MAY implement RPT upgrading. It is RECOMMENDED for the authorization server to document its practices regarding RPT upgrades and to act consistently with respect to RPT upgrades so as to enable clients to manage tokens efficiently. If the authorization server has implemented RPT upgrading, the client has submitted an RPT in its request, and the result is success, the authorization server adds the permissions from the client's previous RPT to the RPT it is about to issue, setting the value of the upgraded property in its response containing the upgraded RPT to true (see Section 3.6.6).

The following example illustrates authorization assessment and partial results:

• Assume a resource server has registered two resources on behalf of a resource owner, photo1 with scopes view, print, and download and photo2 with scopes view, print, download, and link.
• The resource owner has set policy conditions that allow access to photo1 only by requesting parties that can provide claims proving they are family members, and that allow access to photo2 only by requesting parties that can provide claims saying they agree not to download, sell, or market any photo.
• The client has pre-registered with the authorization server for download scope (so ClientRegistered contains download).
• The client attempts what the resource server interprets as view access to photo1.
• The resource server chooses to request a permission for view and print scopes for photo1 on the client's behalf (so PermissionTicket contains view and print).
• The client requests download scope on the requesting party's behalf while requesting an RPT from the authorization server (so ClientRequested contains download).
• The authorization server determines that RequestedScopes contains view, print, and download.
• Based on the authorization server's evaluation of policy conditions associated with these scopes, CandidateGrantedScopes contains only view and print and not download (the dynamically requested scope), which is less than in RequestedScopes.
• The authorization server has a choice whether to issue an RPT in this case.

Note: While a reasonable approach for most scenarios is to implement the classic security stance of default-deny ("everything that is not expressly allowed is forbidden"), corner cases can inadvertently result in default-permit behavior. For example, it is insufficient simply to assume that all resources have some non-zero set of claims required for access, and then accept an empty set of supplied claims as sufficient for access.

If the authorization server's assessment process results in issuance of permissions (see Section 3.6.5), it returns an HTTP 200 (OK) status code with a response body containing the RPT with which it has associated the requested permissions. The authorization server MAY return a refresh token. See Section 3.10 for more information about refreshing an RPT.

The authorization server MAY add the following properties to its response:

pct

OPTIONAL. A correlation handle representing claims and other information collected during this authorization process, which the client is able to present later in order to optimize future authorization processes on behalf of a requesting party. The PCT MUST be unguessable by an attacker. The PCT MUST NOT disclose claims from the requesting party directly to possessors of the PCT. Instead, such claims SHOULD be associated by reference to the PCT or expressed in an encrypted format that can be decrypted only by the authorization server that issued the PCT. See Section 3.6.3 for more information about the end-user requesting party interaction option. See Section 6.1.2 for additional PCT security considerations.

upgraded

OPTIONAL. Boolean value. If the client submits an RPT in the request and the authorization server includes the permissions of the RPT from the request as part of the newly issued RPT, then it MUST set this value to true. If it sets the value to false or the value is absent, the client MUST act as if the newly issued RPT does not include the permissions associated with the RPT from the request.

The authorization server MAY include any of the parameters defined in Section 5.1 of [RFC6749] on its response, except that it is NOT RECOMMENDED to include the scope parameter. This is because RPTs are associated with scopes that are associated with specific resources.

If the authorization server is upgrading an RPT, and the RPT string is new rather than repeating the RPT provided by the client in the request, then the authorization server SHOULD revoke the existing RPT, if possible, and the client MUST discard its previous RPT. If the authorization server does not upgrade the RPT but issues a new RPT, the client MAY retain the existing RPT.

Example:

HTTP/1.1 200 OK
Content-Type: application/json
... 

{  
   "access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
   "token_type":"Bearer"
}

Example with a PCT and an upgraded property in the response:

HTTP/1.1 200 OK
Content-Type: application/json
...

{  
   "access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
   "token_type":"Bearer",
   "pct":"c2F2ZWRjb25zZW50",
   "upgraded":true
}

If the client's request to the token endpoint is not sufficient for granting an RPT, the authorization server responds using an error code and corresponding HTTP status code. Any error code other than need_info ends the current authorization process; the client is free to attempt access to the protected resource another time. The need_info error code begins or continues an authorization process loop that concludes only when the client receives one of the other errors or a success condition (as described in Section 3.6.6).

invalid_grant

If the provided ticket was not found at the authorization server, or the provided ticket has expired, or if any other original reasons to use this error response are found as defined in [RFC6749], the authorization server responds with the HTTP 400 (Bad Request) status code.

invalid_scope

At least one of the scopes included in the request does not match an available scope for any of the resources associated with requested permissions for the permission ticket provided by the client. The authorization server responds with the HTTP 400 (Bad Request) status code.

not_authorized

The client is not authorized to have these permissions added. The authorization server responds with the HTTP 403 (Forbidden) status code. This error code is unique to the UMA grant.

request_submitted

The authorization server requires intervention by the resource owner to determine whether the client is authorized to have these permissions. The authorization server responds with the HTTP 403 (Forbidden) status code. This error code is unique to the UMA grant.

need_info

The authorization server needs additional information in order to determine whether the client is authorized to have these permissions. The authorization server responds with the HTTP 403 (Forbidden) status code. It MUST include a ticket object, and it MAY also include an error_details object. This error code is unique to the UMA grant.

ticket

REQUIRED. A permission ticket that allows the client to make further requests to the authorization server during this attempted authorization. The value MUST NOT be the same as the one the client used to make its request.

error_details

OPTIONAL. Provides hints about information the authorization server needs to perform authorization assessment. On receiving such hints, the client has the opportunity to engage, or engage the requesting party, in claims collection flows. At least one of its sub-properties MUST be supplied.

required_claims

An array containing objects that describe the required claims, with the following properties:

name

OPTIONAL. A string (which MAY be a URI) representing the name of the claim; the "key" in a key-value pair.

friendly_name

OPTIONAL. A string that provides a more human-readable form of the attribute's name, which may be useful as a "display name" for use in user interfaces in cases where the actual name is complex or opaque, such as an OID or a UUID.

claim_type

OPTIONAL. A string, indicating the expected interpretation of the provided claim value. The string MAY be a URI.

claim_token_format

OPTIONAL. An array of strings specifying a set of acceptable formats for a token pushed by the client containing this claim (see Section 3.6.2). Any one of the referenced formats would satisfy the authorization server's requirements. Each string MAY be a URI.

issuer

OPTIONAL. An array of strings specifying a set of acceptable issuing authorities for the claim. Any one of the referenced authorities would satisfy the authorization server's requirements. Each string MAY be a URI.

redirect_user

The claims interaction endpoint URI to which to redirect the end-user requesting party at the authorization server to continue the process of interactive claims gathering. For example, the authorization server may require the requesting party to fill out a CAPTCHA to help prove humanness. If the requesting party is not an end-user, then no client action would be possible on receiving the hint. If a static claims interaction endpoint was also provided in the authorization server's configuration document, then this value overrides the static value. Providing a value in this response might be appropriate, for example, if the URI needs to be customized per requesting party.

Example when the ticket has expired:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...

{  
   "error":"invalid_grant"
}

Example of a need_info response with a full set of error_details hints:

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
...

{  
   "error":"need_info",
   "ticket":"ZXJyb3JfZGV0YWlscw==",
   "error_details":{  
      "required_claims":[  
         {  
            "name":"email23423453ou453",
            "friendly_name":"email",
            "claim_type":"urn:oid:0.9.2342.19200300.100.1.3",
            "claim_token_format":[  
               "http://openid.net/specs/openid-connect-core-1_0.html#IDToken"
            ],
            "issuer":[  
               "https://example.com/idp"
            ]
         }
      ],
      "redirect_user":"https://as.example.com/rqp_claims?id=2346576421"
   }
}

The resource server's request for introspection of an RPT MUST use the OAuth token introspection endpoint (defined by [RFC7662]) declared by the authorization server in its configuration document. The authorization server MUST require requests to this endpoint to be accompanied by a PAT. The PAT provides resource-owner context to the authorization server as well as demonstrating authorized access.

Note: The act of using the token introspection endpoint may require the resource server to interpret which authorization server to consult and in the context of which resource owner, in order to select which PAT to use to make the API call.

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
}

The authorization server's response to the resource server MUST use [RFC7662], responding with a JSON object with the structure dictated by that specification, extended as follows.

If the active property has a Boolean value of true, then the introspection object MUST NOT contain a scope claim, and SHOULD contain an extension property with the name permissions that contains an array of one or more values, each of which is an object consisting of these properties:

resource_id

REQUIRED. A string that uniquely identifies the protected resource, access to which has been granted to this client on behalf of this requesting party. The identifier MUST correspond to a resource that was previously registered as protected.

resource_scopes

REQUIRED. An array referencing one or more strings representing scopes to which access was granted for this resource. Each string MUST correspond to a scope that was registered by this resource server for the referenced resource.

exp

OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this permission will expire. If the property is absent, the permission does not expire. If the token-level exp value pre-dates a permission-level exp value, the former overrides the latter.

iat

OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this permission was originally issued. If the token-level iat value post-dates a permission-level iat value, the former overrides the latter.

nbf

OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating the time before which this permission is not valid. If the token-level nbf value post-dates a permission-level nbf value, the former overrides the latter.

For interoperability, if the introspection object does not contain the permissions property, then an UMA extension SHOULD be defined as appropriate, with supporting authorization servers using the uma_profiles_supported configuration property to advertise their support of any alternative structures (see Section 5 for more information).

Example of a response containing the introspection object with the permissions property:

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
      }
   ]
}

The resource server assesses the permissions associated with the RPT, whether obtained through token introspection or otherwise, and compares them with the RPT-accompanied client's access attempt to a protected resource.

Note: The act of assessment may require the resource server to interpret which resource, resource owner, authorization server, and scope to map to the client's access attempt.

The purpose of this assessment is to determine sufficiency of authorization. The resource server MAY apply additional authorization controls when determining how to respond. For example, even if an RPT provides sufficient permissions for a particular case, the resource server deployer can choose to bar access to certain additional requesting parties.

To ensure the integrity of the ecosystem in which the resource server, authorization server, and resource owner are participating, it is RECOMMENDED for the parties to establish agreements about access rules on a legal or contractual level. See Section 6.5 for more information.

The resource server MUST NOT give access in the case of an invalid RPT or an RPT associated with insufficient authorization.

The client's presentation of a valid RPT associated with sufficient permissions indicates that the policy conditions have been met for access to the protected resource.

Example of the resource server's response to the client on sufficiency of authorization:

HTTP/1.1 200 OK
Content-Type: application/json
...

{  
   "f_number":"f/5.6",
   "exposure":"1/320",
   "focal_length_mm":150,
   "iso":400,
   "flash":false
}

The client's presentation of an invalid RPT or an RPT associated with insufficient permissions for access indicates that the policy conditions have not been met for access to the protected resource.

In this case, the resource server's next option to act is defined in Section 3.4 (requesting permissions, which involves the authorization server), and its next option to respond to the client is defined in Section 3.5, exactly as if the client had attempted to access the protected resource with no RPT. Because the resource server is responsible for its own resource semantics and structure, it may need to map the client's access attempt to a suitable resource identifier (and thus resource owner and authorization server) before proceeding.

Like ordinary OAuth redirection, UMA redirection for the purpose of gathering claims from an end-user requesting party (described in Section 3.6.3) creates the potential for cross-site request forgery (CSRF) through an open redirect if the authorization server does not force the client to pre-register its claims redirection endpoint, and server-side artifact tampering if the client does not avail itself of the state parameter. The client SHOULD check that the ticket value returned by an authorization server after a claims redirect is completed has not been maliciously changed, for example by a man in the browser, by using the state parameter. (See [UMA-Impl] for advice on ways to accomplish this.) Sections 4.4.1.8, 4.4.2.5, and 5.3.5 of [RFC6819] are apropos for the UMA claims-gathering redirection flow as well.

When a client redirects an end-user requesting party to the claims interaction endpoint, the client provides no a priori context to the authorization server about which user is appearing at the endpoint, other than implicitly through the permission ticket. Since the authorization server is free to gather any claims it wishes, the effect is to "late-bind" them to the permission ticket and the state string provided by the client, with the effect of enabling the authorization server not to trust client-asserted claims. This is a desirable result and reflects one reason why the authorization server might choose to demand use of the redirect flow over the push flow. However, the client has the opportunity to switch end-users -- say, enabling malicious end-user Carlos to impersonate the original end-user Bob, who might be represented by a PCT already in that client's possession and might even have authorized the issuance of that PCT -- after the redirect completes and before it returns to the token endpoint to seek permissions.

Another issue concerns the exposure of an RPT to a requesting party, which could maliciously pass the token to an unauthorized party.

To mitigate requesting-party switching and RPT exposure threats, consider the following strategies.

• Require that the requesting party legitimately represent the wielder of the bearer token on a legal or contractual level. This solution does not reduce the risk from a technical perspective.
• The authorization server, possibly with input from the resource owner, can implement tighter time-to-live strategies around the permissions in RPTs. This is a classic approach with bearer tokens that helps to limit a malicious party's ability to intercept and use the bearer token. In the same vein, the authorization server could require claims to have a reasonable degree of freshness (which would require a custom claims profile).
• A stronger strategy is to gather claims interactively from an end-user requesting party that demonstrate that some sufficiently strong level authentication was performed.
• The strongest strategy is to disallow bearer-type RPTs, by providing or requiring a holder-of-key approach. In this way, the wielder of the access token must engage in a live session for proof-of-possession.

A PCT is similar to a refresh token in that it carries extra power over the usage of an RPT. The authorization server and client MUST keep PCTs confidential in transit and storage, and MUST NOT share any PCT with any other entity other than the issuer or issued client, respectively. The authorization server MUST maintain the binding between a PCT and the client to which it was issued.

Given that a PCT represents a set of requesting party claims, a client supplying a PCT in its RPT request MUST make a best effort to ensure that the requesting party using the client now is the same as the requesting party that was associated with the PCT when it was issued. Different clients will have different capabilities in this respect; for example, some applications are single-user and perform no local authentication, associating all PCTs with the "current user", while others might have more sophisticated authentication and user mapping capabilities.

Along with requiring TLS, UMA requires OAuth, or any OAuth-based authentication protocol, as the security mechanism for its protection API. The resource server thus acts in the role of an OAuth client at the authorization server's protection API. While it is possible to use any profile of OAuth for this protection, it is RECOMMENDED for the authorization server to use OpenID Connect, and to use its mechanisms for stronger client authentication at the token endpoint, in order to strengthen the authentication of OAuth clients. Section 16 of [OIDCCore] provides more information on OpenID Connect security considerations.

Clients using the OAuth implicit grant type carry particular vulnerabilities in OAuth, and using OpenID Connect is of no help in this circumstance. This is true where a resource server is used as an OAuth client for obtaining a PAT on a resource owner's behalf, and also where an authorization server is gathering claims from a requesting party through OAuth.

For example, an "implicit client" might require the retrieval of PATs more frequently, for each browser on each platform. An attacker can initiate a spear phishing attack on the resource owner with a link to a malicious website, relying on the resource owner to authenticate to the authorization server through an email-based identity provider in order to receive the PAT. The site can impersonate the resource owner using the browser client's client ID in an OpenID Connect implicit request to the authorization server. If the resource owner had previously authorized a PAT to be issued, this attempt will likely succeed. The subsequently issued PAT could be used for resource registration and other protection API tasks.

A number of mitigation strategies are possible.

• The authorization server could penalize or disallow use of the implicit grant flow. This could be done at a variety of levels:
  • Enabling resource owners to define policies controlling the use of such clients
  • Setting system-default policies controlling their use
  • Participating in mutual agreements with other parties, for example, through the definition and mandated use of profiles, that admit only suitably secure client applications to interact with service operators
• The authorization server could support dynamic client registration at the client instance level, such that each instance receives a unique client_id and secret. The client can then use the authorization code flow and have at least some form of client authentication. However, this is easier for a mobile app than for a browser-based HTML app.

This section discusses the threats surrounding client claim pushing (see Section 3.6.2).

Because claim tokens of any format typically contain audience restrictions and an authorization server would typically not be in the primary audience for a claim token held or generated by a client, it is RECOMMENDED to document how the client, authorization server, and any additional ecosystem entities and parties will establish a trust relationship and communicate any required keying material in a claim token profile, as described in Section 5. Authorization servers are RECOMMENDED not to accept claim tokens pushed by untrusted clients and not to ignore audience restrictions found in claim tokens pushed by clients.

In the special circumstance when an authorization server is colocated with an OpenID Provider for the requesting parties within a deployment ecosystem, then it is able to act as an OpenID Relying Party for itself. This circumstance presents an opportunity for a technical optimization of the requirement for trust because the authorization server itself issued the OAuth client credentials for the client in question, and could reasonably be the singular aud value target in an OpenID Connect ID Token pushed by the client to the token endpoint.

• URI suffix: uma2-configuration
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 2.2 in this document

• Claim name: permissions
• Claim description: Array of objects, each describing a set of scoped, time-limitable entitlements to a resource
• Change controller: Kantara Initiative User-Managed Access Work Group - wg-uma@kantarainitiative.org
• Specification document: Section 3.8.2 in this document

• Claim name: permissions
• Claim description: array of objects, each describing a set of scoped, time-limitable entitlements to a resource
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.8.2 in this document

• Parameter name: ticket
• Parameter usage location: client request, token endpoint
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document

• Parameter name: rpt
• Parameter usage location: client request, token endpoint
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document

• Parameter name: claim_tokens
• Parameter usage location: client request, token endpoint
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document

• Parameter name: pct
• Parameter usage location: client request, token endpoint
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document

• Parameter name: pct
• Parameter usage location: authorization server response, token endpoint
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.6 in this document

• Parameter name: upgraded
• Parameter usage location: authorization server response, token endpoint
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.6 in this document

• Error name: not_authorized (note: this error is distinct from unauthorized_client; it refers to the authorization status of the requesting side)
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document
• Error usage location: authorization server response, token endpoint

• Error name: request_submitted
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document
• Error usage location: authorization server response, token endpoint

• Error name: need_info (and its subsidiary ticket and error_details structures)
• Change controller: Kantara Initiative User-Managed Access Work Group - staff@kantarainitiative.org
• Specification document: Section 3.6.1 in this document
• Error usage location: authorization server response, token endpoint