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