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