idnits 2.17.1 draft-sakimura-oauth-requrl-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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There is 1 instance of too long lines in the document, the longest one being 5 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 (June 17, 2010) is 5059 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: 'FIPS180-2' is defined on line 307, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-2' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group N. Sakimura 3 Internet-Draft Nomura Research Institute 4 Intended status: Standards Track June 17, 2010 5 Expires: December 19, 2010 7 Request by Reference ver.1.0 for OAuth 2.0 8 draft-sakimura-oauth-requrl-00 10 Abstract 12 This document defines a simple mechanism of making request by 13 reference in OAuth 2.0. The reference is given as URL and request 14 parameters are defined as JSON object which is pointed by the URL. 16 Requirements Language 18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 19 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 20 document are to be interpreted as described in RFC 2119 [RFC2119]. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 19, 2010. 39 Copyright Notice 41 Copyright (c) 2010 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.1. JSON OAuth Request . . . . . . . . . . . . . . . . . . . . 4 60 3.2. Signed JSON OAuth Request . . . . . . . . . . . . . . . . . 4 61 3.3. Encrypted Format . . . . . . . . . . . . . . . . . . . . . 5 62 4. Obtaining End-User Authorization . . . . . . . . . . . . . . . 6 63 4.1. Authorization Server Response . . . . . . . . . . . . . . . 6 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 66 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 8.1. Normative References . . . . . . . . . . . . . . . . . . . 7 69 8.2. Informative References . . . . . . . . . . . . . . . . . . 8 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 1. Introduction 74 An additional parameter 'request_url' is introduced as one of the 75 request parameter of the flows of OAuth 2.0 [oauth2]. 77 There are a few cases that this is useful such as: 79 1. When the User Agent looks like it would not like long URLs - It 80 is entirely possible that some extension makes a long URL. For 81 example, the client might want to send a public key with the 82 request. 84 2. When the server wants the request non-repudiation - The server 85 might want the request to be non-repudiable. It is possible to 86 sign the request dynamically, but a simpler way of doing it is to 87 make a signed request file and put it on the client. It can just 88 be done by a client utility or something, so that the private key 89 does not even have to reside on the server nor the client needs 90 to program anything. 92 3. When the server wants the requests to be cacheable - If the 93 request_url comes with sha256 hash as defined in FIPS180-2 94 [FIPS180-2]of the file, the server knows if the file has changed 95 without fetching it, so it does not have to re-fetch a same file, 96 which is a win as well. 98 4. When the client wants to simplify the implementation without 99 compromising the security If the request parameters go through 100 the Browser, it may be tampered at the browser even if TLS was 101 used. This implies we need to have signature on the request as 102 well. However, if HTTPS request_url was used, it is not going to 103 be tampered, thus we now do not have to sign the request. This 104 simplifies the implementation. 106 2. Terminology 108 Following parameter is defined as a request and response parameter. 110 request_url The absolute URL from which request parameters are 111 obtained. 113 Request File This is a physical or logical file that the 114 'request_url' points to. It is in JSON format. It MAY include 115 all the potential variables including extension and non-oauth 116 variables. Request File can optionally be digitally signed. To 117 sign the request file, magic signatures [magic_signatures] is 118 used. 120 3. Formats 122 There are several format that this document defines. 124 3.1. JSON OAuth Request 126 The OAuth authorization request parameters are included in the entity 127 body of the HTTP response using the "application/json" media type as 128 defined by JSON [RFC4627]. It MAY include any other parameters as 129 well. The parameters are serialized into a JSON structure by adding 130 each parameter at the highest structure level. Parameter names and 131 string values are included as JSON strings. Numerical values are 132 included as JSON numbers. 134 For example: 136 HTTP/1.1 200 OK 137 Content-Type: application/json 139 { 140 "redirect_url":"https://example.com/rp/endpoint_url", 141 "cliend_id":"http://example.com/rp/", 142 "state":"ab890f0d" 143 } 145 3.2. Signed JSON OAuth Request 147 To achieve non-repudiation and ascertained provenance of the JSON 148 OAuth Request when it was obtained through unprotected channel, one 149 MAY use asymmetric signature as in [magic_signatures] where 150 parameters are as follows. 152 "data_type":"application/json" 154 "encoding":"base64url" 156 "alg":"RSA-SHA256" 158 "data":base64url encoded JSON representation of the assertion. 160 This specification defines an additional parameter. 162 o certs_url 164 Value: A URL from which one can retrieve PEM format X.509 165 certificate. It is used as the replacement of "keyhash". Only 166 either of the keyhash or certs_url MAY be used. When certs_url 167 was used, the processor MUST obtain the certificate from this 168 URL and use public key contained in it to verify the signature. 169 In addition, the processor MUST verify the domain of the 170 "request_url" against the CN of the certificate. 172 Any other variables can be included in any level of the JSON 173 structure. The processor MUST ignore the parameter that it does not 174 understand. 176 Following is the non-normative illustration of a signed response. 177 (Note: Line wraps in the values are only for the display purpose. 178 New lines MUST be escaped in JSON values.) 179 { 180 "data_type":"application/json", 181 "encoding":"base64url", 182 "alg":"RSA-SHA256", 183 "data":"base64url encoded data without padding", 184 "sigs": [ 185 { 186 "value": "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76 187 up8w63i2fWHvLKJzeGLKfyHg8ZomQ", 188 "certs_url": "https://rp.example.com/certs.pem" 189 } 190 ] 191 } 193 3.3. Encrypted Format 195 The HTTP response may be encrypted by the receiving party's public 196 key for audience restriction and confidentiality. If it is 197 encrypted, the data is formatted as JSON Encryption Envelope 198 [json_enc]. The following parameter MUST be set as follows: 200 o data_type - "http://openid.net/specs/ab/1.0#openid2json-enc" 202 Following is a non-normative example of encrypted payload. 204 { 205 "class_id":"http://jsonenc.info/json-encryption/1.0/", 206 "data_type":"http://openid.net/specs/ab/1.0#openid2json-enc", 207 "enc_data":"b5guwzFgvrIUd7XcXI0bAFrg-....O69VKhY", 208 "enc_type_asy":"http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p", 209 "enc_type":"http://www.w3.org/2001/04/xmlenc#aes256-cbc", 210 "enc_key":"mHM2ongmZlPVexe....2lsBNdw", 211 "enc_iv":"_b4INfYIRwLPZdxB2L7wJg", 212 "enc_ref":"https://rp.example.com/rpf_ax.json", 213 "enc_thumbprint":"511e7a9cfe5eda16fa70f553c2dfa3c473e06423" 214 } 216 4. Obtaining End-User Authorization 218 When the client is obtaining End-User Authorization as in Section 3 219 of OAuth 2.0 [oauth2] , the client MAY use request_url instead of any 220 but 'state' parameter. The corresponding Request File MUST have all 221 the necessary parameters which was to be queried in this request. 222 When sending the request_url, the client MAY provide the sha256 hash 223 as defined in FIPS180-2 [FIPS180-2]of the Request File as a fragment 224 to it to assist the cache utilization decision of the Authorization 225 Server. 227 For example, the client directs the end-user's user-agent to make the 228 following HTTPS request (line breaks are for display purposes only): 230 GET /authorize?request_url=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 231 Host: server.example.com 233 The Request File MAY be signed AND/OR encrypted. 235 Upon receipt of 'requst_url' in the request, the authorization server 236 MUST send a GET request to the 'request_url' to retrieve the content 237 of the Request File unless it is already cached at the Authorization 238 Server. 240 If the response was signed AND/OR encrypted, it has to be decoded 241 accordingly before being processed. 243 Then, the Authorization Server MUST reconstruct the complete client 244 request from the original HTTP request and the content of the Request 245 File. Then, the process continues as described in Section 3 of OAuth 246 2.0 [oauth2] . 248 4.1. Authorization Server Response 250 Authorization Server Response is created and sent to the client as in 251 Section 3.1 of OAuth 2.0 [oauth2] . 253 In addition, this document defines additional 'error' values as 254 follows: 256 o "invalid_request_url" - The provided request_url was not 257 available. 259 o "invalid_request_file_format" - The Request File format was 260 invalid. 262 o "invalid_request_params" - The parameter set provided in the 263 Request File was invalid. 265 5. IANA Considerations 267 This document makes no request of IANA. 269 6. Security Considerations 271 When obtaining the Request FIle, the Authorization Server SHOULD use 272 either HTTP over TLS 1.2 as defined in RFC5246 [RFC5246] AND/OR 273 Signed JSON Request. 275 If the Request File contains personally identifiable or sensitive 276 information, the "request_url" MUST be of one-time use and MUST have 277 large enough entropy deemed necessary with applicable security 278 policy. For higher security requirement, using Encryption described 279 in (Section 3.3) is strongly recommended. 281 [[ToDo]] 283 7. Acknowledgements 285 Following people contributed to creating this document through the 286 OpenID Artifact Binding 1.0 [openid_ab] . 288 Breno de Medeiros (Google), Hideki Nara (TACT), John Bradley (Wingaa) 289 , Nat Sakimura (NRI) , Ryo Itou (Yahoo! 290 Japan) 292 Many people joined the discussion of the above at IIW and other 293 occasions including Allen Tom (Yahoo!), George Fletcher (AOL), Dick 294 Hardt (Independent) [[ToDo]] 296 In addition following people contributed to this and previous 297 versions through The OAuth Working Group. 299 David Recordon (Facebook), Luke Shepard (Facebook), James H. Manger 300 (Telstra), Marius Scurtescu (Google), John Panzer (Google), Dirk 301 Balfanz (Google). 303 8. References 305 8.1. Normative References 307 [FIPS180-2] 308 U.S. Department of Commerce and National Institute of 309 Standards and Technology, "Secure Hash Signature 310 Standard", FIPS 180-2. 312 Defines Secure Hash Algorithm 256 (SHA256) 314 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 315 Requirement Levels", BCP 14, RFC 2119, March 1997. 317 [RFC4627] Crockford, D., "The application/json Media Type for 318 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 320 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 321 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 323 [json_enc] 324 Bradeley, J. and N. Sakimura, "JSON Encryption Envelope", 325 February 2010. 327 [magic_signatures] 328 Panzer, J. and B. Laurie, "Magic Signatures", 329 February 2010. 331 [oauth2] Hammer-Lahav, E., "The OAuth 2.0 Protocol", June 2010. 333 8.2. Informative References 335 [openid_ab] 336 openid-specs-ab@openid.net, "OpenID Artifact Binding 1.0", 337 June 2010. 339 Author's Address 341 Nat Sakimura 342 Nomura Research Institute 343 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 344 Chiyoda-ku, Tokyo 100-0005 345 Japan 347 Phone: +81-3-5533-2111 348 Email: n-sakimura@nri.co.jp