| Version: | 1.0.1 |
| � | |
| Date: | 2015-09-01 |
| � | |
| Editor: | Thomas Hardjono, MIT |
| � | |
| Contributors: | Eve Maler, ForgeRock |
| Maciej Machulak, Cloud Identity Ltd | |
| Domenico Catalano, Oracle | |
User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policies.
This specification was developed by the User-Managed Access Work Group and approved by the Leadership Council as a Draft Recommendation according to the Kantara Initiative Operating Procedures.
Copyright (c) 2015 Kantara Initiative and the persons identified as the document authors. All rights reserved.
This document is subject to theKantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND) (HTML version)
User-Managed Access (UMA) is a profile of OAuth 2.0 [RFC6749]. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policies. Resource owners configure authorization servers with access policies that serve as asynchronous authorization grants.
UMA serves numerous use cases where a resource owner uses a dedicated service to manage authorization for access to their resources, potentially even without the run-time presence of the resource owner. A typical example is the following: a web user (an end-user resource owner) can authorize a web or native app (a client) to gain one-time or ongoing access to a protected resource containing his home address stored at a "personal data store" service (a resource server), by telling the resource server to respect access entitlements issued by his chosen cloud-based authorization service (an authorization server). The requesting party operating the client might be the resource owner, where the app is run by an e-commerce company that needs to know where to ship a purchased item, or the requesting party might be resource owner's friend who is using an online address book service to collect contact information, or the requesting party might be a survey company that uses an autonomous web service to compile population demographics. A variety of use cases can be found in [UMA-usecases] and [UMA-casestudies].
Practical control of access among loosely coupled parties requires more than just messaging protocols. This specification defines only the "technical contract" between UMA-conforming entities. Work is ongoing to define recommendations for developing agreements about the rights and responsibilities of parties operating and using these entities on a contractual or legal level (see, for example, [UMA-obligations]). Parties operating entities that claim to be UMA-conforming should provide documentation of any rights and obligations between and among them, especially as they pertain to the concepts and clauses discussed in this companion specification.
In enterprise settings, application access management sometimes involves letting back-office applications serve only as policy enforcement points (PEPs), depending entirely on access decisions coming from a central policy decision point (PDP) to govern the access they give to requesters. This separation eases auditing and allows policy administration to scale in several dimensions. UMA makes use of a separation similar to this, letting the resource owner serve as a policy administrator crafting authorization strategies for resources under their control.
In order to increase interoperable communication among the authorization server, resource server, and client, UMA leverages two purpose-built APIs related to the outsourcing of authorization, themselves protected by OAuth (or an OAuth-based authentication protocol) in embedded fashion.
The UMA protocol has three broad phases, as shown in Figure�1.
The Three Phases of the UMA Profile of OAuth
+--------------+
| resource |
+---------manage (A)------------ | owner |
| +--------------+
| Phase 1: |
| protect a control (C)
| resource |
v v
+------------+ +----------+--------------+
| | |protection| |
| resource | | API | authorization|
| server |<-protect (B)--| (needs | server |
| | | PAT) | |
+------------+ +----------+--------------+
| protected | | authorization|
| resource | | API |
|(needs RPT) | | (needs AAT) |
+------------+ +--------------+
^ |
| Phases 2 and 3: authorize (D)
| get authorization, |
| access a resource v
| +--------------+
+---------access (E)-------------| client |
+--------------+
requesting party
Figure 1
The phases work as follows:
Implementers have the opportunity to develop profiles (see Section�6) that specify and restrict various UMA protocol, RPT, and identity claim format options, according to deployment and usage conditions.
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 [RFC2119].
Unless otherwise noted, all protocol properties and values are case sensitive. JSON [RFC7159] 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 Section 1.6 of [RFC6749], 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 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 data (see Section�1.4).
The protection API consists of three endpoints:
An entity seeking protection API access MUST have the scope "uma_protection". An access token with at least this scope is called a protection API token (PAT) and an entity that can acquire an access token with this scope is by definition a resource server. A single entity can serve in both resource server and client roles if it has access tokens with the appropriate OAuth scopes. 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.
The authorization server MUST support the OAuth bearer token profile for PAT issuance, and MAY support other OAuth token profiles. It MUST declare all supported token profiles and grant types for PAT issuance in its configuration data. 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. [UMA-Impl] discusses grant options further.
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.
Note: When a client attempts access to a presumptively protected resource without an RPT, the resource server needs to derive the authorization server and resource set identifier associated with that resource from some other aspect of the client's request. This effectively means that the resource server’s API needs to be structured in such a way that the client's RPT-free request uniquely identifies the resource set. In practice, this information likely needs to be passed through the URI, headers, or body of the request.
The resource server MAY present to clients whatever HTTP-based APIs or endpoints it wishes. To protect any of its resources available in this fashion using UMA, it MUST require a requesting party token (RPT) with sufficient authorization data for access.
This specification defines one RPT profile, call "bearer" (see Section�3.6.2), which the authorization server MUST support. It MAY support additional RPT profiles, and MUST declare all supported RPT profiles in its configuration data (see Section�1.4).
An RPT binds a requesting party, the client being used by that party, the resource server at which protected resources of interest reside, and the authorization server that protects those resources. It is not specific to a single resource owner, though its internal components are likely to be bound in practice to individual resource owners, depending on the RPT profile in use.
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 authorization data components associated with RPTs where applicable, and even the client credentials that it issues. Different time-to-live strategies may be suitable for different resource sets and scopes of access, and the authorization server has the opportunity to give the resource owner control over lifetimes of tokens and authorization data issued on their behalf through policy. These options are all outside the scope of this specification.
The authorization server MUST provide configuration data in a JSON document that resides in an /uma-configuration directory at its host-meta [RFC6415] location. The configuration data documents conformance options and endpoints supported by the authorization server.
The configuration data has the following properties.
Example of authorization server configuration data that resides at https://example.com/.well-known/uma-configuration (note the use of https: for endpoints throughout):
{
"version":"1.0",
"issuer":"https://example.com",
"pat_profiles_supported":["bearer"],
"aat_profiles_supported":["bearer"],
"rpt_profiles_supported":
["https://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0"],
"pat_grant_types_supported":["authorization_code"],
"aat_grant_types_supported":["authorization_code"],
"claim_token_profiles_supported":["https://example.com/claims/formats/token1"],
"dynamic_client_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",
"requesting_party_claims_endpoint":"https://as.example.com/rqp_claims_uri",
"resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri",
"introspection_endpoint":"https://as.example.com/rs/status_uri",
"permission_registration_endpoint":"https://as.example.com/rs/perm_uri",
"rpt_endpoint":"https://as.example.com/client/rpt_uri"
}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 configuration data to indicate their usage.
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 data 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 set has been placed under authorization server protection through the registration of a resource set description for it, and until such a description's deletion by the resource server, the resource server MUST limit access to corresponding resources, requiring sufficient authorization data associated with client-presented RPTs by the authorization server (see Section�3.3).
Note: When a client attempts access to a presumptively protected resource without an RPT, the resource server needs to derive the authorization server and resource set identifier associated with that resource from some other aspect of the client's request. This effectively means that the resource server’s API needs to be structured in such a way that the client's RPT-free request uniquely identifies the resource set. In practice, this information likely needs to be passed through the URI, headers, or body of the 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 dictated by that resource owner.
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 resource sets 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 /album/photo.jpg HTTP/1.1 Host: photoz.example.com ...
If the resource server chooses to respond, it next registers a requested permission (see Section�3.2).
Example of a client request at a protected resource carrying an RPT using the UMA "bearer" RPT profile:
GET /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.6).
If the client's request at the protected resource has no RPT, or an invalid RPT or insufficient authorization data associated with the RPT as determined through RPT status checking (see Section�3.6), then assuming the resource server chooses to respond to the client, it MUST use the protection API's permission registration endpoint to register a requested permission with the corresponding authorization server. The extent of the requested permission 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 permission that it registers, as long as it minimally suffices for the access attempted by the client. For example, it can choose to register a permission that covers several scopes or a resource set that is greater in extent than the specific resource that the client attempted to access.
The PAT provided in the API request enables the authorization server to map the requested permission to the appropriate resource owner. The authorization server returns a permission ticket for the resource server to give to the client in its response that represents what the resource server registered.
The resource server uses the POST method at the permission registration endpoint. The body of the HTTP request message contains a JSON object providing the requested permission, using a format derived from the scope description format specified in [OAuth-resource-reg], as follows. The object has the following properties:
Example of an HTTP request that registers a requested permission at the authorization server's permission registration 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_set_id": "112210f47de98100",
"scopes": [
"http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"
]
}
The authorization server uses a permission ticket to maintain the state of requested permission information, 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 permission ticket is a short-lived structure, opaque to resource servers and clients, whose form is determined by the authorization server. The ticket value MUST be securely random (for example, not merely part of a predictable sequential series), to avoid denial-of-service attacks. Since the ticket is an opaque structure from the point of view of the client, the authorization server is free to include information regarding expiration time or any other information within the opaque ticket for its own consumption.
Since permission tickets are used only by clients bearing an AAT at the authorization server, the authorization server can associate a permission ticket with both a client and a requesting party at the time the client first makes a request at the RPT endpoint. If the authorization server observes that a permission ticket is used by multiple different clients, it SHOULD attempt to revoke all RPTs already granted based on the compromised permission ticket.
Permission tickets MUST NOT be single-use to allow the client to interact with the authorization server during the claims-gathering flow, which may require multiple interactions, either direct or through redirection of a requesting party.
The authorization server MUST invalidate a permission ticket when an RPT is successfully granted to a client based on this permission ticket 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 (see Section�3.2.2) in response to the resource server's request, 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):
If the client's request at a protected resource has no RPT, an invalid RPT, or insufficient authorization data associated with the RPT as determined through RPT status checking (see Section�3.6), and the resource server successfully registered a requested permission 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 authorization server's URI in an "as_uri" parameter and the just-received permission ticket in a "ticket" parameter.
If it responds with the HTTP status code 403 (Forbidden), it MAY also return the permission ticket in the body in a JSON-encoded "ticket" property. Note: The appearance of the permission ticket in a response body is deprecated and will be removed in a future UMA version. It is included here for backwards compatibility.
Example of the resource server's response to a client after having registered a requested permission and received a ticket:
HTTP/1.1 401 Unauthorized WWW-Authenticate: UMA realm="example", as_uri="https://as.example.com", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" ...
Alternate example:
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example",
as_uri="https://as.example.com"
error="insufficient_scope"
{
"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.7).
If the client's request at the protected resource has no RPT, or an invalid RPT or insufficient authorization data associated with the RPT as determined through RPT status checking (see Section�3.6), and the resource server received an error of any kind from the authorization server when trying to register a requested permission 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 ...
If the client's request at the protected resource has a valid RPT associated with sufficient authorization data as determined through RPT status checking (see Section�3.6), then assuming the resource server chooses to respond to the client, it MUST give access to the desired resource.
Example of the resource server's response to the client after having determined that the RPT is valid and associated with sufficient authorization data:
HTTP/1.1 200 OK Content-Type: image/jpeg ... /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb
The resource server MUST NOT give access where the token's status is not associated with sufficient authorization data for the attempted scope of access.
If a client's request at a protected endpoint has an RPT, 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 authorization data before taking next actions.
An RPT is associated with a set of authorization data that governs whether the client is authorized for access. The token's nature and format are dictated by its profile; the profile might allow it to be self-contained, such that the resource server is able to determine its status locally, or might require or allow the resource server to make a run-time introspection request of the authorization server that issued the token.
This specification makes one type of RPT REQUIRED for the authorization server to support: the UMA bearer token profile, as defined in Section�3.6.2. Implementers MAY define and use other RPT profiles.
Within any RPT profile, when a resource server needs to introspect a token in a non-self-contained way to determine its status, it MAY require, allow, or prohibit use of the OAuth token introspection endpoint (defined by [OAuth-introspection]) that is part of the protection API, and MAY profile its usage.
This section defines the UMA bearer token profile. Following is a summary:
An example of a client making a request with an RPT using the "Bearer" scheme appears in Section�3.1.2.
On receiving an RPT with the "Bearer" scheme in an authorization header from a client making an access attempt, the resource server introspects the token by using the token introspection endpoint of the protection API. The PAT used by the resource server to make the introspection request provides resource-owner context to the authorization server.
The authorization server responds with a JSON object with the structure dictated by [OAuth-introspection]. 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_set_id": "112210f47de98100",
"scopes": [
"http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"
],
"exp" : 1256953732
}
]
}
If the client received a "need_info" error in response to its request for authorization, it has the opportunity to continue seeking authorization by engaging in follow-on flows with the authorization server, either directly or through redirection of an end-user requesting party. This process is sometimes known as "trust elevation".
If an "error_details" object was also returned with the error, then the contents of that object indicate the flow options.
The "authentication_context" sub-property of the "error_details" object provides hints about additional requirements regarding the requesting party's authentication that underlies the issuance of the currently valid AAT. On receiving such hints, the client has the opportunity to redirect the requesting party to the authorization server to reauthenticate in a manner anticipated to be more successful for gaining access. Such an action is sometimes referred to as "step-up" authentication. The "authentication_context" sub-property contains the following parameter:
The "requesting_party_claims" sub-property of the "error_details" object 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 in claims-gathering flows of various types. The "requesting_party_claims" sub-property MAY contain the following parameters, where at least one of "required_claims" or "redirect_user" MUST be supplied:
An example of the use of these properties appears in Section�3.7.4.
The authorization server has many options for gathering requesting party claims. For example, it could interact with an end-user requesting party directly, or accept claims delivered by a client, or perform a lookup in some external system. The process is extensible and can have dependencies on the type of requesting party (for example, natural person or legal person) or client (for example, browser, native app, or autonomously running web service).
The client and authorization server have two nonexclusive claims-gathering interaction patterns: push and redirect. (See Section�7 for important security considerations regarding claims gathering.)
If the client is claims-aware and the authorization server can accept pushed claims (for example, as it might have indicated by providing "requesting_party_claims" hints illustrated in Section�3.7.4), the client has the option to push claim tokens to the RPT 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 RPT endpoint.
The client supplies claim tokens in the body of the authorization data request message by providing, in addition to the "rpt" and "ticket" properties, the following property:
Example:
POST /rpt_authorization 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 data.
If the client is claims-unaware and the authorization server has declared a requesting party claims endpoint in its configuration data, or if the authorization server requires direct interaction with the requesting party as part of its claims-gathering process (for example, as it might have indicated through the "redirect_user" hint illustrated in Section�3.7.4), the client has the option to redirect an end-user requesting party to the requesting party claims 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 requesting party claims 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 &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 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 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 redirection URI, the authorization server informs the client by adding an "error" parameter to the query component of the 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
Ultimately the resource server is responsible for either granting the access the client attempted, or returning an error response to the client with a reason for the failure. [RFC6749] defines several error responses for a resource server to return. UMA makes use of these error responses, but requires the resource server to "outsource" the determination of some error conditions to the authorization server. This specification defines additional UMA-specific error responses that the authorization server may give to the resource server and client as they interact with it, and that the resource server may give to the client.
When a resource server or client attempts to access one of the authorization server endpoints or a client attempts to access a protected resource at the resource server, it has to make an authenticated request by including an OAuth access token in the HTTP request as described in [RFC6749] Section 7.2.
If the request failed authentication, the authorization server or the resource server responds with an OAuth error message as described in this specification in Section�3.
When a resource server or client attempts to access one of the authorization server endpoints or a client attempts to access a protected resource at the resource server, if the request is successfully authenticated by OAuth means, but is invalid for another reason, the authorization server or resource server responds with an UMA error response by adding the following properties to the entity 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": "There is already a resource with this identifier.",
"error_uri": "https://as.example.com/errors/resource_exists"
}
In some circumstances, it may be desirable to couple UMA 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, AATs, and RPTs and associate authorization data with RPTs, and REQUIRES resource servers to give clients access only when RPTs are associated with sufficient authorization data. 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, AATs, and RPTs and associate authorization data with RPTs, and the resource server MUST still give clients access only when RPTs are associated with sufficient authorization data. 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 data (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, AATs, and RPTs and associate authorization data with RPTs, and the resource server MUST still give clients access only when RPTs are associated with sufficient authorization data. 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 data (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 MUST still give clients access only when RPTs are associated with sufficient authorization data. 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 data (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.6.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 the security considerations in [RFC6749] (Section 10) and [RFC6750] (Section 5) along with the security considerations of any other OAuth token-defining specifications in use, along with the entire [RFC6819] 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 an protocol enabling autonomous (non-resource-owner) requesting parties to gain authorized access to sensitive resources, including through the process of claims-gathering redirection.
Like ordinary OAuth redirection, UMA redirection for the purpose of gathering claims from an end-user requesting party (described in Section�3.8.2.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 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 redirect is completed has not been maliciously changed, for example by a man in the browser (MITB), by using the state parameter. (See the [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 requesting party claims 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 approved the minting of of the AAT -- after the redirect completes and before it returns to the RPT endpoint to seek authorization data.
Another issue concerns the exposure of the RPT to an autonomous 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.
Along with TLS, UMA requires OAuth, or any OAuth-based authentication protocol, as the security mechanism for its standardized APIs. The UMA resource server acts in the role of an OAuth client at the authorization server's protection API, and the UMA client acts in the role of an OAuth client at the authorization server's authorization 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 OpenID Connect doesn't help because of the nature of the implicit grant flow. UMA scenarios are vulnerable as well. For example, an "implicit client" might require the retrieval of AATs more frequently, for each browser on each platform. An attacker can initiate a spear phishing attack on the requesting party with a link to a malicious website, relying on the requesting party to authenticate to the authorization server through an email-based identity provider in order to receive the AAT. The site can impersonate the requesting party using the browser client's client ID in an OpenID Connect implicit request to the UMA authorization server. If the requesting party had previously given consent for an AAT to be issued, this attempt will likely succeed. The subsequently issued AAT and permission ticket for an attempted resource access could potentially be used for RPT retrieval and authorization data issuance.
A number of mitigation strategies are possible.
This specification defines a number of data formats based on [RFC7159]. 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 JavaScript interpreter 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.
In contrast to the threats discussed in Section�7.1, regarding the redirection model for claims-gathering (see Section�3.8.2.2), this section discusses the threats surrounding the model for claims-gathering where the client is the source of claims (see Section�3.8.2.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 STRONGLY 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 STRONGLY 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 RPT endpoint.
The authorization server comes to be in possession of resource set 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 authorization data is associated with its RPT. The more information about a resource set 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 issuance of an AAT, which represents the approval of a requesting party for a client to engage with an authorization server to perform tasks needed for obtaining authorization, possibly including pushing claim tokens.
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.4 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.6.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].
| [UMA-usecases] | Maler, E., “UMA Scenarios and Use Cases”, October�2010, <http://kantarainitiative.org/confluence/display/uma/UMA+Scenarios+and+Use+Cases>. |
| [UMA-obligations] | Maler, E., “Binding Obligations on UMA Participants”, January�2013, <http://docs.kantarainitiative.org/uma/draft-uma-trust.html>. |
| [UMA-casestudies] | Maler, E., “UMA Case Studies”, 2015, <http://kantarainitiative.org/confluence/display/uma/Case+Studies>. |
| [UMAnitarians] | Maler, E., “UMA Participant Roster”, 2015, <http://kantarainitiative.org/confluence/display/uma/Participant+Roster>. |
| [UMA-PbD] | Maler, E., “Privacy by Design Implications of UMA”, December�2013, <http://kantarainitiative.org/confluence/display/uma/Privacy+by+Design+Implications+of+UMA>. |
| [UMA-Impl] | Maler, E., “UMA Implementer's Guide”, 2015, <http://kantarainitiative.org/confluence/display/uma/UMA+Implementer%27s+Guide>. |
Thomas Hardjono
(editor)
MIT
EMail: hardjono@mit.edu
Eve Maler
ForgeRock
EMail: eve.maler@forgerock.com
Maciej Machulak
Cloud Identity
EMail: maciej.machulak@cloudidentity.co.uk
Domenico Catalano
Oracle
EMail: domenico.catalano@oracle.com