|Editor:||Eve Maler, ForgeRock|
|Authors:||Maciej Machulak, HSBC|
|Justin Richer, Bespoke Engineering|
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 authorizes access.
This technical specification is a Draft Recommendation produced by the User-Managed Access Work Group. The Work Group has disposed of all comments collected during this specification's Public Comment period. 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. The grant enhances OAuth capabilities in the following ways:
For example, bank customer (resource owner) Alice with a bank account service (resource server) can use a sharing management service (authorization server) hosted by the bank to manage access to her various protected resources by spouse Bob, accounting professional Charline, and and financial information aggregation company Decide Account, all using different client applications. Each of her bank accounts is a protected resource, and two different scopes of access she can control on them are viewing account data and accessing payment functions.
An OPTIONAL second specification, [UMAFedAuthz], defines a means for an UMA-enabled authorization server and resource server to be loosely coupled, or federated, in a resource owner context. This specification, together with [UMAFedAuthz], constitutes UMA 2.0.
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 parameter names and values are case sensitive. JSON [RFC7159] data structures defined in this specification MAY contain extension parameters that are not defined in this specification. Any entity receiving or retrieving a JSON data structure SHOULD ignore extension parameters 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.
The UMA grant enhances the abstract protocol flow of OAuth.
Figure 1 shows an example flow illustrating a variety of messaging paths and artifacts. The resource owner entity and its communications with the authorization server are included for completeness, although policy condition setting is outside the scope of this specification and communications among the other four entities are asynchrjonous with respect to resource owner actions. Further, although both claims pushing and interactive claims gathering are shown, both might not typically be used in one scenario.
requesting authorization resource resource party client server server owner | | | | | | | |Set policy| | | | |conditions (anytime)| | | |<- - - - - - - - - -| | |Resource request (no access token) | | | |------------------------------------->| | | |401 response with initial permission | | | |ticket, authz server location | | | |<-------------------------------------| | | |Access token (RPT) request | | | | |with permission ticket, | | | | |claim token (push claims) | | | | |-------------------------->| | | | | +----|Authz | | | | +--->|assessment| | | |403 response with new | | | | |permission ticket, | | | | |need_info error, | | | | |redirect_user hint | | | | |<--------------------------| | | |Redirect | | | | |user with | | | | |permission | | | | |ticket | | | | |<-----------| | | | |Follow redirect to authz server | | | |--------------------------------------->| | | |Interactive claims gathering | | | |<- - - - - - - - - - - - - - - - - - - >| | | |Redirect back with new permission | | | |ticket | | | |<---------------------------------------| | | |Follow | | | | |redirect | | | | |to client | | | | |----------->| | | | | |RPT request with permission| | | | |ticket | | | | |-------------------------->| | | | | +----|Authz | | | | +--->|assessment| | | |Response with RPT and PCT | | | | |<--------------------------| | | | |Resource request with RPT | | | | |------------------------------------->| | | |Protected resource | | | | |<-------------------------------------| |
Figure 1: Example Flow
Following are key concepts relevant to this specification, as illustrated in the figure:
Note: How the client acquired knowledge of the resource server's interface and the specific endpoint of the desired protected resource is outside the scope of this specification. For example, the resource server might have a programmatic API or it might serve up simple web pages, and the resource owner might have advertised the endpoint publicly on a blog or other website, listed it in a discovery service, or emailed a link to a particular intended requesting party.
The authorization server supplies metadata in a discovery document to declare its endpoints. The client uses this discovery document to discover these endpoints for use in the flows defined in Section 3.
The authorization server MUST make a discovery document available. The structure of the discovery document MUST conform to that defined in [OAuthMeta]. The discovery document MUST be available at an endpoint formed by concatenating the string /.well-known/uma2-configuration to the issuer metadata value defined in [OAuthMeta], using the well-known URI syntax and semantics defined in [RFC5785]. In addition to the metadata defined in [OAuthMeta], this specification defines the following metadata for inclusion in the discovery document:
If the authorization server supports dynamic client registration, it MUST allow client applications to register claims_redirect_uri metadata, as defined in Section 3.3.2, using the following metadata field:
The client requests a protected resource without providing any access token.
Note: This process does not assume that any relevant policy conditions have already been defined at the authorization server.
For an example of how the resource server can put resources under the protection of an authorization server, see [UMAFedAuthz].
Example of a client request at a protected resource without providing an access token:
GET /users/alice/album/photo.jpg HTTP/1.1 Host: photoz.example.com ...
The resource server responds to the client's tokenless resource request.
The resource server MUST obtain a permission ticket from the authorization server to provide in its response, but the means of doing so is outside the scope of this specification. For an example of how the resource server can obtain the permission ticket, see [UMAFedAuthz].
The process of choosing what permissions to request from the authorization server may require interpretation and mapping of the client's resource request. The resource server SHOULD request a set of permissions with scopes that is reasonable for the client's resource request.
Note: In order for the resource server to know which authorization server to approach for the permission ticket and on which resource owner's behalf, it needs to derive the necessary information using cues provided by the structure of the API where the resource request was made, rather than by an access token. Commonly, this information can be passed through the URI, headers, or body of the client's request. Alternatively, the entire interface could be dedicated to the use of a single resource owner and protected by a single authorization server.
See Section 5.5 for permission ticket security considerations.
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 discovery document in an as_uri parameter and the permission ticket in a ticket parameter.
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".
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 requests the resource, now in possession of an RPT. The client uses [RFC6750] for a bearer token, and any other suitable presentation mechanism for an RPT of another access token type.
Example of a client request for the 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 RPT-accompanied resource request.
If the resource request fails, the resource server responds as if the request were unaccompanied by an access token, as defined in Section 3.2.
The resource server MUST NOT give access in the case of an invalid RPT or an RPT associated with insufficient authorization.
For an example of how the resource server can introspect the RPT and its permissions at the authorization server prior to responding to the client's request, see [UMAFedAuthz].
As noted in Section 3.3.5, when issuing an RPT, the authorization server MAY also issue a refresh token.
Having previously received a refresh token from the authorization server, the client MAY use the refresh token grant as defined in [RFC6749] to attempt to refresh an expired RPT. If the client includes the scope parameter in its request, the authorization server MAY limit the scopes in the permissions associated with any resulting refreshed RPT to the scopes requested by the client.
The authorization server MUST NOT perform an authorization assessment calculation on receiving the client's request to refresh an RPT.
If the authorization server presents a token revocation endpoint as defined in [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:
An UMA profile restricts UMA's available options. An UMA extension defines how to use UMA's extensibility points. The two can be combined. Some reasons for creating profiles and extensions include:
The following actions are RECOMMENDED regarding the creation and use of profiles and extensions:
This specification relies mainly on OAuth 2.0 security mechanisms as well as transport-level security. 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.
Redirection used for gathering claims interactively from an end-user requesting party (described in Section 3.3.2) creates the potential for cross-site request forgery (CSRF). This may be the result of 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.
A CSRF attack against the authorization server's claims interaction endpoint can result in an attacker obtaining authorization for access through a malicious client without involving or alerting the end-user requesting party. The authorization server MUST implement CSRF protection for its claims interaction endpoint and ensure that a malicious client cannot obtain authorization without the awareness and involvement of the requesting party.
If the client uses the interactive claims gathering feature, it MUST implement CSRF protection for its claims redirection URI. It SHOULD use the state parameter when redirecting the requesting party to the claims interaction endpoint. The value of the state parameter MUST be unguessable by an attacker. Once the authorization server redirects the requesting party back, with the required binding value contained in the state parameter, the client MUST check that the value of the state parameter received is equal to the value sent in the initial redirection request. Depending on the type of application, a client has several methods for storing and later verifying the value of the state parameter in between the initial redirect and the eventual resulting request to the claims redirection URI, including storage in a server-side session-bound variable, cryptographic derivation from a browser cookie, or secure application-level storage. The client MUST treat requests containing an invalid or unknown state parameter value as an error.
The state parameter SHOULD NOT include sensitive client or requesting party information in plain text, as it is transmitted through third-party components (the requesting party's user agent) and could be stored insecurely.
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. Thus, a malicious client has the opportunity to switch end-users -- say, enabling malicious end-user Carlos to impersonate legitimate 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.
To mitigate this threat, the authorization server, with the support of the resource owner, should consider the following strategies in combination.
The client MUST only share the RPT (access token) with the resource server and authorization server, as explained in Section 10.3 of [RFC6749], and thus MUST keep it confidential from the requesting party. Because a malicious requesting party (the user of the client in the UMA grant) may have incentives to steal an RPT that the resource owner (the user of the client in other OAuth grants) does not, this security consideration takes on especial importance.
The PCT is similar to a refresh token in that it allows non-interactive issuance of access tokens. The authorization server and client MUST keep the PCT confidential in transit and storage, and MUST NOT share the PCT with any entity other than each other. The authorization server MUST maintain the binding between the PCT and the client to which it was issued.
Given that the 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.
If the authorization server has reason to believe that a PCT is compromised, for example, if the PCT has been supplied by a client that has "impossible geography" parameters, the authorization server should consider not using the claims based on that PCT in its authorization assessment.
After the client's resource request with an RPT, assuming the client sent an RPT of the bearer style such as defined in [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 specification's publication. 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, for example, submit the token identifier to the token introspection endpoint to obtain the necessary key information. The details of this usage are outside the scope of this specification.
Permission tickets and PCTs are additional credentials that the authorization server MUST prevent attackers from guessing, as defined in Section 10.10 of [RFC6749].
Within the constraints of making permission ticket values unguessable, the authorization server MAY format the permission ticket however it chooses, for example, either as a random string that references data held on the server or by including data within the ticket itself.
Permission tickets MUST be single-use. This prevents susceptibility to a session fixation attack.
The authorization server MUST invalidate a permission ticket when the client presents the permission ticket to either the token endpoint or the claims interaction endpoint, or when the permission ticket expires, whichever occurs first.
The client SHOULD check that the value of the ticket parameter it receives back from the authorization server in each response and each redirect of the requesting party back to it differs from the one it sent to the server in the initial request or redirect.
If the authorization server has reason to believe that a permission ticket is compromised, for example, because it has seen the permission ticket before and it believes the first appearance was from a legitimate client and the second appearance is from an attacker, it should consider invalidating any access tokens based on this evidence.
Given that scenarios involving the request_submitted error code are likely to involve polling intervals, the permission ticket needs to last long enough to give the client a chance to attempt a polling request, which then needs to figure into other permission ticket security considerations.
While a reasonable approach for most scenarios is to implement the classic stance of default-deny ("everything that is not expressly allowed is forbidden"), corner cases can inadvertently result in default-permit behavior. For example, it is insufficient to create default "empty" policy conditions stating "no claims are needed", and then accept an empty set of supplied claims as sufficient for access during authorization assessment.
When a client makes an RPT request, it has the opportunity to push a claim token to attempt to satisfy policy conditions (see Section 3.3.1).
Claim tokens of any format typically contain audience restrictions, and an authorization server would not typically 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.
Some deployments could have exceptional circumstances allowing the authorization server to validate claim tokens. For example, if the authorization server itself is also the identity provider for the requesting party, then it would be able to validate any ID token that the client pushes as a claim token and also validate the client to which it was issued.
Parties that are operating and using UMA software entities may need 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. Written profiles are a key mechanism for conveying and enforcing these agreements. Section 4 discusses profiling. See [UMA-legal] to learn about frameworks and tools to assist in the legal and contractual elements of deploying UMA-enabled services.
UMA has the following privacy considerations.
The setting of policy conditions, the resource owner-authorization server interface, and the resource owner-resource server interface are outside the scope of this specification. (For an example of how a secure and authorized resource owner context can be established between the resource server and authorization server, see [UMAFedAuthz].)
A variety of flows and user interfaces for policy condition setting involving user agents for both of these servers are possible, each with different privacy consequences for end-user resource owners. As well, various authorization, security, and time-to-live strategies could be applied on a per-resource owner basis or a per-authorization server basis, as the entities see fit. Validity periods of RPTs, refresh tokens, permissions, caching periods for responses, and even OAuth client credentials are all subject to management. Different time-to-live strategies might be suitable for different resources and scopes.
In order to account for modifications of policy conditions that result in the withdrawal of authorization grants (for example, fewer scopes, fewer resources, or resources available for a shorter time) in as timely a fashion as possible, the authorization server should align its strategies for management of these factors with resource owner needs and actions rather than those of clients and requesting parties. For example, the authorization server may want to invalidate a client's RPT and refresh token as soon as a resource owner changes policy conditions in such a way as to deny the client and its requesting party future access to a full set of previously held permissions.
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 claims 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 may need 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.8 for more information. Additional considerations related to Privacy by Design concepts are discussed in [UMA-PbD].
This document makes the following requests of IANA.
The following people made significant text contributions to the specification:
Additional contributors to this specification include the Kantara UMA Work Group participants, a list of whom can be found at [UMAnitarians].
|[BCP195]||Sheffer, Y., “Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)”, May 2015, <https://tools.ietf.org/html/bcp195>.|
|[OIDCCore]||Sakimura, N., “OpenID Connect Core 1.0 incorporating errata set 1”, November 2014, <http://openid.net/specs/openid-connect-core-1_0.html>.|
|[OIDCDynClientReg]||Sakimura, N., “OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1”, November 2014, <http://openid.net/specs/openid-connect-registration-1_0.html>.|
|[UMAFedAuthz]||Maler, E., “Federated Authorization for User-Managed Access (UMA) 2.0”, September 2017, <https://docs.kantarainitiative.org/uma/wg/oauth-uma-federated-authz-2.0-08.html>.|
|[OAuthMeta]||Jones, M., “OAuth 2.0 Authorization Server Metadata”, March 2017, <https://tools.ietf.org/html/draft-ietf-oauth-discovery-06>.|
|[RFC2119]||Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.|
|[RFC3986]||Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax”, STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>.|
|[RFC5785]||Nottingham, M. and E. Hammer-Lahav, “Defining Well-Known Uniform Resource Identifiers (URIs)”, RFC 5785, DOI 10.17487/RFC5785, April 2010, <https://www.rfc-editor.org/info/rfc5785>.|
|[RFC6749]||Hardt, D., Ed., “The OAuth 2.0 Authorization Framework”, RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.|
|[RFC6750]||Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage”, RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/info/rfc6750>.|
|[RFC6819]||Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations”, RFC 6819, DOI 10.17487/RFC6819, January 2013, <https://www.rfc-editor.org/info/rfc6819>.|
|[RFC7591]||Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, “OAuth 2.0 Dynamic Client Registration Protocol”, RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/info/rfc7591>.|
|[RFC7009]||Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, “OAuth 2.0 Token Revocation”, RFC 7009, DOI 10.17487/RFC7009, August 2013, <https://www.rfc-editor.org/info/rfc7009>.|
|[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>.|