| Version: | 2.0 |
| Date: | 2016-11-17 |
| Editor: | Eve Maler, ForgeRock |
| Contributors: | Maciej Machulak, iWelcome |
| Justin Richer, Bespoke Engineering | |
The User-Managed Access (UMA) 2.0 federated authorization framework enables a resource owner to control resource access to requesting parties through the clients they use in an asynchronous fashion, where resources reside on any number of resource servers and a central authorization server manages the resource owner's access grants over time.
This document is a draft technical specification produced by the User-Managed Access Work Group. See the Kantara Initiative Operating Procedures for more information.
Copyright © 2016 Kantara Initiative and the persons identified as the document authors. All rights reserved.
This document is subject to the Kantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND) (HTML version).
The User-Managed Access (UMA) 2.0 federated authorization framework uses and extends OAuth 2.0 ERROR: Undefined target: RFC6749 (at line 63), along with leveraging federated identity frameworks, in order to enable additions to OAuth abilities as follows:
For example, a bank customer (resource owner) named Alice with a bank account service (resource server) can use a dedicated sharing management service (authorization server) to manage access by a spouse Bob, an accounting professional Charline, and a tax professional David (requesting parties), all using different client applications, to view account data and even to give each of them differential access to payment and withdrawal functions. Alice can use the same sharing management service to give out "read", "write", or "comment" access to documents residing in a cloud file system (a different resource server) residing in a different domain to community members Erik and Frances with whom she is working on a project. (A variety of use cases can be found in [UMA-usecases] and [UMA-casestudies].)
The federation of authorization in UMA results in a conceptual separation of responsibilities: The resource server defines the boundaries of a resource and its possible scopes of access; the resource owner configures the authorization server to express access grant rules that match up resources and scopes to a protection scheme; and the authorization server executes those rules when clients attempt protected-resource access on behalf of requesting parties, with an ultimate result of access token and permission issuance or denial.
Practical control of access among loosely coupled parties typically requires more than just messaging protocols. It is out of scope for this specification to define more than just the "technical contract" between UMA-conforming entities. The legally responsible parties representing these entities may form contracts for, or there may be laws or regulations governing, access-sharing relationships. Parties operating entities that claim to be UMA-conforming should provide documentation of any rights and obligations between and among them; see Section 7.5 for more information.
Note: The resource owner-authorization server interface is out of scope of this specification, and as a result, a variety of flows are all equally possible for the resource server and authorization server in concert to provide to a resource owner, with particular consequences for user experiences of end-user resource owners.
Implementers have the opportunity to develop extensions and profiles (see Section 6) that specify and restrict various UMA protocol and identity claim format options, according to deployment and usage conditions.
[tbs: Intro to high-level protocol flow]
Main Protocol Flow
tbs
Figure 1
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in ERROR: Undefined target: RFC2119 (at line 153).
Unless otherwise noted, all protocol properties and values are case sensitive. JSON ERROR: Undefined target: RFC7159 (at line 156) data structures defined by this specification MAY contain extension properties that are not defined in this specification. Any entity receiving or retrieving a JSON data structure SHOULD ignore extension properties it is unable to understand. Extension names that are unprotected from collisions are outside the scope of this specification.
UMA introduces the following new terms and enhancements of OAuth term definitions.
The software components that fill the roles of UMA authorization servers, resource servers, and clients respectively are intended to work in an interoperable fashion when each is operated by an independent party (for example, different organizations). For this reason, UMA specifies communications channels that the authorization server MUST implement as HTTP-based APIs that MUST use TLS and OAuth (or OAuth-based authentication protocol) protection, and that the resource server MUST implement as an HTTP-based interface. UMA's use of TLS is governed by [BCP195], which discusses deployment and adoption characteristics of different TLS versions.
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.
It is also REQUIRED, in turn, for resource servers and clients on the requesting side of UMA interactions to use these channels, unless a profile is being used that enables API extensibility. The profiles that enable such alternatives are provided in Section 5.
The authorization server MUST present an HTTP-based protection API, protected by TLS and OAuth (or an OAuth-based authentication protocol), for use by resource servers. The authorization server thus has an OAuth token endpoint and authorization endpoint. The authorization server MUST declare all of its protection API endpoints in its configuration (see Section 1.4).
The protection API consists of three endpoints:
The UMA resource server, which is the entity seeking protection API access, MUST be an OAuth client with client credentials and the ability to get an OAuth access token with at least the scope uma_protection. An access token with at least this scope is called a protection API access token (PAT). If a request to an 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.
A PAT binds a resource owner, a resource server the owner uses for resource management, and an authorization server the owner uses for protection of resources at this resource server. It is not specific to any client or requesting party. The issuance of a PAT represents the approval of the resource owner for this resource server to use this authorization server for protecting some or all of the resources belonging to this resource owner. 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: The PAT is used in requesting permission on the client's behalf (as described in Section 3.2). One circumstance precipitating this action is when the client has attempted access without an RPT (as described in Section 3.1.1). In order for the resource server to know which authorization server to approach and which PAT (representing a resource owner) and resource identifier to supply, the resource server's API needs be structured in such a way that it can derive this information from the client's RPT-free access attempt. In practice, this information likely needs to be passed through the URI, headers, or body of the client's request.
The authorization server has the opportunity to manage the validity periods of access tokens that it issues, their corresponding refresh tokens where applicable, the individual permission components associated with RPTs where applicable, caching periods for responses, and even the client credentials that it issues. Different time-to-live strategies may be suitable for different resources and scopes of access, and the authorization server has the opportunity to give the resource owner control over lifetimes of tokens and permissions issued on their behalf through policy. These options are all outside the scope of this specification.
The authorization server supplies configuration information in order to document its endpoints and the major conformance options it supports.
Where this specification does not already require optional features to be documented, it is RECOMMENDED that authorization server deployers document any profiled or extended features explicitly and use extension configuration properties to indicate their usage.
The authorization server has configuration properties as follows.
The authorization server MUST make its configuration properties available in a JSON document at the path formed by concatenating the string /.well-known/uma2-configuration to the issuer configuration property value as defined in Section 1.4.1. The syntax and semantics of /.well-known are defined in ERROR: Undefined target: RFC5785 (at line 541) and apply to the issuer value when it contains no path component.
Any entity, such as a resource server or client, seeking an authorization server configuration document MUST query it using an HTTP GET request.
Example:
GET /.well-known/uma2-configuration HTTP/1.1 Host: example.com }
If the issuer value contains a path component, the caller MUST remove any terminating slash before appending /.well-known/uma2-configuration.
For example, the caller would make the following request to the issuer https://example.com/issuer1, since the issuer value contains a path component:
GET /issuer1/.well-known/uma2-configuration HTTP/1.1 Host: example.com }
A successful authorization server response to a configuration document query MUST use the HTTP 200 (OK) status code and return a JSON object using the application/json content type containing the configuration properties as defined in Section 1.4.1.
Example (note the use of https: for endpoints throughout):
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"issuer":"https://example.com",
"claim_token_profiles_supported":[
"https://example.com/claims/formats/token1"
],
"registration_endpoint":"https://as.example.com/dyn_client_reg_uri",
"token_endpoint":"https://as.example.com/token_uri",
"authorization_endpoint":"https://as.example.com/authz_uri",
"claims_interaction_endpoint":"https://as.example.com/claims_uri",
"resource_registration_endpoint":"https://as.example.com/rs/rsrc_uri",
"introspection_endpoint":"https://as.example.com/rs/status_uri",
"permission_endpoint":"https://as.example.com/rs/perm_uri"
}
The resource owner, resource server, and authorization server perform the following actions to put resources under protection. This list assumes that the resource server has discovered the authorization server's configuration document and endpoints as needed.
Note: The resource server is free to offer the option to 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 can be made explicitly by the resource owner or implicitly by the resource server. Any such partitioning by the resource server or owner is outside the scope of this specification.
Once a resource has been placed under authorization server protection through the registration of a resource description document for it, and until such a description's deletion by the resource server, the resource server MUST limit access to corresponding resources, requiring sufficient permissions associated with client-presented RPTs by the authorization server (see Section 3.3.1).
Note: The PAT that the resource server uses to register resources must also be used later during client access attempts, for example, in requesting permission on a client's behalf (as described in Section 3.2). One circumstance precipitating this action is when the client has attempted access without an RPT (as described in Section 3.1.1). In order for the resource server to know which authorization server to approach and which PAT (representing a resource owner) and resource identifier to supply, the resource server's API needs be structured in such a way that it can derive this information from the client's RPT-free access attempt. In practice, this information likely needs to be passed through the URI, headers, or body of the client's request.
An authorization server orchestrates and controls clients' access on their requesting parties' behalf to a resource owner's protected resources at a resource server, under conditions specified by that resource owner through policy.
The process of getting authorization and accessing a resource always begins with the client attempting access at a protected resource endpoint at the resource server. Several aspects of the client's behavior are out of scope for this specification:
In brief, the entire process is as follows.
The recipient of each request message SHOULD respond unless it detects a security concern, such as a suspected denial of service attack that can be mitigated by rate limiting.
This interaction assumes that the resource server has already registered any relevant resources prior to the client's access attempt at any resource that is intended to be UMA-protected.
Example of a client request at a protected resource carrying no RPT:
GET /users/alice/album/photo.jpg HTTP/1.1 Host: photoz.example.com ...
If the resource server chooses to respond, it next requests one or more permissions on the client's behalf (see Section 3.2).
Example of a client request at a protected resource carrying an RPT using the UMA Bearer RPT profile:
GET /users/alice/album/photo.jpg HTTP/1.1 Authorization: Bearer vF9dft4qmT Host: photoz.example.com ...
If the resource server chooses to respond, it next determines the RPT's status (see Section 3.4).
If the client's request at the protected resource has no RPT, or has an invalid RPT or insufficient permissions associated with the RPT as determined through RPT status checking (see Section 3.4), then assuming the resource server chooses to respond to the client, it MUST use the protection API's permission endpoint to request permissions with the corresponding authorization server on the client's behalf. The extent of the set of requested permissions MUST suffice for the extent of the client's access attempt at that resource.
Note: The resource server is free to choose the extent of the requested permissions, as long as it minimally suffices for the access attempted by the client. For example, it can choose to request permission for access to a single resource with several scopes, or a set of permissions for multiple resources that together are greater in extent, than the specific resource and scope that the client attempted to access.
The PAT provided in the API request enables the authorization server to map the request to the appropriate resource owner. The authorization server returns a permission ticket in its response for the resource server to give to the client that represents the same extent of requested access that the resource server requested.
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:
Example of an HTTP request for a single-resource-set 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 a multiple-resource-set 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":"7b727369647d",
"scopes":[
"view",
"crop",
"lightbox"
]
},
{
"resource_id":"7b72736964327d",
"scopes":[
"view",
"layout",
"print"
]
},
{
"resource_id":"7b72736964337d",
"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.
See [UMA-Impl] for more information about permission ticket management.
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):
If the resource server chooses to respond to the client's access attempt, it has three possible paths.
If the client's request at a protected resource has no RPT, or has an invalid RPT or insufficient permissions associated with the RPT as determined through RPT status checking (see Section 3.4), and the resource server successfully requested one or more permissions and received a permission ticket (see Section 3.2), then assuming the resource server chooses to respond to the client with an UMA response, it MUST provide 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.
Example of the resource server's response to a client after having requested one or more permissions and received a permission ticket:
HTTP/1.1 401 Unauthorized WWW-Authenticate: UMA realm="example", as_uri="https://as.example.com", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" ...
On receiving a response from the resource server with permission ticket and authorization server location information, the client next seeks authorization (see Section 3.5).
If the client's request at the protected resource has no RPT, or has an invalid RPT or insufficient permissions associated with the RPT as determined through RPT status checking (see Section 3.4), and the resource server received an error of any kind from the authorization server when trying to request permissions such that it did not receive a permission ticket, then assuming the resource server chooses to respond to the client, it is unable to create a WWW-Authenticate: UMA header and MUST include 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's presentation of a valid RPT associated with sufficient permissions as determined through RPT status checking (see Section 3.4) indicates that the resource owner's policies have been met for access to the protected resource. The resource server MAY apply additional authorization controls when determining how to respond.
Example of the resource server's response to the client:
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 resource server MUST NOT give access in the case of an invalid RPT or an RPT associated with insufficient authorization. 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 in this case on a legal or contractual level. See Section 7.5 for more information.
If a client's request for a protected resource has an RPT (an example of which appears in Section 3.1.2), and the resource server chooses to respond to the client, then it MUST determine the RPT's status, including whether it is active and, if so, its associated permissions indicating whether the client is authorized for access before taking next actions.
Depending on the nature of the RPT as issued by the authorization server and on operative caching parameters, the resource server MAY take any of the following actions as appropriate to determine the RPT's status:
In the case of token introspection, the authorization server's response contains an extended version of the OAuth introspection object. A number of security considerations around handling and interpreting the RPT can be found throughout Section 3, and in Section 7.
The following sections describe the process when the resource server introspects the RPT at the authorization server and the form of the introspection object.
The resource server's request for introspection of an RPT MUST use the OAuth token introspection endpoint (defined by ERROR: Undefined target: RFC7662 (at line 1100)) 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.
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 ERROR: Undefined target: RFC7662 (at line 1124), 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 JSON object MUST NOT contain a scope claim, and MUST contain an extension property with the name permissions that contains an array of zero or more values, each of which is an object consisting of these properties:
Example:
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
}
]
}
If the client received a need_info error in response to its request for authorization, it has the opportunity to continue the authorization process.
If an error_details object was also returned with the error, then the contents of that object indicate the flow options.
If the authorization server can accept pushed claims (for example, as it might have indicated by providing requesting_party_claims hints illustrated in Section 3.5.4), the client has the option to push claim tokens to the token endpoint. The claim token can reflect the client's role as a federated identity provider, a federated relying party, or an application integrated with a native identity repository.
If the client is aware of the authorization server's requirements for claims through an out-of-band relationship, the client MAY push claim tokens in an initial interaction with the token endpoint.
The client supplies claim tokens in the body of the request message by providing, in addition to the rpt and ticket properties, the following property:
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 format profiling. The authorization server MAY support any number of claim token profiles, and SHOULD document the claim token profiles it supports in its configuration document.
If the authorization server has declared a claims interaction endpoint in its configuration document, or if the authorization server requires direct interaction with the requesting party as part of its claims collection process (for example, as it might have indicated through the redirect_user hint illustrated in Section 3.5.4), the client has the option to redirect an end-user requesting party to the claims interaction endpoint. In this case, the authorization server might be a relying party in a federated identity interaction, or it might connect to a directory or other user repository, or even interact with the user in other ways, such as presenting a questionnaire in a web form. After this process completes, the authorization server redirects the end-user requesting party back to the client.
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:
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 user agent to the client adding the following parameters to the query component of the claims redirection URI using the application/x-www-form-urlencoded format:
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:
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
As noted in Section 3.5.3.1, 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.
Both OAuth and UMA errors can occur.
As described in Section 1.3.1, the protection API requires a PAT for access. PATs are simply OAuth access tokens with appropriate scope. If a request to an endpoint in this API fails due to an invalid, missing, or expired access token, or requires higher privileges at this endpoint than provided by the token supplied, the authorization server responds with an OAuth error.
If a request triggers no OAuth error, but is invalid for another reason as defined throughout this specification, the authorization server or resource server responds with an UMA error, sometimes along with a specified HTTP status code, by supplying the following properties in a JSON-encoded object in the body of the HTTP response:
The following is a common error code that applies to several UMA-specified request messages:
For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...
{
"error":"invalid_request",
"error_description":"Request is missing a required parameter.",
"error_uri":"https://as.example.com/errors/bad_uma_request"
}
In some circumstances, it may be desirable to couple UMA software entity roles tightly. For example, an authorization server application might also need to act as a client application in order to retrieve protected resources so that it can present to resource owners a dashboard-like user interface that accurately guides the setting of policy; it might need to access itself-as-authorization server for that purpose. For another example, the same organization might operate both an authorization server and a resource server that communicate only with each other behind a firewall, and it might seek more efficient communication methods between them.
In other circumstances, it may be desirable to bind UMA flows to transport mechanisms other than HTTP even if entities remain loosely coupled. For example, in Internet of Things scenarios, Constrained Application Protocol (CoAP) may be preferred over HTTP.
This section defines profiles that allow inter-role communications channels and methods to vary in these circumstances. This specification still REQUIRES authorization servers to issue PATs, and RPTs and associate permissions with RPTs, and REQUIRES resource servers not to give access in the case of an invalid RPT or an RPT associated with insufficient authorization. This is because, although tokens might not always appear on the wire in the normal fashion, the tokens may represent sets of expected behaviors of additional parties unable to take part in these optimization opportunities.
Where alternate communications channels are being used between independently implemented system entities, it is RECOMMENDED, for reasons of implementation interoperability, to define concrete extension profiles that build on these extensibility profiles (see Section 6.1).
This section defines a profile for UMA where the authorization server and resource server roles either reside in the same system entity or otherwise have a privileged or specialized communications channel between them. Following is a summary:
Using this profile, the resource server MAY use means other than the HTTP-based protection API that is protected by TLS and OAuth (or an OAuth-based authentication protocol) to communicate with the authorization server in all respects, including using software interfaces and methods rather than network interfaces and APIs. The authorization server MUST still issue PATs and RPTs and associate permissions with RPTs, and the resource server still MUST NOT give clients access in the case of invalid RPTs or RPTs that are associated with insufficient permissions. Interactions with entities other than the authorization server or resource server MUST be preserved exactly as they would have if either of them were using standardized UMA APIs, unless other extensibility profiles are also in use.
An authorization server using any of the opportunities afforded by this profile MUST declare use of this profile by supplying its identifying URI for one of its uma_profiles_supported values in its configuration document (see Section 1.4).
Same-entity communication or a tight integration of entities has the opportunity to make deployments more secure by reducing possible attack vectors. However, if the entities do not use TLS but communicate across a transport layer, it is RECOMMENDED to use an alternate means of transport-layer security, for example, using DTLS in the case of a CoAP-based UMA profile.
Same-entity communication or a tight integration of entities has the potential to compromise privacy by promoting the freer exchange of personal information within a deployment ecosystem. It is RECOMMENDED to account for privacy impacts in each deployment scenario.
This section defines a profile for UMA where the authorization server and client roles either reside in the same system entity or otherwise have a privileged or specialized communications channel between them. Following is a summary:
Using this profile, the client MAY use means other than the HTTP-based authorization API that is protected by TLS and OAuth (or an OAuth-based authentication protocol) to communicate with the authorization server in all respects, including using software interfaces and methods rather than network interfaces and APIs. The authorization server MUST still issue PATs and RPTs and associate permissions with RPTs, and the resource server still MUST NOT give clients access in the case of invalid RPTs or RPTs that are associated with insufficient permissions. Interactions with entities other than the authorization server or client MUST be preserved exactly as they would have if either of them were using standardized UMA APIs, unless other extensibility profiles are also in use.
An authorization server using any of the opportunities afforded by this profile MUST declare use of this profile by supplying its identifying URI for one of its uma_profiles_supported values in its configuration document (see Section 1.4).
Same-entity communication or a tight integration of entities has the opportunity to make deployments more secure by reducing possible attack vectors. However, if the entities do not use TLS but communicate across a transport layer, it is RECOMMENDED to use an alternate means of transport-layer security, for example, using DTLS in the case of a CoAP-based UMA profile.
Same-entity communication or a tight integration of entities has the potential to compromise privacy by promoting the freer exchange of personal information within a deployment ecosystem. It is RECOMMENDED to account for privacy impacts in each deployment scenario.
This section defines a profile for UMA where the resource server and client roles either reside in the same system entity or otherwise have a privileged or specialized communications channel between them. Following is a summary:
Using this profile, the resource server MAY use means other than an HTTP-based resource interface to communicate with the authorization server in all respects, including using software interfaces and methods rather than network interfaces and APIs. The resource server still MUST NOT give clients access in the case of invalid RPTs or RPTs that are associated with insufficient permissions. Interactions with entities other than the resource server or client MUST be preserved exactly as they would have if either of them were using standardized UMA APIs, unless other extensibility profiles are also in use.
An authorization server involved in deployments where resource servers and clients are known to be using opportunities afforded by the resource interface extensibility profile MAY declare use of this profile by supplying its identifying URI for one of its uma_profiles_supported values in its configuration document (see Section 1.4).
Same-entity communication or a tight integration of entities has the opportunity to make deployments more secure by reducing possible attack vectors. However, if the entities do not use TLS but communicate across a transport layer, it is RECOMMENDED to use an alternate means of transport-layer security, for example, using DTLS in the case of a CoAP-based UMA profile.
Same-entity communication or a tight integration of entities has the potential to compromise privacy by promoting the freer exchange of personal information within a deployment ecosystem. It is RECOMMENDED to account for privacy impacts in each deployment scenario.
This specification defines a protocol that has optional features. For implementation interoperability and to serve particular deployment scenarios, including sector-specific ones such as healthcare or e-government, third parties may want to define profiles of UMA that restrict these options.
Further, this specification creates extensibility points for RPT profiles and claim token profiles, and third parties may likewise want to define their own. Different RPT profiles could be used, for example, to change the dividing line between authorization server and resource server responsibilities in controlling access. Different claim token profiles could be used to customize sector-specific or population-specific (such as individual vs. employee) claim types that drive the types of policies resource owners could set.
It is not practical for this specification to standardize all desired profiles. However, to serve overall interoperability goals, this section provides guidelines for third parties that wish to specify UMA-related profiles. In all cases, it is RECOMMENDED that profiles document the following information:
It is RECOMMENDED that profiles of UMA additionally document the following information:
See Section 5 for examples.
It is RECOMMENDED that RPT profiles additionally document the following information:
See Section 3.4.2 for an example.
It is RECOMMENDED that claim token format profiles additionally document the following information:
As a profile of OAuth, this specification relies mainly on OAuth security mechanisms as well as transport-level encryption. Thus, implementers are strongly advised to read [BCP195] and the security considerations in ERROR: Undefined target: RFC6749 (at line 2181) (Section 10) and ERROR: Undefined target: RFC6750 (at line 2182) (Section 5) along with the security considerations of any other OAuth token-defining specifications in use, along with the entire ERROR: Undefined target: RFC6819 (at line 2184) specification, and apply the countermeasures described therein. As well, since this specification builds on [OAuth-resource-reg], implementers should also take into account the security considerations in that specification.
The following sections describe additional security considerations.
This section discusses threats related to UMA's nature as a protocol enabling party-to-party sharing of protected resource access; that is, enabling requesting parties who are not the resource owner to gain authorized access to protected resources.
For privacy considerations related to requesting parties, see Section 8.2.
Like ordinary OAuth redirection, UMA redirection for the purpose of gathering claims from an end-user requesting party (described in Section 3.6.2) 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 ERROR: Undefined target: RFC6819 (at line 2215) 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 a Bearer-type 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.
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.
This section discusses security considerations related to UMA's use of OAuth and OpenID Connect.
Along with requiring TLS, UMA requires OAuth, or any OAuth-based authentication protocol, as the security mechanism for its protection API. The UMA 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 an UMA 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 UMA 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 MUST prevent attackers from guessing permission tickets and PCTs.
This specification defines a number of data formats based on ERROR: Undefined target: RFC7159 (at line 2361). As a subset of the JavaScript scripting language, JSON data SHOULD be consumed through a process that does not dynamically execute it as code, to avoid malicious code execution. One way to achieve this is to use a JSON parser rather than the built-in JavaScript eval() function.
Parties operating and using UMA software entities have opportunities to establish agreements about the parties' rights and responsibilities on a legal or contractual level, along with common interpretations of UMA constructs for consistent and expected software behavior. These agreements can be used to improve the parties' respective security postures, and written profiles are a key mechanism for conveying and enforcing these agreements. Section 6 discusses profiling. Section 5 discusses profiling for extensibility.
This section discusses the threats surrounding client claim pushing (see Section 3.6.1).
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 format profile, as described in Section 6 and Section 6.3. 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 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.
UMA has the following privacy considerations.
The authorization server comes to be in possession of resource information that may reveal information about the resource owner, which the authorization server's trust relationship with the resource server is assumed to accommodate. However, the client is a less-trusted party -- in fact, entirely untrustworthy until permissions are associated with its RPT. The more information about a resource that is registered, the more risk of privacy compromise there is through a less-trusted authorization server.
The primary privacy duty of UMA's design is to the resource owner. However, privacy considerations affect the requesting party as well. This can be seen in the optional issuance of a PCT, which enables an opportunity to optimize an access-seeking flow for a requesting party through persisting a set of collected claims across authorization processes, and can involve a requesting party's authorization for this persistence. Claims are likely to contain personally identifiable and possibly very sensitive information, and much like identity attributes exchanged during single sign-on, the process of claim pushing in particular will tend to be invisible to an end-user requesting party if they have not consciously authorized the possibility. A requesting party who provides claims to an authorization server once redirected there is less susceptible to privacy-destroying behavior.
Parties operating and using UMA software entities have opportunities to establish agreements about mutual rights, responsibilities, and common interpretations of UMA constructs for consistent and expected software behavior. These agreements can be used to improve the parties' respective privacy postures. See Section 7.5 for more information. Additional considerations related to Privacy by Design concepts are discussed in [UMA-PbD].
This document makes the following requests of IANA.
This specification registers the claim defined in Section 3.4.2.
This specification registers the claim defined in Section 3.4.2.
This specification registers the well-known URI defined in Section 1.4.
The following people made significant text contributions to the specification:
Additional contributors to this specification include the Kantara UMA Work Group participants, a list of whom can be found at [UMAnitarians].
| [BCP195] | Sheffer, Y., “Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)”, May 2015, <https://tools.ietf.org/html/bcp195>. |
| [OAuth-resource-reg] | Hardjono, T., “OAuth 2.0 Resource Registration”, December 2015, <https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html>. |
| [OIDCCore] | Sakimura, N., “OpenID Connect Core 1.0 incorporating errata set 1”, November 2014, <http://openid.net/specs/openid-connect-core-1_0.html>. |
| [OIDCDynClientReg] | Sakimura, N., “OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1”, November 2014, <http://openid.net/specs/openid-connect-registration-1_0.html>. |
| [UMA-casestudies] | Maler, E., “UMA Case Studies”, 2016, <https://kantarainitiative.org/confluence/display/uma/Case+Studies>. |
| [UMA-Impl] | Maler, E., “UMA Implementer's Guide”, 2016, <https://kantarainitiative.org/confluence/display/uma/UMA+Implementer%27s+Guide>. |
| [UMA-PbD] | Maler, E., “Privacy by Design Implications of UMA”, December 2013, <https://kantarainitiative.org/confluence/display/uma/Privacy+by+Design+Implications+of+UMA>. |
| [UMA-usecases] | Maler, E., “UMA Scenarios and Use Cases”, October 2010, <https://kantarainitiative.org/confluence/display/uma/UMA+Scenarios+and+Use+Cases>. |
| [UMAnitarians] | Maler, E., “UMA Participant Roster”, 2016, <https://kantarainitiative.org/confluence/display/uma/Participant+Roster>. |
Eve Maler
(editor)
ForgeRock
EMail: eve.maler@forgerock.com
Maciej Machulak
iWelcome
EMail: maciej.machulak@iwelcome.com
Justin Richer
Bespoke Engineering
EMail: justin@bspk.io