idnits 2.17.1 draft-ietf-oauth-jwsreq-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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC6749]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 2, 2016) is 2823 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) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6234 ** Downref: Normative reference to an Informational RFC: RFC 6819 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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 J. Bradley 5 Expires: February 3, 2017 Ping Identity 6 August 2, 2016 8 OAuth 2.0 JWT Authorization Request (JAR) 9 draft-ietf-oauth-jwsreq-08 11 Abstract 13 The authorization request in OAuth 2.0 [RFC6749] utilizes query 14 parameter serialization, which means that Authorization Request 15 parameters are encoded in the URI of the request and sent through 16 user agents such as web browsers. While it is easy to implement, it 17 means that (a) the communication through the user agents are not 18 integrity protected and thus the parameters can be tainted, and (b) 19 the source of the communication is not authentciated. Because of 20 these weaknesses, several attacks to the protocol have now been put 21 forward. 23 This document introduces the ability to send request parameters in a 24 JSON Web Token (JWT) instead, which allows the request to be JWS 25 signed and/or JWE encrypted so that the integrity, source 26 authentication and confidentiallity property of the Authorization 27 Request is attained. The request can be sent by value or by 28 reference. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on February 3, 2017. 47 Copyright Notice 49 Copyright (c) 2016 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 2.1. Request Object . . . . . . . . . . . . . . . . . . . . . 6 68 2.2. Request Object URI . . . . . . . . . . . . . . . . . . . 6 69 3. Symbols and abbreviated terms . . . . . . . . . . . . . . . . 6 70 4. Request Object . . . . . . . . . . . . . . . . . . . . . . . 6 71 5. Authorization Request . . . . . . . . . . . . . . . . . . . . 8 72 5.1. Passing a Request Object by Value . . . . . . . . . . . . 9 73 5.2. Passing a Request Object by Reference . . . . . . . . . . 10 74 5.2.1. URL Referencing the Request Object . . . . . . . . . 12 75 5.2.2. Request using the "request_uri" Request Parameter . . 12 76 5.2.3. Authorization Server Fetches Request Object . . . . . 12 77 6. Validating JWT-Based Requests . . . . . . . . . . . . . . . . 13 78 6.1. Encrypted Request Object . . . . . . . . . . . . . . . . 13 79 6.2. JWS Signed Request Object . . . . . . . . . . . . . . . . 13 80 6.3. Request Parameter Assembly and Validation . . . . . . . . 13 81 7. Authorization Server Response . . . . . . . . . . . . . . . . 13 82 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . 14 83 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 14 84 10. Security Considerations . . . . . . . . . . . . . . . . . . . 14 85 10.1. Choice of Algorithms . . . . . . . . . . . . . . . . . . 14 86 10.2. Choice of Parameters to include in the Request Object . 14 87 10.3. Request Source Authentication . . . . . . . . . . . . . 15 88 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 89 11.1. Collection limitation . . . . . . . . . . . . . . . . . 16 90 11.2. Disclosure Limitation . . . . . . . . . . . . . . . . . 16 91 11.2.1. Request Disclosure . . . . . . . . . . . . . . . . . 16 92 11.2.2. Tracking using Request Object URI . . . . . . . . . 17 93 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 94 13. Revision History . . . . . . . . . . . . . . . . . . . . . . 17 95 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 96 14.1. Normative References . . . . . . . . . . . . . . . . . . 19 97 14.2. Informative References . . . . . . . . . . . . . . . . . 20 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 100 1. Introduction 102 The Authorization Request in OAuth 2.0 [RFC6749] utilizes query 103 parameter serialization and typically sent through user agents such 104 as web browsers. 106 For example, the parameters 'response_type', 'client_id', 'state', 107 and 'redirect_uri' are encoded in the URI of the request: 109 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 110 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 111 Host: server.example.com 113 While it is easy to implement, the encoding in the URI does not allow 114 application layer security with confidentiality and integrity 115 protection to be used. While TLS is used to offer communication 116 security between the Client and the user-agent and the user-agent and 117 the Authorization Server, TLS sessions are terminated in the user- 118 agent. In addition, TLS sessions are terminated prematurely at some 119 middlebox (such as a load balancer). 121 As the result, the Authorization Request of [RFC6749] has a property 122 that 124 (a) the communication through the user agents are not integrity 125 protected and thus the parameters can be tainted (integrity 126 protection failure); 128 (b) the source of the communication is not authentciated (source 129 authentication failure); and 131 (c) the communication through the user agents can be monitored 132 (containment failure). 134 Because of these weaknesses, several attacks to the protocol such as 135 Redirection URI rewrite has been put forward by now. 137 The use of application layer security mitigates these issues. 139 In addition, it allows requests to be prepared by a third party so 140 that a client application cannot request more permissions than 141 previously agreed. This offers an additional degree of privacy 142 protection. 144 Further, the request by reference allows the reduction of over-the- 145 wire overhead. 147 There are other potential formats that could be used for this purpose 148 instead of JWT [RFC7519]. The JWT was chosen because of 150 (1) its close relationship with JSON, which is used as OAuth's 151 response format; 153 (2) its developer friendliness due to its textual nature; 155 (3) its relative compactness compared to XML; 157 (4) its development status that it is an RFC and so is its 158 associated signing and encryption methods as [RFC7515] and 159 [RFC7516]; 161 (5) relative ease of JWS and JWE compared to XML Signature and 162 Encryption. 164 The parameters "request" and "request_uri" are introduced as 165 additional authorization request parameters for the OAuth 2.0 166 [RFC6749] flows. The "request" parameter is a JSON Web Token (JWT) 167 [RFC7519] whose JWT Claims Set holds the JSON encoded OAuth 2.0 168 authorization request parameters. This JWT is integrity protected 169 and source authenticated using JWS. 171 The JWT [RFC7519] can be passed to the authorization endpoint by 172 reference, in which case the parameter "request_uri" is used instead 173 of the "request". 175 Using JWT [RFC7519] as the request encoding instead of query 176 parameters has several advantages: 178 (a) (integrity protection) The request can be signed so that the 179 integrity of the request can be checked ; 181 (b) (source authentication) The request can be signed so that the 182 signer can be authenticated ; 184 (c) (containment) The request can be encrypted so that end-to-end 185 confidentiality can be provided even if the TLS connection is 186 terminated at one point or another ; and 188 (d) (collection minimization) The request can be signed by a third 189 party attesting that the authorization request is compliant to 190 certain policy. For example, a request can be pre-examined by a 191 third party that all the personal data requested is strictly 192 necessary to perform the process that the end-user asked for, 193 and statically signed by that third party. The client would 194 then send the request along with dynamic parameters such as 195 state. The authorization server then examines the signature and 196 shows the conformance status to the end-user, who would have 197 some assurance as to the legitimacy of the request when 198 authorizing it. In some cases, it may even be desirable to skip 199 the authorization dialogue under such circumstances. 201 There are a few cases that request by reference are useful such as: 203 1. When it is desirable to reduce the size of transmitted request. 204 The use of application layer security increases the size of the 205 request, particularly when public key cryptography is used. 207 2. The client can make a signed Request Object and put it at a place 208 that the Authorization Server can access. This may just be done 209 by a client utility or other process, so that the private key 210 does not have to reside on the client, simplifying programming. 211 Downside of it is that the signed portion just become a token. 213 3. When the server wants the requests to be cacheable: The 214 request_uri may include a SHA-256 hash of the contents of the 215 resources referenced by the Request Object URI. With this, the 216 server knows if the resource has changed without fetching it, so 217 it does not have to re-fetch the same content, which is a win as 218 well. This is explained in Section 5.2. 220 4. When the client does not want to do the crypto: The Authorization 221 Server may provide an endpoint to accept the Authorization 222 Request through direct communication with the Client so that the 223 Client is authentcicated and the channel is TLS protected. 225 This capability is in use by OpenID Connect [OpenID.Core]. 227 1.1. Requirements Language 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 231 document are to be interpreted as described in RFC 2119 [RFC2119]. 233 2. Terminology 235 For the purposes of this specification, the following terms and 236 definitions in addition to what is defined in OAuth 2.0 Framework 237 [RFC6749], JSON Web Signature [RFC7515], and JSON Web Encryption 238 [RFC7519] apply. 240 2.1. Request Object 242 JWT [RFC7519] that holds an OAuth 2.0 authorization request as JWT 243 Claims Set 245 2.2. Request Object URI 247 Absolute URI from which the Request Object (Section 2.1) can be 248 obtained 250 3. Symbols and abbreviated terms 252 The following abbreviations are common to this specification. 254 JSON Javascript Object Notation 256 JWT JSON Web Token 258 JWS JSON Web Signature 260 JWE JSON Web Encryption 262 URI Uniform Resource Identifier 264 URL Uniform Resource Locator 266 WAP Wireless Application Protocol 268 4. Request Object 270 A Request Object (Section 2.1) is used to provide authorization 271 request parameters for an OAuth 2.0 authorization request. It 272 contains OAuth 2.0 [RFC6749] authorization request parameters 273 including extension parameters. The parameters are represented as 274 the JWT claims. Parameter names and string values MUST be included 275 as JSON strings. Since it is a JWT, JSON strings MUST be represented 276 in UTF-8. Numerical values MUST be included as JSON numbers. It MAY 277 include any extension parameters. This JSON [RFC7159] constitutes 278 the JWT Claims Set [RFC7519]. The JWS Claims Set is then signed, 279 encrypted, or signed and encrypted. 281 To sign, JSON Web Signature (JWS) [RFC7515] is used. The result is a 282 JWS signed JWT [RFC7519]. If signed, the Authorization Request 283 Object SHOULD contain the Claims "iss" (issuer) and "aud" (audience) 284 as members, with their semantics being the same as defined in the JWT 285 [RFC7519] specification. 287 To encrypt, JWE [RFC7516] is used. Unless the algorithm used in JWE 288 allows for the source to be authenticated, JWS signature should also 289 be applied. In this case, it MUST be signed then encrypted, with the 290 result being a Nested JWT, as defined in JWT [RFC7519]. 292 The Authorization Request Object may be sent by value as described in 293 Section 5.1 or by reference as described in Section 5.2. 295 Required OAuth 2.0 Authorization Request parameters that are not 296 included in the Request Object MUST be sent as query parameters. If 297 a required parameter is missing from both the query parameters and 298 the Request Object, the request is malformed. 300 "request" and "request_uri" parameters MUST NOT be included in 301 Request Objects. 303 If the parameter exists in both the query string and the 304 Authorization Request Object, the values in the Request Object take 305 precedence. This means that if it intends to use a cached request 306 object, it cannot include parameters such as "state" that are 307 expected to differ in every request. It is fine to include them in 308 the request object if it is going to be prepared afresh every time. 310 The following is a non-normative example of the Claims in a Request 311 Object before base64url encoding and signing. Note that it includes 312 extension variables such as "nonce" and "max_age". 314 { 315 "iss": "s6BhdRkqt3", 316 "aud": "https://server.example.com", 317 "response_type": "code id_token", 318 "client_id": "s6BhdRkqt3", 319 "redirect_uri": "https://client.example.org/cb", 320 "scope": "openid", 321 "state": "af0ifjsldkj", 322 "nonce": "n-0S6_WzA2Mj", 323 "max_age": 86400 324 } 326 Signing it with the "RS256" algorithm results in this Request Object 327 value (with line wraps within values for display purposes only): 329 eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3 330 F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQogInJl 331 c3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNk 332 JoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1w 333 bGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiAic3RhdGUiOiAiYWYwaW 334 Zqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWoiLA0KICJtYXhfYWdlIjog 335 ODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXNlcmluZm8iOiANCiAgICB7DQ 336 ogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgIm5p 337 Y2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjogeyJlc3NlbnRpYWwiOiB0cnVlfS 338 wNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAg 339 ICAgInBpY3R1cmUiOiBudWxsDQogICAgfSwNCiAgICJpZF90b2tlbiI6IA0KICAgIH 340 sNCiAgICAgImdlbmRlciI6IG51bGwsDQogICAgICJiaXJ0aGRhdGUiOiB7ImVzc2Vu 341 dGlhbCI6IHRydWV9LA0KICAgICAiYWNyIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOm 342 luY29tbW9uOmlhcDpzaWx2ZXIiXX0NCiAgICB9DQogIH0NCn0.nwwnNsk1-Zkbmnvs 343 F6zTHm8CHERFMGQPhos-EJcaH4Hh-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyF 344 KzuMXZFSZ3p6Mb8dkxtVyjoy2GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx 345 0GxFbuPbj96tVuj11pTnmFCUR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8K 346 ol-cSLWoYE9l5QqholImzjT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPG 347 iyon_-Te111V8uE83IlzCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw 349 The following RSA public key, represented in JWK format, can be used 350 to validate the Request Object signature in this and subsequent 351 Request Object examples (with line wraps within values for display 352 purposes only): 354 { 355 "kty":"RSA", 356 "kid":"k2bdc", 357 "n":"y9Lqv4fCp6Ei-u2-ZCKq83YvbFEk6JMs_pSj76eMkddWRuWX2aBKGHAtKlE5P 358 7_vn__PCKZWePt3vGkB6ePgzAFu08NmKemwE5bQI0e6kIChtt_6KzT5OaaXDF 359 I6qCLJmk51Cc4VYFaxgqevMncYrzaW_50mZ1yGSFIQzLYP8bijAHGVjdEFgZa 360 ZEN9lsn_GdWLaJpHrB3ROlS50E45wxrlg9xMncVb8qDPuXZarvghLL0HzOuYR 361 adBJVoWZowDNTpKpk2RklZ7QaBO7XDv3uR7s_sf2g-bAjSYxYUGsqkNA9b3xV 362 W53am_UZZ3tZbFTIh557JICWKHlWj5uzeJXaw", 363 "e":"AQAB" 364 } 366 5. Authorization Request 368 The client constructs the authorization request URI by adding one of 369 the following parameters but not both to the query component of the 370 authorization endpoint URI using the "application/x-www-form- 371 urlencoded" format: 373 request The Request Object (Section 4) that holds authorization 374 request parameters stated in the section 4 of OAuth 2.0 [RFC6749]. 376 request_uri The absolute URL that points to the Request Object 377 (Section 4) that holds authorization request parameters stated in 378 the section 4 of OAuth 2.0 [RFC6749]. 380 The client directs the resource owner to the constructed URI using an 381 HTTP redirection response, or by other means available to it via the 382 user-agent. 384 For example, the client directs the end-user's user-agent to make the 385 following HTTPS request: 387 GET /authz?request=eyJhbG..AlMGzw HTTP/1.1 388 Host: server.example.com 390 The value for the request parameter is abbreviated for brevity. 392 The authorization request object MUST be either 394 (a) JWS signed; or 396 (b) JWE encrypted; or 398 (c) JWS signed and JWE encrypted. 400 When the Request Object is used, the OAuth 2.0 request parameter 401 values contained in the JWS Signed and/or JWE Encrypted JWT supersede 402 those passed using the OAuth 2.0 request syntax. However, parameters 403 MAY also be passed using the OAuth 2.0 request syntax even when a 404 Request Object is used; this would typically be done to enable a 405 cached, pre-signed (and possibly pre-encrypted) Request Object value 406 to be used containing the fixed request parameters, while parameters 407 that can vary with each request, such as "state" and "nonce" of 408 OpenID Connect, are passed as OAuth 2.0 parameters. 410 5.1. Passing a Request Object by Value 412 The Client sends the Authorization Request as a Request Object to the 413 Authorization Endpoint as the "request" parameter value. 415 The following is a non-normative example of an Authorization Request 416 using the "request" parameter (with line wraps within values for 417 display purposes only): 419 https://server.example.com/authorize? 420 request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiA 421 iczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmN 422 vbSIsDQogInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWV 423 udF9pZCI6ICJzNkJoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8 424 vY2xpZW50LmV4YW1wbGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiA 425 ic3RhdGUiOiAiYWYwaWZqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWo 426 iLA0KICJtYXhfYWdlIjogODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXN 427 lcmluZm8iOiANCiAgICB7DQogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWw 428 iOiB0cnVlfSwNCiAgICAgIm5pY2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjo 429 geyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJ 430 lc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgInBpY3R1cmUiOiBudWxsDQogICAgfSw 431 NCiAgICJpZF90b2tlbiI6IA0KICAgIHsNCiAgICAgImdlbmRlciI6IG51bGwsDQo 432 gICAgICJiaXJ0aGRhdGUiOiB7ImVzc2VudGlhbCI6IHRydWV9LA0KICAgICAiYWN 433 yIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOmluY29tbW9uOmlhcDpzaWx2ZXIiXX0 434 NCiAgICB9DQogIH0NCn0.nwwnNsk1-ZkbmnvsF6zTHm8CHERFMGQPhos-EJcaH4H 435 h-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyFKzuMXZFSZ3p6Mb8dkxtVyjoy2 436 GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx0GxFbuPbj96tVuj11pTnmFC 437 UR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8Kol-cSLWoYE9l5QqholImz 438 jT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPGiyon_-Te111V8uE83Il 439 zCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw 441 5.2. Passing a Request Object by Reference 443 The "request_uri" Authorization Request parameter enables OAuth 444 authorization requests to be passed by reference, rather than by 445 value. This parameter is used identically to the "request" 446 parameter, other than that the Request Object value is retrieved from 447 the resource at the specified URL, rather than passed by value. 449 When the "request_uri" parameter is used, the OAuth 2.0 authorization 450 request parameter values contained in the referenced JWT supersede 451 those passed using the OAuth 2.0 request syntax. However, parameters 452 MAY also be passed using the OAuth 2.0 request syntax even when a 453 "request_uri" is used; this would typically be done to enable a 454 cached, pre-signed (and possibly pre-encrypted) Request Object value 455 to be used containing the fixed request parameters, while parameters 456 that can vary with each request, such as "state" and "nonce", are 457 passed as OAuth 2.0 parameters. 459 Servers MAY cache the contents of the resources referenced by Request 460 Object URIs. If the contents of the referenced resource could ever 461 change, the URI SHOULD include the base64url encoded SHA-256 hash as 462 defined in RFC6234 [RFC6234] of the referenced resource contents as 463 the fragment component of the URI. If the fragment value used for a 464 URI changes, that signals the server that any cached value for that 465 URI with the old fragment value is no longer valid. 467 The entire Request URI MUST NOT exceed 512 ASCII characters. There 468 are three reasons for this restriction. 470 1. Many WAP / feature phones do not accept large payloads. The 471 restriction are typically either 512 or 1024 ASCII characters. 473 2. The maximum URL length supported by older versions of Internet 474 Explorer is 2083 ASCII characters. 476 3. On a slow connection such as 2G mobile connection, a large URL 477 would cause the slow response and using such is not advisable 478 from the user experience point of view. 480 The contents of the resource referenced by the URL MUST be a Request 481 Object. The scheme used in the "request_uri" value MUST be "https", 482 unless the target Request Object is signed in a way that is 483 verifiable by the Authorization Server. The "request_uri" value MUST 484 be reachable by the Authorization Server, and SHOULD be reachable by 485 the Client. 487 The following is a non-normative example of the contents of a Request 488 Object resource that can be referenced by a "request_uri" (with line 489 wraps within values for display purposes only): 491 eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3 492 F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQogInJl 493 c3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNk 494 JoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1w 495 bGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiAic3RhdGUiOiAiYWYwaW 496 Zqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWoiLA0KICJtYXhfYWdlIjog 497 ODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXNlcmluZm8iOiANCiAgICB7DQ 498 ogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgIm5p 499 Y2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjogeyJlc3NlbnRpYWwiOiB0cnVlfS 500 wNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAg 501 ICAgInBpY3R1cmUiOiBudWxsDQogICAgfSwNCiAgICJpZF90b2tlbiI6IA0KICAgIH 502 sNCiAgICAgImdlbmRlciI6IG51bGwsDQogICAgICJiaXJ0aGRhdGUiOiB7ImVzc2Vu 503 dGlhbCI6IHRydWV9LA0KICAgICAiYWNyIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOm 504 luY29tbW9uOmlhcDpzaWx2ZXIiXX0NCiAgICB9DQogIH0NCn0.nwwnNsk1-Zkbmnvs 505 F6zTHm8CHERFMGQPhos-EJcaH4Hh-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyF 506 KzuMXZFSZ3p6Mb8dkxtVyjoy2GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx 507 0GxFbuPbj96tVuj11pTnmFCUR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8K 508 ol-cSLWoYE9l5QqholImzjT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPG 509 iyon_-Te111V8uE83IlzCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw 511 5.2.1. URL Referencing the Request Object 513 The Client stores the Request Object resource either locally or 514 remotely at a URL the Authorization Server can access. The URL MUST 515 be HTTPS URL. This URL is the Request Object URI, "request_uri". 517 It is possible for the Request Object to include values that is to be 518 revealed only to the Authorization Server. As such, the 519 "request_uri" MUST have appropriate entropy for its lifetime. It is 520 RECOMMENDED that it be removed if it is known that it will not be 521 used again or after a reasonable timeout unless access control 522 measures are taken. 524 Unless the access to the "request_uri" over TLS provides adequate 525 authentciation of the source of the Request Object, the Request 526 Object MUST be JWS Signed. 528 The following is a non-normative example of a Request Object URI 529 value (with line wraps within values for display purposes only): 531 https://client.example.org/request.jwt# 532 GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM 534 5.2.2. Request using the "request_uri" Request Parameter 536 The Client sends the Authorization Request to the Authorization 537 Endpoint. 539 The following is a non-normative example of an Authorization Request 540 using the "request_uri" parameter (with line wraps within values for 541 display purposes only): 543 https://server.example.com/authorize? 544 response_type=code%20id_token 545 &client_id=s6BhdRkqt3 546 &request_uri=https%3A%2F%2Fclient.example.org%2Frequest.jwt 547 %23GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM 548 &state=af0ifjsldkj 550 5.2.3. Authorization Server Fetches Request Object 552 Upon receipt of the Request, the Authorization Server MUST send an 553 HTTP "GET" request to the "request_uri" to retrieve the referenced 554 Request Object, unless it is already cached, and parse it to recreate 555 the Authorization Request parameters. 557 Note that the client SHOULD use a unique URI for each request 558 containing distinct parameters values, or otherwise prevent the 559 Authorization Server from caching the "request_uri". 561 The following is a non-normative example of this fetch process: 563 GET /request.jwt HTTP/1.1 564 Host: client.example.org 566 6. Validating JWT-Based Requests 568 6.1. Encrypted Request Object 570 The Authorization Server MUST decrypt the JWT in accordance with the 571 JSON Web Encryption [RFC7516] specification. If the result is a 572 signed request object, signature validation MUST be performed as 573 defined in Section 6.2 as well. 575 If decryption fails, the Authorization Server MUST return 576 "invalid_request_object" error. 578 6.2. JWS Signed Request Object 580 To perform JWS Signature Validation, the "alg" Header Parameter in 581 the JOSE Header MUST match the value of the pre-registered algorithm. 582 The signature MUST be validated against the appropriate key for that 583 "client_id" and algorithm. 585 If signature validation fails, the Authorization Server MUST return 586 "invalid_request_object" error. 588 6.3. Request Parameter Assembly and Validation 590 The Authorization Server MUST assemble the set of Authorization 591 Request parameters to be used from the Request Object value and the 592 OAuth 2.0 Authorization Request parameters (minus the "request" or 593 "request_uri" parameters). If the same parameter exists both in the 594 Request Object and the OAuth Authorization Request parameters, the 595 parameter in the Request Object is used. Using the assembled set of 596 Authorization Request parameters, the Authorization Server then 597 validates the request as specified in OAuth 2.0 [RFC6749]. 599 7. Authorization Server Response 601 Authorization Server Response is created and sent to the client as in 602 Section 4 of OAuth 2.0 [RFC6749] . 604 In addition, this document uses these additional error values: 606 invalid_request_uri The "request_uri" in the Authorization Request 607 returns an error or contains invalid data. 609 invalid_request_object The request parameter contains an invalid 610 Request Object. 612 request_not_supported The Authorization Server does not support the 613 use of the "request" parameter. 615 request_uri_not_supported The Authorization Server does not support 616 use of the "request_uri" parameter. 618 8. TLS Requirements 620 Client implementations supporting the Request Object URI method MUST 621 support TLS as recommended in Recommendations for Secure Use of 622 Transport Layer Security (TLS) and Datagram Transport Layer Security 623 (DTLS) [RFC7525]. 625 To protect against information disclosure and tampering, 626 confidentiality protection MUST be applied using TLS with a 627 ciphersuite that provides confidentiality and integrity protection. 629 Whenever TLS is used, the identity of the service provider encoded in 630 the TLS server certificate MUST be verified using the procedures 631 described in Section 6 of [RFC6125]. 633 9. IANA Considerations 635 This specification requests no actions by IANA. 637 10. Security Considerations 639 In addition to the all the security considerations discussed in OAuth 640 2.0 [RFC6819], the following security considerations should be taken 641 into account. 643 10.1. Choice of Algorithms 645 When sending the authorization request object through "request" 646 parameter, it MUST either be JWS signed with then considered 647 appropriate algorithm or encrypted using [RFC7516]. 649 10.2. Choice of Parameters to include in the Request Object 651 Unless there is a compelling reasons to do otherwise, it is strongly 652 recommended to create a request object that covers all the parameters 653 so that the entire request is integrity protected. 655 This means that the request object is going to be prepared fresh each 656 time an authorization request is made and cacheing cannot be used. 657 It has a performance disadvantage, but where such disadvantage is 658 permissible, it should be considered. 660 Unless the server and the client have agreed prior to the 661 authorization request to use the non-protected parameters, the 662 authorization server SHOULD reject a request that is not fully 663 integrity protected and source authenticated. 665 10.3. Request Source Authentication 667 The source of the Authorization Request MUST always be verified. 668 There are several ways to do it in this sepcification. 670 (a) Verifying the JWS Signature of the Request Object. 672 (b) Verifying the TLS Server Identity of the Request Object URI. In 673 this case, the Authorization Server MUST know out of band that 674 the Client uses Request Object URI and only the Client is 675 covered by the TLS certificate. In general, it is not a 676 reliable method. 678 (c) Authorization Server is providing an endpoint that provides a 679 Request Object URI in exchange for a Request Object. In this 680 case, the Authorization Server MUST peform Client Authentication 681 to accept the Request Object and bind the Client Identifier to 682 the Request Object URI it is providing. Since Request Object 683 URI can be replayed, the lifetime of the Request Object URI MUST 684 be short and preferably one-time use. The entropy of the 685 Request Object URI MUST be sufficiently large. 687 (d) A third party, such as a Trust Framework Provider, provides an 688 endpoint that provides a Request Object URI in exchange for a 689 Request Object. The same requirements as (b) above applies. In 690 addition, the Authorization Server MUST know out-of-band that 691 the Client utilizes the Trust Framework Operator. 693 11. Privacy Considerations 695 When the Client is being granted access to a protected resource 696 containing personal data, both the Client and the Authorization 697 Server need to adhere to Privacy Principles. ISO/IEC 29100 698 [ISO29100] is a freely accessible International Standard and its 699 Privacy Principles are good to follow. 701 Most of the provision would apply to The OAuth 2.0 Authorization 702 Framework [RFC6749] and The OAuth 2.0 Authorization Framework: Bearer 703 Token Usage [RFC6750] and not specific to this specification. In 704 what follows, only the specific provisions to this specification are 705 noted. 707 11.1. Collection limitation 709 When the Client is being granted access to a protected resource 710 containing personal data, the Client SHOULD limit the collection of 711 personal data to that which is within the bounds of applicable law 712 and strictly necessary for the specified purpose(s). 714 It is often hard for the user to find out if the personal data asked 715 for is strictly necessary. A Trust Framework Provider can help the 716 user by examining the Client request and comparing to the proposed 717 processing by the Client and certifying the request. After the 718 certification, the Client, when making an Authorization Request, can 719 submit Authorization Request to the Trust Framework Provider to 720 obtain the Request Object URI. 722 Upon receiving such Request Object URI in the Authorization Request, 723 the Authorization Server first verifies that the authority portion of 724 the Request Object URI is a legitimate one for the Trust Framework 725 Provider. Then, the Auhtorization Server issues HTTP GET request to 726 the Request Object URI. Uppon connecting, the Authorization Server 727 MUST verify the server identity represented in the TLS certificate is 728 legitimate for the Request Object URI. Then, the Authorization 729 Server can obtain the Request Object, which includes the "client_id" 730 representing the Client. 732 The Consent screen MUST indicate the Client and SHOULD indicate that 733 the request has been vetted by the Trust Framework Operator for the 734 adherance to the Collection Limitation principle. 736 11.2. Disclosure Limitation 738 11.2.1. Request Disclosure 740 This specification allows extension parameters. These may include 741 potentially sensitive information. Since URI query parameter may 742 leak through various means but most notably through referrer and 743 browser history, if the authorization request contains poteintially 744 sensitive parameter, the Client SHOULD JWE [RFC7516] encrypt the 745 request object. 747 Where Request Object URI method is being used, if the request object 748 contains personally identifiable or sensitive information, the 749 "request_uri" SHOULD be of one-time use and MUST have large enough 750 entropy deemed necessary with applicable security policy unless the 751 Request Object itself is JWE [RFC7516] Encrypted. 753 11.2.2. Tracking using Request Object URI 755 Even if the protected resource does not include a personally 756 identifiable information, it is sometimes possible to identify the 757 user through the Request Object URI if persistent per-user Request 758 Object URI is used. A third party may observe it through borwser 759 history etc. and start corrilating the user's activity using it. It 760 is in a way a data disclosure as well and should be avoided. 762 Therefore, per-user Request Object URI should be avoided. 764 12. Acknowledgements 766 Follwoing people contributed to the creation of this document in 767 OAuth WG. (Affiliations at the time of the contribution is used.) 769 Sergey Beryozkin, Brian Campbell (Ping Identity), Vladimir Dzhuvinov 770 (Connect2id), Michael B. Jones (Microsoft), Torsten Lodderstedt 771 (Deutche Telecom) Jim Manico, Axel Nenker(Deutche Telecom), Hannes 772 Tschofenig (ARM), (add yourself). 774 Following people contributed to creating this document through the 775 OpenID Connect Core 1.0 [OpenID.Core]. 777 Brian Campbell (Ping Identity), George Fletcher (AOL), Ryo Itou 778 (Mixi), Edmund Jay (Illumila), Michael B. Jones (Microsoft), Breno 779 de Medeiros (Google), Hideki Nara (TACT), Justin Richer (MITRE), (add 780 yourself). 782 In addition following people contributed to this and previous 783 versions through The OAuth Working Group. 785 Dirk Balfanz (Google), James H. Manger (Telstra), John Panzer 786 (Google), David Recordon (Facebook), Marius Scurtescu (Google), Luke 787 Shepard (Facebook). 789 13. Revision History 791 -08 793 o Applied changes proposed by Hannes on 2016-06-29 on IETF OAUth 794 list recorded as https://bitbucket.org/Nat/oauth-jwsreq/ 795 issues/12/. 797 o TLS requirements added. 799 o Security Consideration reinforced. 801 o Privacy Consideration added. 803 o Introduction improved. 805 -07 807 o Changed the abbrev to OAuth JAR from oauth-jar. 809 o Clarified sig and enc methods. 811 o Better English. 813 o Removed claims from one of the example. 815 o Re-worded the URI construction. 817 o Changed the example to use request instead of request_uri. 819 o Clarified that Request Object parameters takes precedence 820 regardless of request or request_uri parameters were used. 822 o Generalized the language in 4.2.1 to convey the intent more 823 clearly. 825 o Changed "Server" to "Authorization Server" as a clarification. 827 o Stopped talking about request_object_signing_alg. 829 o IANA considerations now reflect the current status. 831 o Added Brian Campbell to the contributers list. Made the lists 832 alphabetic order based on the last names. Clarified that the 833 affiliation is at the time of the contribution. 835 o Added "older versions of " to the reference to IE uri length 836 limitations. 838 o Stopped talking about signed or unsigned JWS etc. 840 o 1.Introduction improved. 842 -06 844 o Added explanation on the 512 chars URL restriction. 846 o Updated Acknowledgements. 848 -05 850 o More alignment with OpenID Connect. 852 -04 854 o Fixed typos in examples. (request_url -> request_uri, cliend_id -> 855 client_id) 857 o Aligned the error messages with the OAuth IANA registry. 859 o Added another rationale for having request object. 861 -03 863 o Fixed the non-normative description about the advantage of static 864 signature. 866 o Changed the requirement for the parameter values in the request 867 itself and the request object from 'MUST MATCH" to 'Req Obj takes 868 precedence. 870 -02 872 o Now that they are RFCs, replaced JWS, JWE, etc. with RFC numbers. 874 -01 876 o Copy Edits. 878 14. References 880 14.1. Normative References 882 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 883 Requirement Levels", BCP 14, RFC 2119, 884 DOI 10.17487/RFC2119, March 1997, 885 . 887 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 888 Verification of Domain-Based Application Service Identity 889 within Internet Public Key Infrastructure Using X.509 890 (PKIX) Certificates in the Context of Transport Layer 891 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 892 2011, . 894 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 895 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 896 DOI 10.17487/RFC6234, May 2011, 897 . 899 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 900 RFC 6749, DOI 10.17487/RFC6749, October 2012, 901 . 903 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 904 Framework: Bearer Token Usage", RFC 6750, 905 DOI 10.17487/RFC6750, October 2012, 906 . 908 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 909 Threat Model and Security Considerations", RFC 6819, 910 DOI 10.17487/RFC6819, January 2013, 911 . 913 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 914 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 915 2014, . 917 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 918 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 919 2015, . 921 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 922 RFC 7516, DOI 10.17487/RFC7516, May 2015, 923 . 925 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 926 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 927 . 929 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 930 "Recommendations for Secure Use of Transport Layer 931 Security (TLS) and Datagram Transport Layer Security 932 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 933 2015, . 935 14.2. Informative References 937 [ISO29100] 938 "ISO/IEC 29100 Information technology - Security 939 techniques - Privacy framework", December 2011, 940 . 943 [OpenID.Core] 944 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 945 C. Mortimore, "OpenID Connect Core 1.0", February 2014, 946 . 948 Authors' Addresses 950 Nat Sakimura 951 Nomura Research Institute 952 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 953 Chiyoda-ku, Tokyo 100-0005 954 Japan 956 Phone: +81-3-5533-2111 957 Email: n-sakimura@nri.co.jp 958 URI: http://nat.sakimura.org/ 960 John Bradley 961 Ping Identity 962 Casilla 177, Sucursal Talagante 963 Talagante, RM 964 Chile 966 Phone: +44 20 8133 3718 967 Email: ve7jtb@ve7jtb.com 968 URI: http://www.thread-safe.com/