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. Unless one or more of the profiles defined in Section 5 are in use, 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 resource server is privy to information about resource semantics and structure, only a limited subset of which is exposed through resource registration and API documentation. Thus, certain responsibilities for resource and scope interpretation fall to the resource server.

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 resource identifier-unaware, the process of making a permission request may also require interpretation by the resource server in order to establish a suitable resource identifier, resource owner, and authorization server.

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 issuance of a PAT represents the authorization of the resource owner for the resource server to use the authorization server for protecting the resources that this resource server registers for protection. Any OAuth authorization grant type might be appropriate depending on circumstances; 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.

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 if the experiences encourage or discourage different access granting behaviors. Some discretionary elements of the resource registration API are available for use in such user interfaces.

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 for this specification.

Note: Because the resource server is responsible for managing internal resource complexity and because the resource owner-resource server interface is out of scope for this specification, the resource server is fully responsible for managing the process and timing of registering resources, maintaining the registration of resources, and deregistering resources at the authorization server.

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 (as defined in Section 3.6.3) with the authorization server, either using a static process or through [RFC7591] or [OIDCDynClientReg].

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 future RPT requests. The PCT represents the set of claims collected by the authorization server during current authorization process. It is intended to be used when this client seeks an RPT for this requesting party at this authorization server in a subsequent authorization process, even if for a different resource or at a different resource server entirely.

The authorization server's function is to perform authorization on behalf of 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 authorization server conducts the authorization process in three phases, with some variation in order and looping possible 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 MAY occur 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 a first step. In order for this to happen, the client needs a permission ticket and for 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.
• An authorization assessment phase (as defined in Section 3.6.5). This phase involves assembling and calculating over policy conditions, scopes, claims, and other relevant information in evidence in order to mitigate access authorization risk. This phase MAY occur first in the authorization process when the client requests an RPT at the token endpoint as its first step 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.8). 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 to redirect the requesting party and request an RPT.

Some choices of phase order, claim collection, and the error_details structure inside need_info may tend to be suited for particular deployment ecosystems. For example, where no pre-established relationship is expected between the resource owner's authorization server and the requesting party, initial redirecting party redirection and a redirect_user hint may be most practical, at which point the authorization server might either authenticate the requesting party locally or serve as a relying party for a remote identity provider. On the other hand, in an ecosystem where a common authorization server also functions as an identity provider for all resource owners and requesting parties, it may be most practical for the client to push claim tokens sourced from that central server itself with a pre-negotiated format and contents.

As noted in Section 1.3, the resource server MUST expose its protected resources through an HTTP service unless the appropriate extensibility profile is in use. 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 service-client relationship are out of scope for 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_uri 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_uri 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.

The authorization server MUST invalidate a permission ticket when the client presents the permission ticket either to the token endpoint or 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.2 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. If the client included an RPT in its failed access attempt to the resource, it MAY include the same RPT here. This gives the authorization server the option of updating the existing RPT instead of issuing a new one (see Section 3.6.6 for the basic form of that response).

scope

OPTIONAL. A string of space-separated values representing the scopes that the client is requesting. This allows the client to add dynamically to any scopes already under consideration for authorization.

claim_tokens

OPTIONAL. Claims pushed directly from the client to the authorization server. This allows the client to provide information already in its possession to the authorization server. It MAY provide this information a first or subsequent request to this endpoint. See Section 3.6.2 for 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 7.1.2 for additional PCT security considerations. See Section 3.6.7 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
&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 7.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#HybridIDToken",
         "token":"..."
      }
   ]
}

This specification provides a framework for extensibility through claim token profiling (see Section 6). The authorization server MAY support any number of claim token profiles, and SHOULD document the claim token 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 or a local or federated login form.

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 redirection endpoint prior to utilizing the authorization endpoint (either using a static process or through [RFC7591] or [OIDCDynClientReg]). 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.7 for authorization server options for collecting authorization from the requesting party while gathering claims interactively. SeeSection 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

OPTIONAL. A permission ticket that allows the client to make further requests to the authorization server during this attempted authorization. The value of this permission ticket 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 for 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.

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 resource owner 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.

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 for this specification.

In this 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 = union ( intersection (ClientRequested, ClientRegistered), PermissionTicket). Observe that this logic requires the client to have registered and requested at least one scope in common to have any effect on the result set.
2. Determine all operative policy conditions for each resource scope assocated with RequestedScopes and evaluate it. Note: Policy conditions are out of scope (in the ordinary English sense) for this specification. Potential sources of claims include pushed claims, interactively gathered claims, and claims associated with a client-provided PCT in the RPT request.
3. For each scope that passes the evaluation, add it to a set called CandidateGrantedScopes.

