Version: | 2.0 |
Date: | 2017-4-19 |
Editor: | Eve Maler, ForgeRock |
This specification defines a means for a client, representing a requesting party, to use a permission ticket to request an OAuth 2.0 access token to gain access to a protected resource asynchronously from the time a resource owner grants access.
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 © 2017 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).
This specification defines an extension OAuth 2.0 [RFC6749] grant to enable the following two aims of User-Managed Access (UMA) 2.0:
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) hosted by the bank to manage access by a spouse Bob, an accounting professional Charline, a tax professional David, and an account aggregation company ExplanAccount (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.
A third aim of UMA outside the scope of this specification involves loosely coupling the interactions of the authorization server and resource server to let the resource owner monitor and control access grant rules at a central service location over time and at a fine grain.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "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.
The UMA grant enhances the OAuth definitions of entities in order to accommodate the requesting party role.
Figure 1 shows a sample high-level flow.
resource resource authorization client requesting owner server server | party | | Attempt resource access w/no token 1| | | |<----------------------------------------| | | |2 Return AS location, permission ticket | | | |---------------------------------------->| | | | Request RPT, send permission 3| | | | | ticket, push claims| | | | |<---------------------| | | | Authorization 4|-------+ | | | | assessment|<------+ | | | | |5 Return need_info w/ | | | | |redirect_user, permission ticket | | |--------------------->| | | | | |6 | | | | Redirect...| | | for interactive claims gathering...| | | | | and redirect back| | | | |<---------------------|------->| | | | Request RPT, send 7| | | | | permission ticket| | | | |<---------------------| | | | Authorization 4|-------+ | | | | assessment|<------+ | | | | |8 Issue RPT w/PCT (opt) | | | |--------------------->| | | | Attempt resource access w/RPT 9| | | |<----------------------------------------| | | |10 Protected resource | | | |---------------------------------------->| |
Figure 1: Protocol Flow Summary
Following are concepts introduced in the figure:
Note: The following aspects of the resource server-client relationship are outside the scope of this specification:
The UMA grant uses the OAuth endpoints in some special ways and defines some new endpoints:
Different choices of phase order, claim collection style, and use of the error_details hints inside need_info might be best suited for different deployment ecosystems. For example, where no pre-established relationship is expected between the resource owner's authorization server and the requesting party, initial requesting party redirection and a redirect_user hint may be a useful pattern, at which point the authorization server might either authenticate the requesting party locally or serve as a relying party for a remote identity provider. Where a common authorization server also functions as an identity provider for all resource owners and requesting parties, having the client push claim tokens sourced from that central server itself with a pre-negotiated format and contents may be an alternate useful pattern.
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, ideally by supplying the URI identifying each UMA profile and extension in its uma_profiles_supported configuration property, and by using extension configuration properties to indicate specific usage details as necessary.
The authorization server has configuration properties as follows.
The authorization server MUST make its configuration properties available in a JSON document at a discovery endpoint formed by concatenating the string /.well-known/uma2-configuration to the issuer configuration property value as defined in Section 2.1. The syntax and semantics of /.well-known are defined in [RFC5785] 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 2.1.
Example of a configuration document returned in response to a query (note the use of https: for endpoints throughout):
HTTP/1.1 200 OK Content-Type: application/json ... { "issuer":"https://example.com", "registration_endpoint":"https://as.example.com/dyn_client_reg", "claims_interaction_endpoint":"https://as.example.com/claims", }
Example of a configuration document response containing the uma_profiles_supported configuration property indicating that the authorization server supports an UMA profile related to the OpenID Connect-based claim token format:
HTTP/1.1 200 OK Content-Type: application/json ... { "issuer":"https://example.com", "uma_profiles_supported":"http://openid.net/specs/openid-connect-core-1_0.html#IDToken", "registration_endpoint":"https://as.example.com/dyn_client_reg", "claims_interaction_endpoint":"https://as.example.com/claims", }
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.
The client attempts access to a resource that the resource server considers protected, without having presented a token for authorized access.
Note: This process does not assume that any policy conditions have already been defined at the authorization server. A variety of combinations of access attempt flows and resource owner policy condition-setting interfaces are possible.
Example of a client request at a protected resource carrying no token:
GET /users/alice/album/photo.jpg HTTP/1.1 Host: photoz.example.com ...
The resource server responds to the client's tokenless access attempt on a protected resource.
If the resource server is able to provide a permission ticket from the authorization server, it responds to the client by providing a WWW-Authenticate header with the authentication scheme UMA, with the issuer URI from the authorization server's configuration document in an as_uri parameter and the permission ticket in a ticket parameter.
For example:
HTTP/1.1 401 Unauthorized WWW-Authenticate: UMA realm="example", as_uri="https://as.example.com", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" ...
If the resource server is unable to provide a permission ticket from the authorization server, then it includes a header of the following form in its response to the client: Warning: 199 - "UMA Authorization Server Unreachable".
For example:
HTTP/1.1 403 Forbidden Warning: 199 - "UMA Authorization Server Unreachable" ...
Without an authorization server location and permission ticket, the client is unable to continue.
The client attempts to access the protected resource, now in possession of an RPT.
Example of a client request at a protected resource carrying an RPT:
GET /users/alice/album/photo.jpg HTTP/1.1 Authorization: Bearer sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv Host: photoz.example.com ...
The resource server responds to the client's access attempt on a protected resource that bore an RPT.
This process concludes the flow.
As noted in Section 3.3.5, when issuing an RPT, the authorization server MAY also issue a refresh token.
In a typical access token refreshing flow, providing the scope parameter in the request has a token downscoping effect. However, if the client includes the scope parameter when providing a refresh token that is associated with an RPT, the effect is undefined.
If the authorization server presents a token revocation endpoint as defined by [RFC7009], the client MAY use the endpoint to request revocation of an RPT (access token), refresh token, or PCT previously issued to it on behalf of a requesting party. This specification defines the following token type hint value:
For implementation interoperability and to serve particular deployment scenarios, third parties may want to define profiles of UMA that restrict its available options. Further, third parties may want to define profiles of companion technologies to fit interoperably within the UMA framework, for example, claim token formats suitable for claim pushing (see Section 3.3.1) or protocol alternatives to HTTP. Finally, it is possible to use the natural extensibility within this specification's messaging formats to enable third parties to define extensions that serve adjacent use cases.
This section provides guidelines for third parties wishing to specify UMA-related profiles and extensions. It is RECOMMENDED for authorization server deployers to document any profiled or extended features explicitly (see Section 2 for details).
In all cases, it is RECOMMENDED for profiles and extensions to document the following information:
This specification relies mainly on OAuth 2.0 security mechanisms as well as transport-level encryption. Thus, implementers are strongly advised to read [BCP195] and 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, implementers should take into account the security considerations in all other normatively referenced specifications.
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 6.1.
Like ordinary OAuth redirection, UMA redirection for the purpose of gathering claims from an end-user requesting party (described in Section 3.3.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 [RFC6819] are apropos for the UMA claims-gathering redirection flow as well.
When a client redirects an end-user requesting party to the claims interaction endpoint, the client provides no a priori context to the authorization server about which user is appearing at the endpoint, other than implicitly through the permission ticket. Since the authorization server is free to gather any claims it wishes, the effect is to "late-bind" them to the permission ticket and the state string provided by the client, with the effect of enabling the authorization server not to trust client-asserted claims. This is a desirable result and reflects one reason why the authorization server might choose to demand use of the redirect flow over the push flow. However, the client has the opportunity to switch end-users -- say, enabling malicious end-user Carlos to impersonate the original end-user Bob, who might be represented by a PCT already in that client's possession and might even have authorized the issuance of that PCT -- after the redirect completes and before it returns to the token endpoint to seek permissions.
Another issue concerns the exposure of an RPT to a requesting party, which could maliciously pass the token to an unauthorized party.
To mitigate requesting-party switching and RPT exposure threats, consider the following strategies.
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.
After the client's access attempt on a protected resource, assuming the client sent an RPT of the bearer style such as those defined by [RFC6750], the resource server will have received from the client the entire secret portion of the token. This specification assumes only bearer-type tokens because they are the only type standardized as of this writing. However, to strengthen protection for RPTs using a proof-of-possession approach, the resource server could receive an RPT that consists of only a cryptographically signed token identifier, and then to validate the signature, it could submit the token identifier to the token introspection endpoint to obtain the necessary key information. The details of this usage are out of scope of this specification.
The authorization server MUST prevent attackers from guessing permission tickets and PCTs.
Parties that are 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 4 discusses profiling. See [UMA-legal] to learn about tools to assist in the legal and contractual elements of deploying UMA-enabled services.
This section discusses the threats surrounding client claim pushing (see Section 3.3.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 profile, as described in Section 4. Authorization servers are RECOMMENDED not to accept claim tokens pushed by untrusted clients and not to ignore audience restrictions found in claim tokens pushed by clients.
In the special circumstance when an authorization server is colocated with an OpenID Provider for the requesting parties within a deployment ecosystem, then it is able to act as an OpenID Relying Party for itself. This circumstance presents an opportunity for a technical optimization of the requirement for trust because the authorization server itself issued the OAuth client credentials for the client in question, and could reasonably be the singular aud value target in an OpenID Connect ID Token pushed by the client to the token endpoint.
UMA has the following privacy considerations.
The primary privacy duty of UMA's design is to the resource owner. However, privacy considerations affect the requesting party as well, having to do with the nature of claims. Claims are likely to contain personal, personally identifiable, and sensitive information, particularly in the case of requesting parties who are end-users.
If the authorization server supports persisting claims for any length of time (for example, to support issuance of PCTs), then it SHOULD provide a secure and privacy-protected means of storing claim data. It is also RECOMMENDED for the authorization server to use an interactive claims-gathering flow to ask an end-user requesting party for authorization to persist their claims before issuing a PCT. A requesting party who provides claims to an authorization server once having been redirected there is less susceptible to privacy-destroying behavior. Otherwise, certain flows such as claim pushing and interactive federated sign-in with automatic login will tend to be invisible to the user if they have not consciously authorized the possibility.
Since the client's initial request for a protected resource is made in an unauthorized and unauthenticated context, such requests are by definition open to all users. The response to that request includes the authorization server's location to enable the client to request an access token and present claims. If it is known out of band that authorization server is owned and controlled by a single user, or visiting the authorization server contains other identifying information, then an unauthenticated and unauthorized client would be able to tell which resource owner is associated with a given resource. Other information about the resource owner, such as organizational affiliation or group membership, may be gained from this transaction as well.
Parties that are 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 5.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 well-known URI defined in Section 2.1, as required by Section 5.1 of [RFC5785].
This specification registers the parameters defined in Section 3.3.1, as required by Section 11.2 of [RFC6749].
This specification registers the errors defined in Section 3.3.6, as required by Section 11.4 of [RFC6749].
This specification registers the errors defined in Section 3.7, as required by Section 4.1.2 of [RFC7009].
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-Impl] | Maler, E., “UMA Implementer's Guide”, 2017, <https://kantarainitiative.org/confluence/display/uma/UMA+Implementer%27s+Guide>. |
[UMA-PbD] | Maler, E., “Privacy by Design Implications of UMA”, 2013, <https://kantarainitiative.org/confluence/display/uma/Privacy+by+Design+Implications+of+UMA>. |
[UMAnitarians] | Maler, E., “UMA Participant Roster”, 2017, <https://kantarainitiative.org/confluence/display/uma/Participant+Roster>. |
[UMA-legal] | Maler, E., “UMA Legal”, 2017, <http://kantarainitiative.org/confluence/display/uma/UMA+Legal>. |
Eve Maler
(editor)
ForgeRock
EMail: eve.maler@forgerock.com