diff options
Diffstat (limited to 'doc/rfc/rfc8707.txt')
| -rw-r--r-- | doc/rfc/rfc8707.txt | 547 |
1 files changed, 547 insertions, 0 deletions
diff --git a/doc/rfc/rfc8707.txt b/doc/rfc/rfc8707.txt new file mode 100644 index 0000000..bfce71c --- /dev/null +++ b/doc/rfc/rfc8707.txt @@ -0,0 +1,547 @@ + + + + +Internet Engineering Task Force (IETF) B. Campbell +Request for Comments: 8707 Ping Identity +Category: Standards Track J. Bradley +ISSN: 2070-1721 Yubico + H. Tschofenig + Arm Limited + February 2020 + + + Resource Indicators for OAuth 2.0 + +Abstract + + This document specifies an extension to the OAuth 2.0 Authorization + Framework defining request parameters that enable a client to + explicitly signal to an authorization server about the identity of + the protected resource(s) to which it is requesting access. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8707. + +Copyright Notice + + Copyright (c) 2020 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 + (https://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. + +Table of Contents + + 1. Introduction + 1.1. Requirements Notation and Conventions + 1.2. Terminology + 2. Resource Parameter + 2.1. Authorization Request + 2.2. Access Token Request + 3. Security Considerations + 4. Privacy Considerations + 5. IANA Considerations + 5.1. OAuth Parameters Registration + 5.2. OAuth Extensions Error Registration + 6. References + 6.1. Normative References + 6.2. Informative References + Acknowledgements + Authors' Addresses + +1. Introduction + + Several years of deployment and implementation experience with the + OAuth 2.0 Authorization Framework [RFC6749] has uncovered a need (in + some circumstances, such as an authorization server servicing a + significant number of diverse resources) for the client to explicitly + signal to the authorization server where it intends to use the access + token it is requesting. + + Knowing the protected resource (a.k.a. resource server, application, + API, etc.) that will process the access token enables the + authorization server to construct the token as necessary for that + entity. Properly encrypting the token (or content within the token) + to a particular resource, for example, requires knowing which + resource will receive and decrypt the token. Furthermore, various + resources oftentimes have different requirements with respect to the + data contained in (or referenced by) the token, and knowing the + resource where the client intends to use the token allows the + authorization server to mint the token accordingly. + + Specific knowledge of the intended recipient(s) of the access token + also helps facilitate improved security characteristics of the token + itself. Bearer tokens, currently the most commonly utilized type of + OAuth access token, allow any party in possession of a token to get + access to the associated resources. To prevent misuse, several + important security assumptions must hold, one of which is that an + access token must only be valid for use at a specific protected + resource and for a specific scope of access. Section 5.2 of + [RFC6750], for example, prescribes including the token's intended + recipients within the token to prevent token redirect. When the + authorization server is informed of the resource that will process + the access token, it can restrict the intended audience of that token + to the given resource such that the token cannot be used successfully + at other resources. + + OAuth scope, from Section 3.3 of [RFC6749], is sometimes overloaded + to convey the location or identity of the protected resource, + however, doing so isn't always feasible or desirable. Scope is + typically about what access is being requested rather than where that + access will be redeemed (e.g., "email", "admin:org", "user_photos", + "channels:read", and "channels:write" are a small sample of scope + values in use in the wild that convey only the type of access and not + the location or identity). + + In some circumstances and for some deployments, a means for the + client to signal to the authorization server where it intends to use + the access token it's requesting is important and useful. A number + of implementations and deployments of OAuth 2.0 have already employed + proprietary parameters toward that end. Going forward, this + specification aspires to provide a standardized and interoperable + alternative to the proprietary approaches. + +1.1. Requirements Notation and Conventions + + 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 + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +1.2. Terminology + + This specification uses the terms "access token", "refresh token", + "authorization server", "resource server", "authorization endpoint", + "authorization request", "authorization response", "token endpoint", + "grant type", "access token request", "access token response", and + "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. + +2. Resource Parameter + + In requests to the authorization server, a client MAY indicate the + protected resource (a.k.a. resource server, application, API, etc.) + to which it is requesting access by including the following parameter + in the request. + + resource + Indicates the target service or resource to which access is being + requested. Its value MUST be an absolute URI, as specified by + Section 4.3 of [RFC3986]. The URI MUST NOT include a fragment + component. It SHOULD NOT include a query component, but it is + recognized that there are cases that make a query component a + useful and necessary part of the resource parameter, such as when + one or more query parameters are used to scope requests to an + application. The "resource" parameter URI value is an identifier + representing the identity of the resource, which MAY be a locator + that corresponds to a network-addressable location where the + target resource is hosted. Multiple "resource" parameters MAY be + used to indicate that the requested token is intended to be used + at multiple resources. + + The parameter value identifies a resource to which the client is + requesting access. The parameter can carry the location of a + protected resource, typically as an https URL or a more abstract + identifier. This enables the authorization server to apply policy as + appropriate for the resource, such as determining the type and + content of tokens to be issued, if and how tokens are encrypted, and + applying appropriate audience restrictions. + + The client SHOULD provide the most specific URI that it can for the + complete API or set of resources it intends to access. In practice, + a client will know a base URI for the application or resource that it + interacts with, which is appropriate to use as the value of the + "resource" parameter. The client SHOULD use the base URI of the API + as the "resource" parameter value unless specific knowledge of the + resource dictates otherwise. For example, the value + "https://api.example.com/" would be used for a resource that is the + exclusive application on that host; however, if the resource is one + of many applications on that host, something like + "https://api.example.com/app/" would be used as a more specific + value. Another example is when an API has multiple endpoints, e.g., + when System for Cross-domain Identity Management (SCIM) [RFC7644] has + endpoints such as "https://apps.example.com/scim/Users", + "https://apps.example.com/scim/Groups", and + "https://apps.example.com/scim/Schemas". The client would use + "https://apps.example.com/scim/" as the resource so that the issued + access token is valid for all the endpoints of the SCIM API. + + The following error code is provided for an authorization server to + indicate problems with the requested resource(s) in response to an + authorization request or access token request. It can also be used + to inform the client that it has requested an invalid combination of + resource and scope. + + invalid_target + The requested resource is invalid, missing, unknown, or malformed. + + The authorization server SHOULD audience-restrict issued access + tokens to the resource(s) indicated by the "resource" parameter. + Audience restrictions can be communicated in JSON Web Tokens + [RFC7519] with the "aud" claim and the top-level member of the same + name provides the audience restriction information in a Token + Introspection [RFC7662] response. The authorization server may use + the exact "resource" value as the audience or it may map from that + value to a more general URI or abstract identifier for the given + resource. + +2.1. Authorization Request + + When the "resource" parameter is used in an authorization request to + the authorization endpoint, it indicates the identity of the + protected resource(s) to which access is being requested. When an + access token will be returned directly from the authorization + endpoint via the implicit flow (Section 4.2 of OAuth 2.0 [RFC6749]), + the requested resource is applicable to that access token. In the + code flow (Section 4.1 of OAuth 2.0 [RFC6749]) where an intermediate + representation of the authorization grant (the authorization code) is + returned from the authorization endpoint, the requested resource is + applicable to the full authorization grant. + + For an authorization request sent as a JSON Web Token (JWT), such as + when using the JWT Secured Authorization Request [JWT-SAR], a single + "resource" parameter value is represented as a JSON string while + multiple values are represented as an array of strings. + + If the client omits the "resource" parameter when requesting + authorization, the authorization server MAY process the request with + no specific resource or by using a predefined default resource value. + Alternatively, the authorization server MAY require clients to + specify the resource(s) they intend to access and MAY fail requests + that omit the parameter with an "invalid_target" error. The + authorization server might use this data to inform the user about the + resources the client is going to access on their behalf, to apply + policy (e.g., refuse the request due to unknown resources), and to + determine the set of resources that can be used in subsequent access + token requests. + + If the authorization server fails to parse the provided value(s) or + does not consider the resource(s) acceptable, it should reject the + request with an error response using the error code "invalid_target" + as the value of the "error" parameter and can provide additional + information regarding the reasons for the error using the + "error_description". + + An example of an authorization request where the client tells the + authorization server that it wants an access token for use at + "https://api.example.com/app/" is shown in Figure 1 below (extra line + breaks and indentation are for display purposes only). + + GET /as/authorization.oauth2?response_type=token + &client_id=example-client + &state=XzZaJlcwYew1u0QBrRv_Gw + &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb + &resource=https%3A%2F%2Fapi.example.com%2Fapp%2F HTTP/1.1 + Host: authorization-server.example.com + + Figure 1: Implicit Flow Authorization Request + + Below in Figure 2 is an example of an authorization request using the + "code" response type where the client is requesting access to the + resource owner's contacts and calendar data at + "https://cal.example.com/" and "https://contacts.example.com/" (extra + line breaks and indentation are for display purposes only). + + GET /as/authorization.oauth2?response_type=code + &client_id=s6BhdRkqt3 + &state=tNwzQ87pC6llebpmac_IDeeq-mCR2wLDYljHUZUAWuI + &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb + &scope=calendar%20contacts + &resource=https%3A%2F%2Fcal.example.com%2F + &resource=https%3A%2F%2Fcontacts.example.com%2F HTTP/1.1 + Host: authorization-server.example.com + + Figure 2: Code Flow Authorization Request + +2.2. Access Token Request + + When the "resource" parameter is used on an access token request made + to the token endpoint, for all grant types, it indicates the target + service or protected resource where the client intends to use the + requested access token. + + The resource value(s) that is acceptable to an authorization server + in fulfilling an access token request is at its sole discretion based + on local policy or configuration. In the case of a "refresh_token" + or "authorization_code" grant type request, such policy may limit the + acceptable resources to those that were originally granted by the + resource owner or a subset thereof. In the "authorization_code" case + where the requested resources are a subset of the set of resources + originally granted, the authorization server will issue an access + token based on that subset of requested resources, whereas any + refresh token that is returned is bound to the full original grant. + + When requesting a token, the client can indicate the desired target + service(s) where it intends to use that token by way of the + "resource" parameter and can indicate the desired scope of the + requested token using the "scope" parameter. The semantics of such a + request are that the client is asking for a token with the requested + scope that is usable at all the requested target services. + Effectively, the requested access rights of the token are the + cartesian product of all the scopes at all the target services. To + the extent possible, when issuing access tokens, the authorization + server should downscope the scope value associated with an access + token to the value the respective resource is able to process and + needs to know. (Here, "downscope" means give fewer permissions than + originally authorized by the resource owner.) This further improves + privacy as a list of scope values is an indication that the resource + owner uses the multiple various services listed; downscoping a token + to only that which is needed for a particular service can limit the + extent to which such information is revealed across different + services. As specified in Section 5.1 of [RFC6749], the + authorization server must indicate the access token's effective scope + to the client in the "scope" response parameter value when it differs + from the scope requested by the client. + + Following from the code flow authorization request shown in Figure 2, + the below examples show an "authorization_code" grant type access + token request (Figure 3) and response (Figure 4) where the client + tells the authorization server that it wants the access token for use + at "https://cal.example.com/" (extra line breaks and indentation are + for display purposes only). + + POST /as/token.oauth2 HTTP/1.1 + Host: authorization-server.example.com + Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ + Content-Type: application/x-www-form-urlencoded + + grant_type=authorization_code + &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb + &code=10esc29BWC2qZB0acc9v8zAv9ltc2pko105tQauZ + &resource=https%3A%2F%2Fcal.example.com%2F + + Figure 3: Access Token Request + + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-cache, no-store + + { + "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6Ijc3In0.eyJpc3MiOi + JodHRwOi8vYXV0aG9yaXphdGlvbi1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWI + iOiJfX2JfYyIsImV4cCI6MTU4ODQyMDgwMCwic2NvcGUiOiJjYWxlbmRhciIs + ImF1ZCI6Imh0dHBzOi8vY2FsLmV4YW1wbGUuY29tLyJ9.nNWJ2dXSxaDRdMUK + lzs-cYIj8MDoM6Gy7pf_sKrLGsAFf1C2bDhB60DQfW1DZL5npdko1_Mmk5sUf + zkiQNVpYw", + "token_type":"Bearer", + "expires_in":3600, + "refresh_token":"4LTC8lb0acc6Oy4esc1Nk9BWC0imAwH7kic16BDC2", + "scope":"calendar" + } + + Figure 4: Access Token Response + + A subsequent access token request, using the refresh token, where the + client tells the authorization server that it wants an access token + for use at "https://contacts.example.com/" is shown in Figure 5 below + with the response shown in Figure 6 (extra line breaks and + indentation are for display purposes only). + + POST /as/token.oauth2 HTTP/1.1 + Host: authorization-server.example.com + Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ + Content-Type: application/x-www-form-urlencoded + + grant_type=refresh_token + &refresh_token=4LTC8lb0acc6Oy4esc1Nk9BWC0imAwH7kic16BDC2 + &resource=https%3A%2F%2Fcontacts.example.com%2F + + Figure 5: Access Token Request + + HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-cache, no-store + + { + "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6Ijc3In0.eyJpc3MiOi + JodHRwOi8vYXV0aG9yaXphdGlvbi1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWI + iOiJfX2JfYyIsImV4cCI6MTU4ODQyMDgyNiwic2NvcGUiOiJjb250YWN0cyIs + ImF1ZCI6Imh0dHBzOi8vY29udGFjdHMuZXhhbXBsZS5jb20vIn0.5f4yhqazc + OSlJw4y94KPeWNEFQqj2cfeO8x4hr3YbHtIl3nQXnBMw5wREY5O1YbZED-GfH + UowfmtNaA5EikYAw", + "token_type":"Bearer", + "expires_in":3600, + "scope":"contacts" + } + + Figure 6: Access Token Response + +3. Security Considerations + + An audience-restricted access token that is legitimately presented to + a resource cannot then be taken by that resource and presented + elsewhere for illegitimate access to other resources. The "resource" + parameter enables a client to indicate the protected resources where + the requested access token will be used, which in turn enables the + authorization server to apply the appropriate audience restrictions + to the token. + + Some servers may host user content or be multi-tenant. In order to + avoid attacks where one tenant uses an access token to illegitimately + access resources owned by a different tenant, it is important to use + a specific resource URI including any portion of the URI that + identifies the tenant, such as a path component. This will allow + access tokens to be audience-restricted in a way that identifies the + tenant and prevents their use, due to an invalid audience, at + resources owned by a different tenant. + + Although multiple occurrences of the "resource" parameter may be + included in a token request, using only a single "resource" parameter + is encouraged. If a bearer token has multiple intended recipients + (audiences), then the token is valid at more than one protected + resource and can be used by any one of those resources to access any + of the others. Thus, a high degree of trust between the involved + parties is needed when using access tokens with multiple audiences. + Furthermore, an authorization server may be unwilling or unable to + fulfill a token request with multiple resources. + + Whenever feasible, the "resource" parameter should correspond to the + network-addressable location of the protected resource. This makes + it possible for the client to validate that the resource being + requested controls the corresponding network location, reducing the + risk of malicious endpoints obtaining tokens meant for other + resources. If the "resource" parameter contains an abstract + identifier, it is the client's responsibility to validate out of band + that any network endpoint to which tokens are sent are the intended + audience for that identifier. + +4. Privacy Considerations + + In typical OAuth deployments the authorization sever is in a position + to observe and track a significant amount of user and client + behavior. It is largely just inherent to the nature of OAuth, and + this document does little to affect that. In some cases, however, + such as when access token introspection is not being used, use of the + resource parameter defined herein may allow for tracking behavior at + a somewhat more granular and specific level than would otherwise be + possible in its absence. + +5. IANA Considerations + +5.1. OAuth Parameters Registration + + This specification updates the following value in the IANA "OAuth + Parameters" registry [IANA.OAuth.Parameters] established by + [RFC6749]. + + Parameter name: resource + Parameter usage location: authorization request, token request + Change controller: IESG + Specification document(s): RFC 8707 + +5.2. OAuth Extensions Error Registration + + This specification updates the following error in the IANA "OAuth + Extensions Error Registry" [IANA.OAuth.Parameters] established by + [RFC6749]. + + Error name: invalid_target + Error usage location: implicit grant error response, token error + response + Related protocol extension: resource parameter + Change controller: IESG + Specification document(s): RFC 8707 + +6. References + +6.1. Normative References + + [IANA.OAuth.Parameters] + IANA, "OAuth Parameters", + <https://www.iana.org/assignments/oauth-parameters>. + + [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>. + + [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>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + +6.2. Informative References + + [JWT-SAR] Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization + Framework: JWT Secured Authorization Request (JAR)", Work + in Progress, Internet-Draft, draft-ietf-oauth-jwsreq-20, + 21 October 2019, + <https://tools.ietf.org/html/draft-ietf-oauth-jwsreq-20>. + + [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>. + + [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token + (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, + <https://www.rfc-editor.org/info/rfc7519>. + + [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., + and C. Mortimore, "System for Cross-domain Identity + Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, + September 2015, <https://www.rfc-editor.org/info/rfc7644>. + + [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", + RFC 7662, DOI 10.17487/RFC7662, October 2015, + <https://www.rfc-editor.org/info/rfc7662>. + +Acknowledgements + + This specification was developed within the OAuth Working Group under + the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with + Eric Rescorla, Benjamin Kaduk, and Roman Danyliw serving as Security + Area Directors. Additionally, the following individuals contributed + ideas, feedback, and wording that helped shape this specification: + + Vittorio Bertocci, Sergey Beryozkin, Roman Danyliw, William Denniss, + Vladimir Dzhuvinov, George Fletcher, Dick Hardt, Phil Hunt, Michael + Jones, Benjamin Kaduk, Barry Leiba, Torsten Lodderstedt, Anthony + Nadalin, Justin Richer, Adam Roach, Nat Sakimura, Rifaat Shekh-Yusef, + Filip Skokan, Éric Vyncke, and Hans Zandbelt. + +Authors' Addresses + + Brian Campbell + Ping Identity + + Email: brian.d.campbell@gmail.com + + + John Bradley + Yubico + + Email: ve7jtb@ve7jtb.com + + + Hannes Tschofenig + Arm Limited + + Email: hannes.tschofenig@gmx.net |