idnits 2.17.1 draft-campbell-oauth-resource-indicators-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 15, 2016) is 2711 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group B. Campbell 3 Internet-Draft J. Bradley 4 Intended status: Standards Track Ping Identity 5 Expires: May 19, 2017 H. Tschofenig 6 ARM 7 November 15, 2016 9 Resource Indicators for OAuth 2.0 10 draft-campbell-oauth-resource-indicators-02 12 Abstract 14 This straw-man specification defines an extension to The OAuth 2.0 15 Authorization Framework that enables the client and authorization 16 server to more explicitly to communicate about the protected 17 resource(s) to be accessed. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on May 19, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Resource Parameter . . . . . . . . . . . . . . . . . . . . . 3 57 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 58 3.1. OAuth Parameters Registration . . . . . . . . . . . . . . 5 59 3.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 5 60 3.2. OAuth Extensions Error Registration . . . . . . . . . . . 6 61 3.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 63 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 5.1. Normative References . . . . . . . . . . . . . . . . . . 7 65 5.2. Informative References . . . . . . . . . . . . . . . . . 7 66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 67 Appendix B. Document History . . . . . . . . . . . . . . . . . . 8 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 70 1. Introduction 72 Several years of deployment and implementation experience with OAuth 73 2.0 [RFC6749] has uncovered a need, in some circumstances, for the 74 client to explicitly signal to the authorization sever where it 75 intends to use the access token it is requesting. 77 Knowing which resource server will process the access token enables 78 the authorization server to construct the token as necessary for that 79 entity. Properly encrypting the token (or content within the token) 80 to a particular resource server, for example, requires knowing which 81 resource server will receive and decrypt the token. Furthermore, 82 various resource servers oftentimes have different requirements with 83 respect to the data contained in, or referenced by, the token and 84 knowing the resource server where the client intends to use the s 85 token allows the the authorization server to mint the token 86 accordingly. 88 Specific knowledge of the intended recipient(s) of the access token 89 also helps facilitate improved security characteristics of the token 90 itself. Bearer tokens, currently the only defined type of OAuth 91 access token, allow any party in possession of a token to get access 92 to the associated resources. To prevent misuse, two important 93 security assumptions must hold: bearer tokens must be protected from 94 disclosure in storage and in transit and the access token must only 95 be valid for use at a specific resource server and for a specific 96 scope. When the authorization server is informed of the resource 97 server that will process the access token, it can restrict the 98 intended audience of that token such that it cannot be used at other 99 resource servers. Section 5.2 of OAuth 2.0 Authorization Framework: 100 Bearer Token Usage [RFC6750] prescribes including the token's 101 intended recipients within the token to prevent token redirect. 103 Scope, from Section 3.3 of OAuth 2.0 [RFC6749], sometimes is 104 overloaded to convey the location or identity of the resource server, 105 however, doing so isn't always feasible or desirable. Scope is 106 typically about what access is being requested rather than where that 107 access will be redeemed (e.g. "email", "user:follow", "user_photos", 108 and "channels:read" are a small sample of scope values in use). 110 A means for the client to signal to the authorization sever where it 111 intends to use the access token it's requesting is important and 112 useful. A number of implementations and deployments of OAuth 2.0 113 have already employed proprietary parameters toward that end. This 114 specification aims to provide a standardized and interoperable 115 alternative to the proprietary approaches going forward. 117 1.1. Requirements Notation and Conventions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 121 "OPTIONAL" in this document are to be interpreted as described in RFC 122 2119 [RFC2119]. 124 1.2. Terminology 126 This specification uses the terms "access token", "refresh token", 127 "authorization server", "resource server", "authorization endpoint", 128 "authorization request", "authorization response", "token endpoint", 129 "grant type", "access token request", "access token response", and 130 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 132 2. Resource Parameter 134 The client may indicate the resource server(s) for which it is 135 requesting an access token by including the following parameter in 136 the request. 138 resource 139 OPTIONAL. The value of the "resource" parameter indicates a 140 resource server where the requested access token will be used. It 141 MUST be an absolute URI, as specified by Section 4.3 of[RFC3986], 142 and MUST NOT include a query or fragment component. If the 143 authorization server fails to parse the provided value or does not 144 consider the resource server acceptable, it MUST reject the 145 request and provide an error response with the error code 146 "invalid_resource". Multiple "resource" parameters may be used to 147 indicate that the issued token is intended to be used at multiple 148 resource servers. 150 When an access token will be returned from the authorization 151 endpoint, the "resource" parameter is used in the authorization 152 request to the authorization endpoint as defined in Section 4.2.1 of 153 OAuth 2.0 [RFC6749]. An example of an authorization request where 154 the client tells the authorization server that it wants a token for 155 use at "https://rs.example.com/" is shown in Figure 1 below. 157 GET /as/authorization.oauth2?response_type=token 158 &client_id=s6BhdRkqt3&state=laeb 159 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 160 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 161 Host: authorization-server.example.com 163 Figure 1: Protected Resource Request 165 When the access token is returned from the token endpoint, the 166 request parameter is included in the token request to the token 167 endpoint. Sections 4.1.1, 4.3.1, 4.4.2, 4.5 and 6 of OAuth 2.0 168 [RFC6749] define requests to the token endpoint with different grant 169 types. An example of a token request, using a refresh token, where 170 the client tells the authorization server that it wants a token for 171 use at "https://rs.example.com/" is shown in Figure 2 below. 173 POST /as/token.oauth2 HTTP/1.1 174 Host: authorization-server.example.com 175 Authorization: Basic czZCaGRSa3F0Mzpoc3FFelFsVW9IQUU5cHg0RlNyNHlJ 176 Content-Type: application/x-www-form-urlencoded 178 grant_type=refresh_token 179 &refresh_token=4LTC8lb0acc6Oy4esc1Nk9BWC0imAwH 180 &resource=https%3A%2F%2Frs.example.com%2F 182 Figure 2: Protected Resource Request 184 The "resource" parameter indicates the physical location of resource 185 server, typically as an https URL, where the client intends to use 186 the requested access token. This enables the authorization server to 187 apply policy as appropriate for the resource, such as determining the 188 type and content of the token to be issued, if and how the token is 189 to be encrypted, and applying appropriate audience restrictions to 190 the token. 192 The client SHOULD provide the most specific URI that it can for the 193 set of resources or API it intends to access. In practice a client 194 will know a base URI for the resource server application that it 195 interacts with, which is appropriate to use as the value of the 196 "resource" parameter. The client SHOULD use the base URI for the API 197 unless specific knowledge of resource server dictates the client use 198 a shorter path. For example, the value "https://rs.example.com/" 199 would be used for a resource server that is the exclusive application 200 on that host, however, if the resource server is one of many 201 applications on that host, something like "https://rs.example.com/ 202 application/" would be used. Another example, for an API like SCIM 203 [RFC7644] that has multiple endpoints such as 204 "https://rs.example.com/scim/Users", "https://rs.example.com/scim/ 205 Groups", and "https://rs.example.com/scim/Schemas" The client should 206 use "https://rs.example.com/scim/" as the resource so that the issued 207 access token is valid for all the endpoints of the SCIM API. 209 The authorization server SHOULD audience restrict the access token to 210 the resource server(s) indicated by the "resource" parameter. 211 Audience restrictions can be communicated in JSON Web Tokens 212 [RFC7519] with the "aud" claim and the top-level member of the same 213 name provides the audience restriction information in a Token 214 Introspection [RFC7662] response. The authorization server may use 215 the exact "resource" value as the audience or it may map from that 216 value to a more general URI or abstract identifier for the resource 217 server. 219 The requested resource pertains to the access token that is the 220 expected result of the request and not to the underlying access 221 granted by the resource owner. 223 3. IANA Considerations 225 3.1. OAuth Parameters Registration 227 This specification registers the following value in the IANA "OAuth 228 Parameters" registry [IANA.OAuth.Parameters] established by 229 [RFC6749]. 231 3.1.1. Registry Contents 233 o Parameter name: resource 234 o Parameter usage location: authorization request, token request 235 o Change controller: IESG 236 o Specification document(s): Section 2 of [[ this specification ]] 238 3.2. OAuth Extensions Error Registration 240 This specification registers the following error in the IANA "OAuth 241 Extensions Error Registry" [IANA.OAuth.Parameters] established by 242 [RFC6749]. 244 3.2.1. Registry Contents 246 o Error name: invalid_resource 247 o Error usage location: implicit grant error response, token error 248 response 249 o Related protocol extension: resource parameter 250 o Change controller: IESG 251 o Specification document(s): Section 2 of [[ this specification ]] 253 4. Security Considerations 255 An access token that is audience restricted to a resource server, 256 which obtains the token legitimately, cannot be used to access 257 resources on behalf of the resource owner at other resource servers. 258 The "resource" parameter enables a client to indicate the resource 259 server where the requested access token will be used, which in turn 260 enables the authorization server to apply the appropriate audience 261 restrictions to the token. 263 Some Resource servers may host user content or be multi-tenant. In 264 order to avoid attacks that might confuse a client into sending a AT 265 to a user controlled resource it is important to use the a specific 266 resource URI including path and not use just a host with no path. 267 This will cause any AT issued for accessing the user controlled 268 resource to have a invalid audience if replayed against the 269 legitimate resource API. 271 Although multiple occurrences of the "resource" parameter may be 272 included in a request, using only a single "resource" parameter is 273 encouraged. A bearer token that has multiple intended recipients 274 (audiences) can be used by any one of those recipients at any other. 275 Thus, a high degree of trust between the involved parties is needed 276 when using access tokens with multiple audiences. Furthermore an 277 authorization server may be unwilling or unable to fulfill a token 278 request with multiple resources. 280 [[TODO: I continue to question the value of allowing multiple 281 resources vs the functional and security complexity that comes with 282 doing so. Writing the preceding paragraph just underscores that 283 concern. So just noting it here.]] 285 5. References 287 5.1. Normative References 289 [IANA.OAuth.Parameters] 290 IANA, "OAuth Parameters", 291 . 293 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 294 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 295 RFC2119, March 1997, 296 . 298 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 299 Resource Identifier (URI): Generic Syntax", STD 66, RFC 300 3986, DOI 10.17487/RFC3986, January 2005, 301 . 303 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 304 RFC 6749, DOI 10.17487/RFC6749, October 2012, 305 . 307 5.2. Informative References 309 [I-D.draft-tschofenig-oauth-audience] 310 Tschofenig, H., "OAuth 2.0: Audience Information", draft- 311 tschofenig-oauth-audience (work in progress), February 312 2013. 314 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 315 Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/ 316 RFC6750, October 2012, 317 . 319 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 320 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 321 . 323 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 324 and C. Mortimore, "System for Cross-domain Identity 325 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 326 September 2015, . 328 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 329 7662, DOI 10.17487/RFC7662, October 2015, 330 . 332 Appendix A. Acknowledgements 334 The following individuals contributed to discussions relating to and 335 giving rise to this draft specification: 337 George Fletcher, Hans Zandbelt, Justin Richer, Michael Jones, Nat 338 Sakimura, Phil Hunt, Sergey Beryozkin, and Anthony "no go" Nadalin. 340 Appendix B. Document History 342 [[ to be removed by the RFC Editor before publication as an RFC ]] 344 -01 346 o Move Hannes Tschofenig, who wrote 347 [I-D.draft-tschofenig-oauth-audience] in '13, from 348 Acknowledgements to Authors. 349 o Added IANA Considerations to register the "resource" parameter and 350 "invalid_resource" error code. 352 -00 354 o Initial draft to define a resource parameter for OAuth 2.0. 356 Authors' Addresses 358 Brian Campbell 359 Ping Identity 361 Email: brian.d.campbell@gmail.com 363 John Bradley 364 Ping Identity 366 Email: ve7jtb@ve7jtb.com 368 Hannes Tschofenig 369 ARM 371 Email: hannes.tschofenig@gmx.net