Network Working Group | T. Hardjono, Ed. |
Internet-Draft | MIT |
Intended status: Standards Track | June 27, 2013 |
Expires: December 29, 2013 |
User-Managed Access (UMA) Profile of OAuth 2.0
draft-hardjono-oauth-umacore-07d
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 policy.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 29, 2013.
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. 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 policy. Resource owners configure authorization servers with access policies that serve as implicit authorization grants. Thus, the UMA profile of OAuth can be considered to encompass an authorization grant flow.
UMA serves numerous use cases where a resource owner outsources 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 app (client) to gain one-time or ongoing access to a protected resource containing his home address stored at a "personal data store" service (resource server), by telling the resource server to respect access entitlements issued by his chosen cloud-based authorization service (authorization server). The requesting party operating the client might be the resource owner himself, using a web or native app run by an e-commerce company that needs to know where to ship a purchased item, or it might be his friend who is using an online address book service to collect contact information, or it might be a survey company that uses an autonomous web service to compile population demographics. A variety of scenarios and 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; its companion Binding Obligations specification [UMA-obligations] defines the expected behaviors of parties operating and using these entities. Parties operating entities that claim to be UMA-conforming MUST provide documentation affirmatively stating their acceptance of the binding obligations contractual framework defined in the Binding Obligations 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 defines several purpose-built APIs related to the outsourcing of authorization, themselves protected by OAuth 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 (B) | resource | v v +------------+ +----------+--------------+ | | |protection| | | resource | | API | authorization| | server |<-protect (C)--| (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 are anticipated to develop profiles (see Section 5) that specify and restrict various UMA protocol, RPT, and identity claim 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 the protocol properties and values are case sensitive.
UMA introduces the following new terms and enhancements of OAuth term definitions.
UMA involves three APIs, all of which are protected.
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 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 resources 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 presents a protection API to the resource server and an authorization API to the client. These APIs MUST be OAuth-protected; thus, the authorization server has an OAuth token endpoint and user authorization endpoint, and has the option to issue an OAuth refresh token along with any access tokens issued for these APIs.
The protection API consists of an OAuth resource set registration endpoint as defined by [OAuth-resource-reg], an endpoint for registering client-requested permissions, and an OAuth token introspection endpoint as defined by [OAuth-introspection]. This specification profiles the endpoints defined by these other specifications.
The authorization API consists of an RPT issuance endpoint and an authorization request endpoint.
All endpoint URIs SHOULD require the use of a transport-layer security mechanism such as TLS. The authorization server MUST declare all of its endpoints in its configuration data (see Section 1.4).
An entity seeking protection API access MUST request the scope "http://docs.kantarainitiative.org/uma/scopes/prot.json", and an access token with at least this scope is called a protection API token (PAT). An entity seeking authorization API access MUST request the scope "http://docs.kantarainitiative.org/uma/scopes/authz.json", and an access token with at least this scope is called an authorization API token (AAT). The same entity can serve in both roles, so that an OAuth access token might be considered both a PAT and an AAT if it has both scopes. If a request to an endpoint fails due to an invalid, missing, or expired PAT or AAT, or requires higher privileges at this endpoint than provided by the PAT or AAT, the authorization server responds with an OAuth error.
Note: These scope keywords are URIs that resolve to JSON-encoded scope descriptions, as defined in [OAuth-resource-reg]. These scope descriptions are non-normative for the purposes of PATs and AATs.
The authorization server is REQUIRED to support the OAuth bearer token profile for PAT and AAT issuance, and MAY support other OAuth token profiles for these purposes. It MUST declare all supported token profiles for PAT and AAT issuance in its configuration data. The authorization server MAY support the use of any OAuth grant type for PAT and AAT issuance, but MUST support the authorization_code grant type, and SHOULD support the SAML bearer token grant type [OAuth-SAML] (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates working with entities that are operating in environments where the use of SAML is prevalent. It MUST declare its supported grant types for PAT and AAT issuance in its configuration data.
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 trust this authorization server for protecting its resources belonging to this resource owner.
An AAT binds a requesting party, a client being used by that party, and an authorization server that protects resources this client is seeking access to on this requesting party's behalf. It is not specific to any resource server or resource owner. The issuance of an AAT represents the approval of this requesting party for this client to engage with this authorization server to supply claims, ask for authorization, and perform any other tasks needed for obtaining authorization for access to resources at all resource servers that use this authorization server. The authorization server is able to manage future processes of authorization and claims-caching efficiently for this client/requesting party pair across all resource servers they try to access. These management processes are outside the scope of this specification, however.
The resource server presents one or more protected resource endpoints to the client; these endpoints are protected by the UMA profile of OAuth and require a requesting party token (RPT) with sufficient authorization data for access. This specification defines one RPT profile, call "bearer" (see Section 3.3.2), which is REQUIRED for the authorization server to support. It MAY support additional RPT profiles. It MUST declare all supported RPT profiles in its configuration data.
An RPT represents a binding of 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 to individual resource owners, depending on the RPT profile in use.
The authorization server MUST provide configuration data in a JSON [RFC4627] document that resides in an /uma-configuration directory at at its hostmeta [hostmeta] location. The configuration data documents conformance options and endpoints supported by the authorization server. (At the appropriate time, this section will instead profile whatever self-describing metadata specification OAuth adopts, for example, [OAuth-linktypes] or [OAuth-meta].)
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":["bearer"], "pat_grant_types_supported":["authorization_code"], "aat_grant_types_supported":["authorization_code"], "claim_profiles_supported":["openid"], "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", "token_endpoint":"https://as.example.com/token_uri", "user_endpoint":"https://as.example.com/user_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", "authorization_request_endpoint":"https://as.example.com/client/perm_uri" }
Authorization server configuration data MAY contain extension properties that are not defined in this specification. Extension names that are unprotected from collisions are outside the scope of this specification.
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, respecting authorization data associated with client-presented RPTs by the authorization server as appropriate (see Section 3.1.2).
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. How the client came to learn about this endpoint is out of scope for this specification. The resource owner might, for example, have advertised its availability publicly on a blog or other website, listed it in a discovery service, or emailed a link to a particular intended requesting party.
The resource server responds to the client's access request with whatever its application-specific interface defines as a success response, either immediately or having first performed one or more embedded interactions with the authorization server. Depending on the nature of the resource server's response to an failed access attempt, the client and its requesting party engage in embedded interactions with the authorization server before re-attempting access.
The interactions are as follows. Each interaction MAY be the last, if the client chooses not to continue pursuing the access attempt or the resource server chooses not to continue facilitating it.
The interactions are described in detail in the following sections.
This interaction assumes that the resource server has previously registered one or more resource sets that correspond to the resource to which access is being attempted.
The client attempts to access a protected resource (for example, when an end-user requesting party clicks on a thumbnail representation of the resource to retrieve a larger version). It is expected to discover, or be provisioned or configured with, knowledge of the protected resource and its location out of band. Further, the client is expected to acquire its own knowledge about the application-specific methods made available by the resource server for operating on this protected resource (such as viewing it with a GET method, or transforming it with some complex API call) and the possible scopes of access.
The access attempt either is or is not accompanied by an RPT.
Example of a request carrying no RPT:
GET /album/photo.jpg HTTP/1.1 Host: photoz.example.com ...
If the client does not present an RPT with the request, the resource server MUST return an HTTP 401 (Unauthorized) status code, along with providing the authorization server's URI in an "as_uri" property to facilitate authorization server configuration data discovery, including discovery of the endpoint where the client can request an RPT (Section 3.4.1).
For example:
HTTP/1.1 401 Unauthorized WWW-Authenticate: UMA realm="example", host_id="photoz.example.com", as_uri="https://as.example.com" ...
Example of a request 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 client presents an RPT with its request, the resource server MUST determine the RPT's status (see Section 3.3) before responding.
If the RPT is invalid, the resource server MUST return an HTTP 401 (Unauthorized) status code, along with providing the authorization server's URI in an "as_uri" property in the header, similarly to the case where no RPT was presented.
If the RPT is valid but has insufficient authorization data for the type of access sought, the resource server SHOULD register a requested permission with the authorization server that would suffice for that scope of access (see Section 3.2), and then respond with the HTTP 403 (Forbidden) status code, along with providing the authorization server's URI in an "as_uri" property in the header, and the permission ticket it just received from the AM in the body in a JSON-encoded "ticket" property.
Example of the host's response after having registered a requested permission and received a ticket:
HTTP/1.1 403 Forbidden WWW-Authenticate: UMA realm="example", host_id="photoz.example.com", as_uri="https://as.example.com" error="insufficient_scope" { "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" }
If the RPT's status is associated with authorization data that is consistent with authorized access of the scope sought by the client, the resource server MUST give access to the desired resource.
Example of the resource server's response after having determineed 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.
In response to receiving an access request accompanied by an RPT that has insufficient authorization data, the resource server registers a permission with the authorization server that would be sufficient for the type of access sought. The authorization server returns a permission ticket for the resource server to give to the client in its response.
The resource server MUST provide its valid PAT in order to get access to this endpoint. Note that this PAT implicitly identifies the resource owner ("subject") to which the permission applies.
The permission ticket is a short-lived opaque structure 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 within the opaque ticket for its own consumption. When the client subsequently asks the authorization server for authorization data to be associated with its RPT, it will submit this ticket to the authorization server.
The resource server registers the requested permission using the POST method at the authorization server's permission registration endpoint. The resource server MUST provide its valid PAT in order to get access to this 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:
POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 Content-Type: application/json Host: as.example.com { "resource_set_id": "112210f47de98100", "scopes": [ "http://photoz.example.com/dev/actions/view", "http://photoz.example.com/dev/actions/all" ] }
If the registration request is successful, the authorization server responds with an HTTP 201 (Created) status code and includes the Location header in its response as well as the "ticket" property in the JSON-formatted body.
For example:
HTTP/1.1 201 Created Content-Type: application/json Location: https://as.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 ... { "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" }
If the 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):
The resource server determines a received RPT's status, including both its validity and, if valid, its associated authorization data, before giving or refusing access to the client. 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 mandatory to implement: the UMA bearer token profile, as defined in Section 3.3.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 MUST use the authorization server's OAuth introspection endpoint, defined by [OAuth-introspection]. Any UMA token profile MAY require, allow, or prohibit use of the token introspection endpoint, and MAY profile its usage. The authorization server MUST OAuth-protect this endpoint and require a PAT from the resource server for access to it. The resource server MUST use the POST method in interacting with the endpoint, not the GET method also defined by [OAuth-introspection].
This section defines the UMA bearer token profile. Following is a summary:
On receiving an RPT of the "Bearer" type in an authorization header from a client making an access attempt, the resource server MUST introspect the token by using the authorization server's token introspection endpoint. 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 valid property has a "true" value, then the JSON object MUST also 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 { "valid": true, "expires_at": "1256953732", "issued_at": "1256912345", "permissions": [ { "resource_set_id": "112210f47de98100", "scopes": [ "http://photoz.example.com/dev/actions/view", "http://photoz.example.com/dev/actions/all" ], "expires_at" : "1256923456" } ] }
In order to access a protected resource successfully, a client needs to present a valid RPT with sufficient authorization data for access. To get to this stage requires a number of previously successful steps:
The client might need an RPT if it has never before requested an RPT for this combination of requesting party, resource server, and authorization server, or if it has lost control of a previously issued RPT and needs a refreshed one. It obtains an RPT by performing a POST on the RPT endpoint. It MUST provide its own valid AAT in the header.
Example of a request message containing an AAT:
POST /rpt HTTP/1.1 Host: as.example.com Authorization: Bearer jwfLG53^sad$#f ...
The authorization server responds with an HTTP 201 (Created) status code and provides a new RPT.
For example:
HTTP/1.1 201 Created Content-Type: application/json { "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" }
If the AAT provided in the header is the same as one provided for a previously issued still-valid RPT by this authorization server, the authorization server invalidates the old RPT and issues a new one.
On first issuance, the RPT is associated with no authorization data and thus does not convey any authorizations for access.
Once in possession of an AAT for this authorization server, an RPT that applies to this requesting party for this resource server and this authorization server, and a permission ticket, the client asks the authorization server to give it suitable authorization data for the sought-for access. It performs a POST on the authorization request endpoint, supplying its own AAT in the header and its RPT and the permission ticket in a JSON object with properties "rpt" and ticket", respectively.
Example of a request message containing an AAT, an RPT, and a permission ticket:
POST /token_status HTTP/1.1 Host: as.example.com Authorization: Bearer jwfLG53^sad$#f ... { "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" }
The authorization server uses the ticket to look up the details of the previously registered requested permission, maps the requested permission to operative resource owner policies based on the resource set identifier and scopes in it, undergoes any claims-gathering flows required (see Section 3.5), and ultimately responds to the request. The resource owner's policies at the authorization server amount to an implicit authorization grant in governing the issuance of authorization data. (The authorization server is also free to enable the resource owner to set policies that require the owner to provide a run-time authorization grant in the form of a consent interaction, mediated by the authorization server. This setting of policies and gathering of consent is outside the scope of this specification.)
The authorization server MUST base the addition of authorization data to RPTs on user policies. The nature of these policies is outside the scope of UMA, but generally speaking, they can be thought of as either independent of requesting-party features (for example, time of day) or dependent on requesting-party features (for example, whether they are over 18). Such requesting-party features can potentially be collected in a claims-gathering flow. If the authorization server does not add the requested authorization data, it responds using the appropriate HTTP status code and UMA error code (see Section 4.2):
For example:
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store ... { "status": "error", "error": "expired_ticket" }
The process for requesting and providing claims is extensible and may have a variety of dependencies on the type of requesting party (for example, natural person or legal person) and the type of client (for example, browser, native app, or autonomously running web service). This specification provides a framework for handling end-user-driven clients and an optional "openid" claim profile, based on OpenID Connect, for gathering standardized claims from such an end-user. It also allows for the definition of additional claim profiles. The authorization server MAY support any number of claim profiles, and SHOULD document the claim profiles it supports its configuration data. For the business-level and legal implications of different claim profiles, see [UMA-obligations].
A client, whether web-based or native, is operated by an end-user in one of two typical situations:
For convenience, this specification refers to the end-user as a "requesting end-user" to cover both cases, which differ only at the level of business agreements (and potentially law), rather than technology. The authorization server has a variety of options at this point for satisfying the resource owner's policy; this specification does not dictate a single answer. For example, the authorization server could require the requesting end-user to register for and/or log in to a local authorization server account, or fill in a questionnaire, or complete a purchase. It could even require several of these operations, where the order is treated as significant for evaluating resource owner policies. A variety of claim profiling can be defined to achieve these effects.
An end-user-driven client MUST redirect the requesting end-user to the authorization server in order to continue the process of seeking authorization, including a URI query parameter with the name "ticket" whose value conveys the permission ticket for which the need_claims error was received; for example, "ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de".
Each claim profile MUST provide the following capabilities:
This section defines the OpenID Connect claim profile for UMA. Following is a summary:
If an authorization server supports the OpenID Connect claim profile, it MUST supply the "openid" value for one of its "claim_profiles_supported" values in its configuration data.
To conform to this option, the authorization server MUST do the following:
The authorization server can then use any conforming OpenID Connect mechanisms and typical user interfaces for engaging with the UserInfo endpoints of OpenID Providers and Claims Providers, potentially allowing for the delivery of "trusted claims" (such as a verified email address or a date or birth) on which authorization policy for access may depend.
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. [OAuth2] 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 [OAuth2] Section 7.2.
If the request failed authentication, the authorization server or the resource server responds with an OAuth error message as described throughout Section 2 and 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 ... { "status": "error", "error": "invalid_request", "error_description": "There is already a resource with this identifier.", "error_uri": "http://as.example.com/errors/resource_exists" }
This specification defines a protocol that has optional features. For 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 profiles, and third parties may likewise want to define their own. Different RPT profile could be used, for example, to change the dividing line between authorization server and resource server responsibilities in controlling access. Different claim profiles could be used to customize sector-specific or population-specific (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, the following sections provide guidelines for third parties that wish to specify UMA-related profiles.
It is RECOMMENDED that profiles of UMA document the following information:
It is RECOMMENDED that RPT profiles document the following information:
See Section 3.3.2 for an example.
It is RECOMMENDED that claim profiles document the following information:
See Section 3.5.1.1 for an example.
This specification relies mainly on OAuth security mechanisms as well as transport-level encryption for protecting the protection and authorization API endpoints. Most PATs and AATs are likely to use OAuth bearer tokens. See [OAuth-threat] for more information.
This specification defines a number of JSON-based data formats. 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.
The issue of impersonation is a crucial aspect in UMA, particularly when entities are wielding bearer tokens that preclude proof-of-possession (of a secret or a cryptographic key). As such, one way to mitigate this risk is for the resource owner to require stronger claims to accompany any access request. For example, consider the case where Alice sets policies at the authorization server governing access to her resources by Bob. When Bob first seeks access and must obtain an RPT (for which the default RPT profile specifies a bearer token), Alice could set policies demanding that Bob prove his identity by providing a set of strong claims issued by a trusted attrribute provider in order to get authorization data associated with that token.
Another issue concerns the use of the [OAuth2] implicit flow. In this case, Bob will have exposure to the token, and may maliciously pass the token to an unauthorized party. To mitigate this weakness and others, we recommend considering the following steps:
For information about the additional technical, operational, and legal elements of trust establishment between UMA entities and parties, which affects security considerations, see [UMA-obligations].
The authorization server comes to be in possession of resource set information (such as names and icons) 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. This specification depends on [OAuth-resource-reg], which recommends obscuring resource set identifiers in order to avoid leaking personally identifiable information to clients through the scope mechanism.
(More privacy considerations information to come.)
For information about the technical, operational, and legal elements of trust establishment between UMA entities and parties, which affects privacy considerations, see [UMA-obligations].
This section outlines conformance requirements for various entities implementing UMA endpoints.
This specification has dependencies on other specifications, as referenced under the normative references listed in this specification. Its dependencies on some specifications, such as OpenID Connect ([OCStandard] and [OCMessages]), are optional depending on whether the feature in question is used in the implementation.
The authorization server's configuration data provides a machine-readable method for it to indicate certain of the conformance options it has chosen or supports. Several of the configuration data properties allow for indicating extension features. Where this specification does not already require optional features to be documented, it is RECOMMENDED that authorization server developers and deployers document any profiled or extended features explicitly and use configuration data to indicate their usage. See Section 1.4 for information about providing and extending the configuration data.
This document makes no request of IANA.
The current editor of this specification is Thomas Hardjono of MIT. The following people are co-authors:
Additional contributors to this specification include the Kantara UMA Work Group participants, a list of whom can be found at [UMAnitarians].
All issues are now captured at the project's GitHub site (https://github.com/xmlgrrl/UMA-Specifications/issues).
[OAuth-linktypes] | Mills, W., "Link Type Registrations for OAuth 2", February 2013. |
[OAuth-meta] | Sakimura, N., "JSON Metadata for OAuth Responses", February 2013. |
[UMA-casestudies] | Maler, E., "UMA Case Studies", March 2013. |
[UMA-usecases] | Maler, E., "UMA Scenarios and Use Cases", October 2010. |
[UMAnitarians] | Maler, E., "UMA Participant Roster", April 2013. |
NOTE: To be removed by RFC editor before publication as an RFC.
See http://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol for a list of code-breaking and other major changes made to this specification at various revision points.