idnits 2.17.1 draft-sakimura-oauth-meta-08.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 : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 10 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 15, 2017) is 2353 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) == Unused Reference: 'RFC2616' is defined on line 385, but no explicit reference was found in the text == Unused Reference: 'HAL' is defined on line 406, but no explicit reference was found in the text == Unused Reference: 'RFC4627' is defined on line 412, but no explicit reference was found in the text == Unused Reference: 'RFC6570' is defined on line 417, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group N. Sakimura 3 Internet-Draft Nomura Research Institute 4 Intended status: Standards Track N. Matake 5 Expires: May 19, 2018 GREE, Inc. 6 S. Preibisch 7 CA Technologies 8 November 15, 2017 10 OAuth Response Metadata 11 draft-sakimura-oauth-meta-08 13 Abstract 15 This specification defines an extensible metadata framework that may 16 be inserted into the OAuth 2.0 responses to assist the clients to 17 process those responses. It is expressed either as a link header, or 18 query parameters. It will allow the client to learn the metadata 19 about the particular response. For example, the client can learn 20 where the members in the response could be used, what is the 21 characteristics of the payload is, how it should be processed, and so 22 on. Since they are just additional response header/query parameters, 23 any client that does not understand this extension should not break 24 and work normally while supporting clients can utilize the metadata 25 to take the advantage of the extension. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on May 19, 2018. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 63 1.2. terminology . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Resource Endpoint Resonse . . . . . . . . . . . . . . . . . . 3 65 3. Token Endpoint Response . . . . . . . . . . . . . . . . . . . 4 66 4. Authorization Endpoint HEAD response . . . . . . . . . . . . 5 67 5. Authorization Response . . . . . . . . . . . . . . . . . . . 6 68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 69 6.1. Link Type Registration . . . . . . . . . . . . . . . . . 6 70 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 7.1. Authorization Response Query Parameter Tampering by a Bad 72 User . . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 74 9. Document History . . . . . . . . . . . . . . . . . . . . . . 7 75 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 10.1. Normative References . . . . . . . . . . . . . . . . . . 9 77 10.2. Informational References . . . . . . . . . . . . . . . . 9 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 80 1. Introduction 82 Although OAuth 2.0 [RFC6749] has been known for its REST 83 friendliness, OAuth itself is not RESTful, as it heavily relies on 84 out-of-band information to drive the interactions. This situation 85 can be eased by hypertext-enabling the endpoint responses through the 86 introduction of data structure that represents such hypertext and 87 other metadata. 89 Hyper-text enabling the OAuth responses has many advantages. For 90 example, 92 o The protected resource can tell which authorization servers it 93 supports. 95 o Permissioned resource discovery: It is possible to tell the client 96 which resource endpoint it should use. This has a privacy 97 advantage. The location of the resource by itself may be a 98 sensitive information as its location may reveal information about 99 the resource owner. Therefore, it may be sensible to tell the 100 location only after the user consent. 102 o It is possible to give a hint on the processing of the payload. 104 o It will be resitant to IdP Mix-up attack. 106 o It will be resitant to Code Phishing Attack. 108 This specification defines methods to represent such metadata in the 109 authorization and token responses. 111 1.1. Requirements Notation and Conventions 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in RFC 2119 [RFC2119]. 117 1.2. terminology 119 This specification uses the terms "Access Token", "Authorization 120 Code", "Authorization Endpoint", "Authorization Grant", 121 "Authorization Server", "Client", "Client Authentication", "Protected 122 Resource", "Refresh Token", and "Token Endpoint" defined by OAuth 2.0 123 [RFC6749]. 125 2. Resource Endpoint Resonse 127 Resource Endpoints that implement this specification returns the 128 following link relation (rel) and the corresonding URI value as 129 defined in [RFC5988] in the response header. The response header can 130 be returned in response to HEAD, GET, or POST request to the 131 endpoint. 133 duri The URI of the corresponding authorization server's discovery 134 document, from which the client can learn the server capabilities 135 and endpoints. 137 auri The URI of the corresponding Authorization Endpoint URI. 139 A typical example of the use of these header values are in the case 140 of the Client accessing the protected resource without a propoer 141 credential. For example, in the case of an [RFC6750] protected 142 resource, the unauthorized access may result in a response header 143 that includes both WWW-Authenticate header as well as the Web Linking 144 header indicating either the Authorization Endpoint URI or the 145 discovery document URI. 147 There is no cardinality restriction on relations put in place by 148 [RFC5988]. Therefore, the resource can respond with multiple 149 Authorization Endpoint URI or Discovery Document URIs from which the 150 Client may choose the appropriate one. 152 HTTP/1.1 401 Unauthorized 153 WWW-Authenticate: Bearer realm="example" 154 Link: ; rel="duri", 155 ; rel="duri", 156 ; rel="auri", 157 ; rel="auri", 158 ; rel="payments" 160 3. Token Endpoint Response 162 Token Endpoints that implements this specification returns the 163 following link relation (rel) and the corresponding URI value as 164 defined in [RFC5988] in the Access Token Response defined in 165 [RFC6749]. 167 ruri Resource URI. The value of this parameter is the URI of the 168 Resource Endpoint that the Access Token is supposed to be used at. 169 If this value is present, the client MUST NOT send the Access 170 Token to any other URI. 172 turi Token Endpoint URI. The value of this parameter is the URI of 173 the Token Endpoint that the Refresh Token can be sent to obtain a 174 new Access Token. If this value is present, then the client MUST 175 NOT send the refresh token to any other places. 177 Any other rels that are registered in Link Relation Type Registry 178 defined in [RFC5988] registry can be used. 180 There is no cardinality restriction on relations put in place by 181 [RFC5988]. Therefore, the Token Endpoing can respond with multiple 182 Resource Endpoint URI or Discovery Document URIs from which the 183 Client may choose the appropriate one. 185 Following is an example of an HTTPS response. 187 HTTP/1.1 200 OK 188 Link: ; rel="ruri", 189 ; rel="ruri", 190 ; rel="payments" 191 Content-Type: application/JSON; charset=utf-8 193 { 194 "access_token":"aCeSsToKen" 195 } 197 4. Authorization Endpoint HEAD response 199 Authorization Endpoints that implements this specification returns 200 the following link relation (rel) and the corresponding URI value as 201 defined in [RFC5988] in the response to the HEAD request. 203 auri The canonical URI of the Authorization Endpoint URI. 205 turi Token Endpoint URI. The value of this parameter is the URI of 206 the Token Endpoint that the Authorization Code can be sent to 207 obtain the Access Token. 209 duri The URI of discovery document, from which the client can learn 210 the server capabilities and endpoints. 212 ruri Resource URI. The value of this parameter is the URI of the 213 Resource Endpoint that the Access Token can be used at. If this 214 parameter is specified, the client MUST NOT send the Access Token 215 to any other URIs than the value of this parameter. 217 There is no cardinality restriction on relations put in place by 218 [RFC5988]. Therefore, the Authorization Endpoint can respond with 219 multiple Endpoint URIs with a same relation type from which the 220 Client may choose the appropriate one. 222 Following is an example of an HTTPS response. 224 HTTP/1.1 200 OK 225 Link: ; rel="duri", 226 ; rel="duri", 227 ; rel="payments" 228 Content-Type: application/JSON; charset=utf-8 229 5. Authorization Response 231 While [RFC5988] defines a useful way of conveying link relations, it 232 cannot be utilized for a redirect based communication such as the 233 authorization response of OAuth 2.0. This section defines a way to 234 return a limited set of those link relations as query parameters so 235 that it can be conveyed over the redirection. 237 The authorization response of the implementation of this 238 specification may return the following query parameter in the 239 redirect URI. 241 turi Token Endpoint URI. The value of this parameter is the URI of 242 the Token Endpoint that the Authorization Code can be sent to 243 obtain the Access Token. If this parameter is specified, the 244 client MUST check that the value of turi matches exactly with the 245 pre-registered token endpoint URI of the Authorization Server that 246 the session recoverd from the state variable points to. The 247 client MUST NOT send the code to any other URIs than the value of 248 this parameter. 250 ruri Resource URI. The value of this parameter is the URI of the 251 Resource Endpoint that the Access Token can be used at. If this 252 parameter is specified, the client MUST NOT send the Access Token 253 to any other URIs than the value of this parameter. 255 As long as the link relation type string does not collide with the 256 underlying protocol parameters, they can also be specified as a query 257 parameter. The value MUST be encoded in application/x-www-form- 258 urlencoded. 260 The following is an example of such response. Line breaks are for 261 display purposes only. 263 HTTP/1.1 302 Found 264 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 265 &turi=https%3A%2F%2Fexample.com%2Ftoken 266 &state=xyz 268 6. IANA Considerations 270 6.1. Link Type Registration 272 Pursuant to [RFC5988], the following link type registrations [[will 273 be]] registered by mail to link-relations@ietf.org. 275 o Relation Name: turi 276 o Description: An OAuth 2.0 Token Endpoint specified in section 3.2 277 of [RFC6749]. 279 o Reference: This specification 281 o Relation Name: ruri 283 o Description: An OAuth 2.0 Resource Endpoint specified in section 284 3.2 of [RFC6750]. 286 o Reference: This specification 288 7. Security Considerations 290 7.1. Authorization Response Query Parameter Tampering by a Bad User 292 The query response parameters may be tampered by the man-in-the- 293 browser. It can also be tampered by a malicious user. In general, 294 anything that comes via the browser/user-agent can be tainted and 295 untrusted. 297 This specification mandates the turi check so that tamparing of turi 298 by the malicious user will be detected. It does not mandate ruri 299 check as the user can get the Access Token and send it to anywhere he 300 wants anyways when it is returned to the browser. 302 However, other parameters are not protected. The Client MUST treat 303 them tainted and implement its own check rules for each parameters. 305 To solve this "Tampering by bad user", either HMAC(concat(params)) 306 need to be sent with them or have all of them inside the JWS. 308 8. Acknowledgements 310 Members of OAuth WG helped to form this specification. Notabely: 311 Hannes tschofenig, John Bradley, Justin Richer, Kaoru Maeda, Masashi 312 Kurabayashi, Michael B. Jones, Phil Hunt, William Dennis, James 313 Manger, (add yourselves). 315 9. Document History 317 -07 319 o Added note that there is no cardinality requirements so that 320 multiple endpoints can be returned by repeating a same rel. 322 o Added resource endpoint response. 324 -06 326 o Removed duri description from token response as it is not needed. 328 o Made the processing instruction more precise. 330 o Added RFC5988 defined link relation type in the example. 332 o Swaped the order of the authorization response and token response. 333 Now, token response gets explained first so that the reader will 334 grasp the basic concept according to RFC5988 and regards the 335 authorization response extension as a mapping of RFC5988 into 336 query parameter form. 338 -05 340 o Factored out JSON Meta and now using query param and Web Linking. 342 -04 344 o Date refresh. 346 -03 348 o Date refresh. 350 -02 352 o Added Mike Kelly as an author. 354 o xref fix. 356 o Introduced "operations" as in draft-ietf-scim-api-00#section-3.5. 358 o Updated the informative reference to HAL. 360 o Added description to OAuth Token Endpoint hrefs. 362 o Added content-type to the example. 364 o Added Area and Working Group. 366 -01 368 o Some format changes, reference fix, and typo fixes. 370 o Changed 'items' to 'elements' to match the JSON terminology. 372 -00 374 o Initial Draft 376 10. References 378 10.1. Normative References 380 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 381 Requirement Levels", BCP 14, RFC 2119, 382 DOI 10.17487/RFC2119, March 1997, 383 . 385 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 386 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 387 Transfer Protocol -- HTTP/1.1", RFC 2616, 388 DOI 10.17487/RFC2616, June 1999, 389 . 391 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 392 DOI 10.17487/RFC5988, October 2010, 393 . 395 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 396 RFC 6749, DOI 10.17487/RFC6749, October 2012, 397 . 399 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 400 Framework: Bearer Token Usage", RFC 6750, 401 DOI 10.17487/RFC6750, October 2012, 402 . 404 10.2. Informational References 406 [HAL] Kelly, M., "JSON Hypermedia API Language", February 2013. 408 [oauth-lrdd] 409 Mills, W., "Link Type Registrations for OAuth 2", October 410 2012. 412 [RFC4627] Crockford, D., "The application/json Media Type for 413 JavaScript Object Notation (JSON)", RFC 4627, 414 DOI 10.17487/RFC4627, July 2006, 415 . 417 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 418 and D. Orchard, "URI Template", RFC 6570, 419 DOI 10.17487/RFC6570, March 2012, 420 . 422 Authors' Addresses 424 Nat Sakimura 425 Nomura Research Institute 427 Email: sakimura@gmail.com 429 Nov Matake 430 GREE, Inc. 432 Email: nov@matake.jp 433 URI: http://matake.jp 435 Sascha Preibisch 436 CA Technologies 438 Email: Sascha.Preibisch@gmail.com