idnits 2.17.1 draft-ietf-oauth-jwsreq-04.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 (July 06, 2015) is 3216 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: January 7, 2016 Ping Identity 6 July 06, 2015 8 Request by JWS ver.1.0 for OAuth 2.0 9 draft-ietf-oauth-jwsreq-04 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 January 7, 2016. 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 . . . . . . . . . . . . . . . . . . . . . . 7 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 at the place where the Authorization Server can access. 101 This may just be done by a client utility or other process, so 102 that the private key does not have to reside on the client, 103 simplifying programming. 105 3. When the server wants the requests to be cache-able: The 106 request_uri may include a sha256 hash of the file, as defined in 107 FIPS180-2 [FIPS180-2], the server knows if the file has changed 108 without fetching it, so it does not have to re-fetch a same file, 109 which is a win as well. 111 4. When the client wants to simplify the implementation without 112 compromising the security. If the request parameters go through 113 the Browser, they may be tampered in the browser even if TLS was 114 used. This implies we need to have signature on the request as 115 well. However, if HTTPS "request_uri" was used, it is not going 116 to be tampered, thus we now do not have to sign the request. 117 This simplifies the implementation. 119 This capability is in use by OpenID Connect [openid_ab]. 121 1.1. Requirements Language 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in RFC 2119 [RFC2119]. 127 2. Terminology 129 For the purposes of this specification, the following terms and 130 definitions apply. 132 2.1. Request Object 134 JWT [RFC7519] that holds OAuth 2.0 authorization requests as JWT 135 Claims Set 137 2.2. Request Object URI 139 Absolute URI from which the Request Object (Section 2.1) can be 140 obtained 142 3. Request Object 144 A Request Object (Section 2.1) is used to provide authorization 145 request parameters for OAuth 2.0 authorization request. It contains 146 OAuth 2.0 [RFC6749] authorization request parameters including 147 extension parameters. It is a JSON Web Signature (JWS) [RFC7515] 148 signed JWT [RFC7519] . The parameters are included as the top-level 149 members of JSON [RFC7159]. Parameter names and string values MUST be 150 included as JSON strings. Numerical values MUST be included as JSON 151 numbers. It MAY include any extension parameters. This JSON 152 [RFC7159] constitutes the JWT [RFC7519] Claims Set. 154 The Request Object MAY be signed or unsigned (plaintext). When it is 155 plaintext, this is indicated by use of the "none" algorithm JWA 156 [RFC7518] in the JWS header. If signed, the Authorization Request 157 Object SHOULD contain the Claims "iss" (issuer) and "aud" (audience) 158 as members, with their semantics being the same as defined in the JWT 159 [RFC7519] specification. 161 The Request Object MAY also be encrypted using JWE [RFC7516] after 162 signing, with nesting performed in the same manner as specified for 163 JWT [RFC7519]. The Authorization Request Object MAY alternatively be 164 sent by reference using "request_uri" parameter. 166 REQUIRED OAuth 2.0 Authorization Request parameters that are not 167 included in the Request Object MUST be sent as a query parameter. If 168 a required parameter is not present in neither the query parameter 169 nor the Request Object, it forms a malformed request. 171 If the parameter exists in both the query string and the 172 Authorization Request Object, the values in the Request Object takes 173 precedence. This means that if it intends to use a cached request 174 object, it cannot include such parameters like "state" that is 175 expected to differ in every request. It is fine to include them in 176 the request object if it is going to be prepared afresh every time. 178 Following is the example of the JSON that constitutes the [RFC7519] 179 Claims Set. 181 { 182 "redirect_url":"https://example.com/rp/endpoint_url", 183 "cliend_id":"http://example.com/rp/" 184 } 186 The following is a non-normative example of a [RFC7519] encoded 187 authorization request object. It includes extension variables such 188 as "nonce", "userinfo", and "id_token". Note that the line wraps 189 within the values are for display purpose only: 191 JWT algorithm = HS256 192 HMAC HASH Key = 'aaa' 194 JSON Encoded Header = "{"alg":"HS256","typ":"JWT"}" 195 JSON Encoded Payload = "{"response_type":"code id_token", 196 "client_id":"s6BhdRkqt3", 197 "redirect_uri":"https://client.example.com/cb", 198 "scope":"openid profile", 199 "state":"af0ifjsldkj", 200 "nonce":"n-0S6_WzA2Mj", 201 "userinfo":{"claims":{"name":null,"nickname":{"optional":true}, 202 "email":null,"verified":null, 203 "picture":{"optional":true}},"format":"signed"}, 204 "id_token":{"max_age":86400,"iso29115":"2"}}" 206 JWT = eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY29kZ 207 SBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiO 208 iJodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkI 209 HByb2ZpbGUiLCJzdGF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zI 210 jp7Im5hbWUiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfSwiZW1haWwiO 211 m51bGwsInZlcmlmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sI 212 mZvcm1hdCI6InNpZ25lZCJ9LCJpZF90b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvM 213 jkxMTUiOiIyIn19.2OiqRgrbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY 215 4. Request Object URI 217 Instead of sending the Request Object in an OAuth 2.0 authorization 218 request directly, this specification allows it to be obtained from 219 the Request Object URI. Using this method has an advantage of 220 reducing the request size, enabling the caching of the Request 221 Object, and generally not requiring integrity protection through a 222 cryptographic operation on the Request Object if the channel itself 223 is protected. 225 The Request Object URI is sent as a part of the OAuth Authorization 226 Request as the value for the parameter called "request_uri". How the 227 Request Object is registered at Request Object URI is out of scope of 228 this specification, but it MUST be done in a protected channel. 230 NOTE: the Request Object MAY be registered at the Authorization 231 Server at the client registration time. 233 When the Authorization Server obtains the Request Object from Request 234 Object URI, it MUST do so over a protected channel. If it is 235 obtained from a remote server, it SHOULD use either HTTP over TLS 1.2 236 as defined in [RFC5246] AND/OR [RFC7515] with the algorithm 237 considered appropriate at the time. 239 When sending the request by "request_uri", the client MAY provide the 240 sha256 hash as defined in FIPS180-2 [FIPS180-2]of the Request Object 241 as the fragment to it to assist the cache utilization decision of the 242 Authorization Server. 244 5. Authorization Request 246 The client constructs the authorization request URI by adding the 247 following parameters to the query component of the authorization 248 endpoint URI using the "application/x-www-form-urlencoded" format: 250 request REQUIRED unless "request_uri" is specified. The Request 251 Object (Section 3) that holds authorization request parameters 252 stated in the section 4 of OAuth 2.0 [RFC6749]. 254 request_uri REQUIRED unless "request" is specified. The absolute 255 URL that points to the Request Object (Section 3) that holds 256 authorization request parameters stated in the section 4 of OAuth 257 2.0 [RFC6749]. 259 state RECOMMENDED. OAuth 2.0 [RFC6749] state. 261 The client directs the resource owner to the constructed URI using an 262 HTTP redirection response, or by other means available to it via the 263 user-agent. 265 For example, the client directs the end-user's user-agent to make the 266 following HTTPS request (line breaks are for display purposes only): 268 GET /authorize?request_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 269 Host: server.example.com 271 The authorization request object MAY be signed AND/OR encrypted. 273 Upon receipt of "request_uri" in the request, the authorization 274 server MUST send a GET request to the "request_uri" to retrieve the 275 authorization request object unless it is already cached at the 276 Authorization Server. 278 If the response was signed AND/OR encrypted, it has to be decoded 279 accordingly before being processed. 281 Then, the Authorization Server MUST reconstruct the complete client 282 request from the original HTTP request and the content of the request 283 object. Then, the process continues as described in Section 3 of 284 OAuth 2.0 [RFC6749] . 286 6. Authorization Server Response 288 Authorization Server Response is created and sent to the client as in 289 Section 4 of OAuth 2.0 [RFC6749] . 291 In addition, this document defines additional 'error' values as 292 follows: 294 invalid_request_uri The provided request_uri was not available. 296 invalid_request_object The Request Object was invalid. 298 7. IANA Considerations 300 None. 302 8. Security Considerations 304 In addition to the all the security considerations discussed in OAuth 305 2.0 [RFC6819], the following security considerations SHOULD be taken 306 into account. 308 When sending the authorization request object through "request" 309 parameter, it SHOULD be signed with then considered appropriate 310 algorithm using [RFC7515]. The "alg=none" SHOULD NOT be used in such 311 a case. 313 If the request object contains personally identifiable or sensitive 314 information, the "request_uri" MUST be of one-time use and MUST have 315 large enough entropy deemed necessary with applicable security 316 policy. For higher security requirement, using [RFC7516] is strongly 317 recommended. 319 9. Acknowledgements 321 Following people contributed to creating this document through the 322 OpenID Connect 1.0 [openid_ab]. 324 Breno de Medeiros (Google), Hideki Nara (TACT), John Bradley ( Ping 325 Identity) , Nat Sakimura (NRI) , Ryo Itou 326 (Yahoo! Japan), George Fletcher (AOL), Justin Richer (MITRE), Edmund 327 Jay (Illumila), Michael B. Jones (Microsoft), (add yourself). 329 In addition following people contributed to this and previous 330 versions through The OAuth Working Group. 332 David Recordon (Facebook), Luke Shepard (Facebook), James H. Manger 333 (Telstra), Marius Scurtescu (Google), John Panzer (Google), Dirk 334 Balfanz (Google), (add yourself). 336 10. Revision History 338 -04 340 o Changed invalid_request_* to align with OpenID Connect. 342 o Removed entry in the IANA considerations. 344 -03 346 o Fixed the non-normative description about the advantage of static 347 signature. 349 o Changed the requement for the parameter values in the request 350 iteself and the request object from 'MUST MATCH" to 'Req Obj takes 351 precedence. 353 -02 355 o Now that they are RFCs, replaced JWS, JWE, etc. with RFC numbers. 357 -01 359 o Copy Edits. 361 11. References 363 11.1. Normative References 365 [FIPS180-2] 366 U.S. Department of Commerce and National Institute of 367 Standards and Technology, "Secure Hash Signature 368 Standard", FIPS 180-2, August 2002. 370 Defines Secure Hash Algorithm 256 (SHA256) 372 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 373 Requirement Levels", BCP 14, RFC 2119, March 1997. 375 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 376 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 378 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 379 6749, October 2012. 381 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 382 Threat Model and Security Considerations", RFC 6819, 383 January 2013. 385 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 386 Interchange Format", RFC 7159, March 2014. 388 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 389 Signature (JWS)", RFC 7515, May 2015. 391 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 392 RFC 7516, May 2015. 394 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May 395 2015. 397 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 398 (JWT)", RFC 7519, May 2015. 400 11.2. Informative References 402 [openid_ab] 403 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 404 C. Mortimore, "OpenID Connect Core 1.0", February 2014. 406 Authors' Addresses 408 Nat Sakimura (editor) 409 Nomura Research Institute 410 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 411 Chiyoda-ku, Tokyo 100-0005 412 Japan 414 Phone: +81-3-5533-2111 415 Email: n-sakimura@nri.co.jp 416 URI: http://nat.sakimura.org/ 418 John Bradley 419 Ping Identity 420 Casilla 177, Sucursal Talagante 421 Talagante, RM 422 Chile 424 Phone: +44 20 8133 3718 425 Email: ve7jtb@ve7jtb.com 426 URI: http://www.thread-safe.com/