idnits 2.17.1 draft-ietf-oauth-jwsreq-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 : ---------------------------------------------------------------------------- ** 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 (May 29, 2015) is 3254 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-2' ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 6819 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group N. Sakimura, Ed. 3 Internet-Draft Nomura Research Institute 4 Intended status: Standards Track J. Bradley 5 Expires: November 30, 2015 Ping Identity 6 May 29, 2015 8 Request by JWS ver.1.0 for OAuth 2.0 9 draft-ietf-oauth-jwsreq-02 11 Abstract 13 The authorization request in OAuth 2.0 utilizes query parameter 14 serialization. This specification defines the authorization request 15 using JWT serialization. The request is sent through "request" 16 parameter or by reference through "request_uri" parameter that points 17 to the JWT, allowing the request to be optionally signed and 18 encrypted. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on November 30, 2015. 37 Copyright Notice 39 Copyright (c) 2015 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Request Object . . . . . . . . . . . . . . . . . . . . . 3 58 2.2. Request Object URI . . . . . . . . . . . . . . . . . . . 3 59 3. Request Object . . . . . . . . . . . . . . . . . . . . . . . 4 60 4. Request Object URI . . . . . . . . . . . . . . . . . . . . . 5 61 5. Authorization Request . . . . . . . . . . . . . . . . . . . . 6 62 6. Authorization Server Response . . . . . . . . . . . . . . . . 7 63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 7 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7 65 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 66 10. Revision History . . . . . . . . . . . . . . . . . . . . . . 8 67 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 11.1. Normative References . . . . . . . . . . . . . . . . . . 8 69 11.2. Informative References . . . . . . . . . . . . . . . . . 9 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 72 1. Introduction 74 The parameters "request" and "request_uri" are introduced as 75 additional authorization request parameters for the OAuth 2.0 76 [RFC6749] flows. The "request" parameter is a JSON Web Token (JWT) 77 [RFC7519] whose JWT Claims Set holds the JSON encoded OAuth 2.0 78 authorization request parameters. The [RFC7519] can be passed to the 79 authorization endpoint by reference, in which case the parameter 80 "request_uri" is used instead of the "request". 82 Using [RFC7519] as the request encoding instead of query parameters 83 has several advantages: 85 1. The request may be signed so that integrity check may be 86 implemented. If a suitable algorithm is used for the signing, 87 then non-repudiation property may be obtained in addition. 89 2. The request may be encrypted so that end-to-end confidentiality 90 may be obtained even if in the case TLS connection is terminated 91 at a gateway or a similar device. 93 There are a few cases that request by reference are useful such as: 95 1. When it is detected that the User Agent does not support long 96 URLs: Some extensions may extend the URL. For example, the 97 client might want to send a public key with the request. 99 2. Static signature: The client may make a signed Request Object and 100 put it on the client. This may just be done by a client utility 101 or other process, so that the private key does not have to reside 102 on the client, simplifying programming. 104 3. When the server wants the requests to be cache-able: The 105 request_uri may include a sha256 hash of the file, as defined in 106 FIPS180-2 [FIPS180-2], the server knows if the file has changed 107 without fetching it, so it does not have to re-fetch a same file, 108 which is a win as well. 110 4. When the client wants to simplify the implementation without 111 compromising the security. If the request parameters go through 112 the Browser, they may be tampered in the browser even if TLS was 113 used. This implies we need to have signature on the request as 114 well. However, if HTTPS "request_uri" was used, it is not going 115 to be tampered, thus we now do not have to sign the request. 116 This simplifies the implementation. 118 This capability is in use by OpenID Connect [openid_ab]. 120 1.1. Requirements Language 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in RFC 2119 [RFC2119]. 126 2. Terminology 128 For the purposes of this specification, the following terms and 129 definitions apply. 131 2.1. Request Object 133 JWT [RFC7519] that holds OAuth 2.0 authorization requests as JWT 134 Claims Set 136 2.2. Request Object URI 138 Absolute URI from which the Request Object (Section 2.1) can be 139 obtained 141 3. Request Object 143 A Request Object (Section 2.1) is used to provide authorization 144 request parameters for OAuth 2.0 authorization request. It contains 145 OAuth 2.0 [RFC6749] authorization request parameters including 146 extension parameters. It is a JSON Web Signature (JWS) [RFC7515] 147 signed JWT [RFC7519] . The parameters are included as the top-level 148 members of JSON [RFC7159]. Parameter names and string values MUST be 149 included as JSON strings. Numerical values MUST be included as JSON 150 numbers. It MAY include any extension parameters. This JSON 151 [RFC7159] constitutes the [RFC7519] Claims Set. 153 The Request Object MAY be signed or unsigned (plaintext). When it is 154 plaintext, this is indicated by use of the "none" algorithm [RFC7518] 155 in the JWS header. If signed, the Authorization Request Object 156 SHOULD contain the Claims "iss" (issuer) and "aud" (audience) as 157 members, with their semantics being the same as defined in the JWT 158 [RFC7519] specification. 160 The Request Object MAY also be encrypted using JWE [RFC7516] after 161 signing, with nesting performed in the same manner as specified for 162 JWTs [RFC7519]. The Authorization Request Object MAY alternatively 163 be sent by reference using "request_uri" parameter. 165 REQUIRED OAuth 2.0 Authorization Request parameters that are not 166 included in the Request Object MUST be sent as a query parameter. If 167 a required parameter is not present in neither the query parameter 168 nor the Request Object, it forms a malformed request. 170 If the parameter exists in both the query string and the 171 Authorization Request Object, they MUST exactly match. 173 Following is the example of the JSON that constitutes the [RFC7519] 174 Claims Set. 176 { 177 "redirect_url":"https://example.com/rp/endpoint_url", 178 "cliend_id":"http://example.com/rp/" 179 } 181 The following is a non-normative example of a [RFC7519] encoded 182 authorization request object. It includes extension variables such 183 as "nonce", "userinfo", and "id_token". Note that the line wraps 184 within the values are for display purpose only: 186 JWT algorithm = HS256 187 HMAC HASH Key = 'aaa' 189 JSON Encoded Header = "{"alg":"HS256","typ":"JWT"}" 190 JSON Encoded Payload = "{"response_type":"code id_token", 191 "client_id":"s6BhdRkqt3", 192 "redirect_uri":"https://client.example.com/cb", 193 "scope":"openid profile", 194 "state":"af0ifjsldkj", 195 "nonce":"n-0S6_WzA2Mj", 196 "userinfo":{"claims":{"name":null,"nickname":{"optional":true}, 197 "email":null,"verified":null, 198 "picture":{"optional":true}},"format":"signed"}, 199 "id_token":{"max_age":86400,"iso29115":"2"}}" 201 JWT = eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY29kZ 202 SBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiO 203 iJodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkI 204 HByb2ZpbGUiLCJzdGF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zI 205 jp7Im5hbWUiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfSwiZW1haWwiO 206 m51bGwsInZlcmlmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sI 207 mZvcm1hdCI6InNpZ25lZCJ9LCJpZF90b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvM 208 jkxMTUiOiIyIn19.2OiqRgrbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY 210 4. Request Object URI 212 Instead of sending the Request Object in an OAuth 2.0 authorization 213 request directly, this specification allows it to be obtained from 214 the Request Object URI. Using this method has an advantage of 215 reducing the request size, enabling the caching of the Request 216 Object, and generally not requiring integrity protection through a 217 cryptographic operation on the Request Object if the channel itself 218 is protected. 220 The Request Object URI is sent as a part of the OAuth Authorization 221 Request as the value for the parameter called "request_uri". How the 222 Request Object is registered at Request Object URI is out of scope of 223 this specification, but it MUST be done in a protected channel. 225 NOTE: the Request Object MAY be registered at the Authorization 226 Server at the client registration time. 228 When the Authorization Server obtains the Request Object from Request 229 Object URI, it MUST do so over a protected channel. If it is 230 obtained from a remote server, it SHOULD use either HTTP over TLS 1.2 231 as defined in [RFC5246] AND/OR [RFC7515] with the algorithm 232 considered appropriate at the time. 234 When sending the request by "request_uri", the client MAY provide the 235 sha256 hash as defined in FIPS180-2 [FIPS180-2]of the Request Object 236 as the fragment to it to assist the cache utilization decision of the 237 Authorization Server. 239 5. Authorization Request 241 The client constructs the authorization request URI by adding the 242 following parameters to the query component of the authorization 243 endpoint URI using the "application/x-www-form-urlencoded" format: 245 request REQUIRED unless "request_uri" is specified. The Request 246 Object (Section 3) that holds authorization request parameters 247 stated in the section 4 of OAuth 2.0 [RFC6749]. 249 request_uri REQUIRED unless "request" is specified. The absolute 250 URL that points to the Request Object (Section 3) that holds 251 authorization request parameters stated in the section 4 of OAuth 252 2.0 [RFC6749]. 254 state RECOMMENDED. OAuth 2.0 [RFC6749] state. 256 The client directs the resource owner to the constructed URI using an 257 HTTP redirection response, or by other means available to it via the 258 user-agent. 260 For example, the client directs the end-user's user-agent to make the 261 following HTTPS request (line breaks are for display purposes only): 263 GET /authorize?request_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 264 Host: server.example.com 266 The authorization request object MAY be signed AND/OR encrypted. 268 Upon receipt of "request_uri" in the request, the authorization 269 server MUST send a GET request to the "request_uri" to retrieve the 270 authorization request object unless it is already cached at the 271 Authorization Server. 273 If the response was signed AND/OR encrypted, it has to be decoded 274 accordingly before being processed. 276 Then, the Authorization Server MUST reconstruct the complete client 277 request from the original HTTP request and the content of the request 278 object. Then, the process continues as described in Section 3 of 279 OAuth 2.0 [RFC6749] . 281 6. Authorization Server Response 283 Authorization Server Response is created and sent to the client as in 284 Section 4 of OAuth 2.0 [RFC6749] . 286 In addition, this document defines additional 'error' values as 287 follows: 289 invalid_request_uri The provided request_uri was not available. 291 invalid_request_format The Request Object format was invalid. 293 invalid_request_params The parameter set provided in the Request 294 Object was invalid. 296 7. IANA Considerations 298 This document registers following error strings to the OAuth Error 299 Registry. 301 invalid_request_uri The provided request_uri was not available. 303 invalid_request_format The Request Object format was invalid. 305 invalid_request_params The parameter set provided in the Request 306 Object was invalid. 308 8. Security Considerations 310 In addition to the all the security considerations discussed in OAuth 311 2.0 [RFC6819], the following security considerations SHOULD be taken 312 into account. 314 When sending the authorization request object through "request" 315 parameter, it SHOULD be signed with then considered appropriate 316 algorithm using [RFC7515]. The "alg=none" SHOULD NOT be used in such 317 a case. 319 If the request object contains personally identifiable or sensitive 320 information, the "request_uri" MUST be of one-time use and MUST have 321 large enough entropy deemed necessary with applicable security 322 policy. For higher security requirement, using [RFC7516] is strongly 323 recommended. 325 9. Acknowledgements 327 Following people contributed to creating this document through the 328 OpenID Connect 1.0 [openid_ab]. 330 Breno de Medeiros (Google), Hideki Nara (TACT), John Bradley ( Ping 331 Identity) , Nat Sakimura (NRI) , Ryo Itou 332 (Yahoo! Japan), George Fletcher (AOL), Justin Richer (MITRE), Edmund 333 Jay (Illumila), (add yourself). 335 In addition following people contributed to this and previous 336 versions through The OAuth Working Group. 338 David Recordon (Facebook), Luke Shepard (Facebook), James H. Manger 339 (Telstra), Marius Scurtescu (Google), John Panzer (Google), Dirk 340 Balfanz (Google), (add yourself). 342 10. Revision History 344 -02 346 o Now that they are RFCs, replaced JWS, JWE, etc. with RFC numbers. 348 -01 350 o Copy Edits. 352 11. References 354 11.1. Normative References 356 [FIPS180-2] 357 U.S. Department of Commerce and National Institute of 358 Standards and Technology, "Secure Hash Signature 359 Standard", FIPS 180-2, August 2002. 361 Defines Secure Hash Algorithm 256 (SHA256) 363 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 364 Requirement Levels", BCP 14, RFC 2119, March 1997. 366 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 367 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 369 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 370 6749, October 2012. 372 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 373 Threat Model and Security Considerations", RFC 6819, 374 January 2013. 376 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 377 Interchange Format", RFC 7159, March 2014. 379 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 380 Signature (JWS)", RFC 7515, May 2015. 382 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 383 RFC 7516, May 2015. 385 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May 386 2015. 388 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 389 (JWT)", RFC 7519, May 2015. 391 11.2. Informative References 393 [openid_ab] 394 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 395 C. Mortimore, "OpenID Connect Core 1.0", February 2014. 397 Authors' Addresses 399 Nat Sakimura (editor) 400 Nomura Research Institute 401 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 402 Chiyoda-ku, Tokyo 100-0005 403 Japan 405 Phone: +81-3-5533-2111 406 Email: n-sakimura@nri.co.jp 407 URI: http://nat.sakimura.org/ 409 John Bradley 410 Ping Identity 411 Casilla 177, Sucursal Talagante 412 Talagante, RM 413 Chile 415 Phone: +44 20 8133 3718 416 Email: ve7jtb@ve7jtb.com 417 URI: http://www.thread-safe.com/