If the value of CandidateGrantedScopes is null, the result is authorization failure and the authorization server MUST subsequently issue one of the UMA error codes (Section 3.6.8). If the value is non-null and CandidateGrantedScopes equals RequestedScopes, the authorization server MUST subsequently respond with a success code and issue an RPT (see Section 3.6.6). If the value is non-null and CandidateGrantedScopes less-than RequestedScopes, the authorization server MUST subsequently issue either an RPT containing CandidateGrantedScopes or one of the UMA 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.

For example, assume a resource server has registered two resources on behalf of a resource owner, rsid_1 with scopes view, link, and download and rsid_2 with scopes view, link, download, and print, and the resource owner has set policy conditions that allow access to rsid_1 only by requesting parties that can provide claims proving they are family members, and that allow access to rsid_2 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 rsid_1. The resource server chooses to request view and print scopes for rsid_1 on its behalf (so PermissionTicket contains view and print). The client requests download scope while requesting an RPT from the authorization server (so ClientRequested contains download, and 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, 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.

Note: Since the authorization server's policy expression and evaluation capabilities might take a simple or arbitrarily complex form, its corresponding abilities to combine or perform calculations over claims and their values might also vary.

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 should use caution and attempt to manage freshness characteristics wherever a PCT or other persistently stored representation of information is used as input to policy evaluations, even including policy conditions themselves.

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. The authorization server MAY return a PCT. If the client included an existing RPT in its request and the authorization server issues a new RPT, the authorization server SHOULD revoke the existing RPT, if possible, and the client MUST discard its previous RPT.

Example:

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

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

The authorization server MAY return a PCT along with an RPT. The PCT represents claims collected during this authorization process, either directly or through the claims interaction endpoint. 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 7.1.2 for additional PCT security considerations.

The authorization server MAY choose to persist collected claims and issue a PCT in order to optimize future authorization processes on behalf of a requesting party. It MAY also gather authorization from an end-user requesting party for persisting these claims, one option being persisting this authorization in the form of an actual claim itself. The authorization server MAY combine authorization-gathering interaction with other interactions as necessary, and in any order. For example, the authorization server might present an opportunity for the requesting party to create or manage a login account for more persistent storage of gathered and pushed claims over time.

The PCT MAY be included by the client in future requests to the token endpoint using the UMA grant type (see Section 3.6.1).

Example:

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

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

If the client's request to the token endpoint is not sufficient for granting an RPT, the authorization server responds using one of the following UMA error codes and corresponding HTTP status codes (see Section 4.2 for more information about error codes and responses):

invalid_ticket

The provided ticket was not found at the authorization server. The authorization server responds with the HTTP 400 (Bad Request) status code.

expired_ticket

The provided ticket has expired. 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.

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.

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.

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 MAY also respond with an error_details object that contains one or more sub-properties with hints about the nature of further required information.

The first five error responses end the current authorization process; the client is free to attempt access to the protected resource another time. The sixth error response, need_info, begins or continues an authorization process loop that concludes only when the client receives one of the other five errors or a success condition (as described in Section 3.6.6).

Example when the ticket has expired:

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

{  
   "error":"expired_ticket"
}

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",
   "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#HybridIDToken"
            ],
            "issuer":[  
               "https://example.com/idp"
            ]
         }
      ],
      "redirect_user":"https://as.example.com/rqp_claims_uri?id=2346576421"
   }
}

The error_details object is OPTIONAL for the authorization server to provide. It provides hints about additional requirements regarding information the authorization server needs about the requesting party. On receiving such hints, the client has the opportunity to engage, or engage the requesting party, with the authorization server in claims collection flows of various types. The error_details sub-property MAY contain the following parameters, where at least one of required_claims or redirect_user MUST be supplied.

required_claims

An array containing objects that describe characteristics of 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

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

ticket

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

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_uri 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 6 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, if the resource owner's policy conditions at the authorization server have led to issuance of an RPT with 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 7.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 within the UMA profile being deployed, by providing or requiring an RPT profile that requires use of a holder-of-key approach. In this way, the wielder of the 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 6. 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.

• 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

• Name: permissions
• 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

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

• Grant type: urn:ietf:params:oauth:grant-type:uma-ticket
• Change controller: Kantara Initiative User-Managed Access Work Group - wg-uma@kantarainitiative.org
• Specification document: Section 3.6.1 in this document
• Parameters (usage locations are all on the token endpoint):
  • ticket
  • rpt
  • claim_tokens
  • rpt