idnits 2.17.1 draft-ietf-oauth-jwsreq-09.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 28, 2016) is 2739 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: 5 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: April 1, 2017 Ping Identity 6 September 28, 2016 8 The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request 9 (JAR) 10 draft-ietf-oauth-jwsreq-09 12 Abstract 14 The authorization request in OAuth 2.0 described in RFC 6749 utilizes 15 query parameter serialization, which means that Authorization Request 16 parameters are encoded in the URI of the request and sent through 17 user agents such as web browsers. While it is easy to implement, it 18 means that (a) the communication through the user agents are not 19 integrity protected and thus the parameters can be tainted, and (b) 20 the source of the communication is not authenticated. Because of 21 these weaknesses, several attacks to the protocol have now been put 22 forward. 24 This document introduces the ability to send request parameters in a 25 JSON Web Token (JWT) instead, which allows the request to be JWS 26 signed and/or JWE encrypted so that the integrity, source 27 authentication and confidentiallity property of the Authorization 28 Request is attained. The request can be sent by value or by 29 reference. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on April 1, 2017. 48 Copyright Notice 50 Copyright (c) 2016 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 67 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.1. Request Object . . . . . . . . . . . . . . . . . . . . . 6 69 2.2. Request Object URI . . . . . . . . . . . . . . . . . . . 6 70 3. Symbols and abbreviated terms . . . . . . . . . . . . . . . . 6 71 4. Request Object . . . . . . . . . . . . . . . . . . . . . . . 6 72 5. Authorization Request . . . . . . . . . . . . . . . . . . . . 8 73 5.1. Passing a Request Object by Value . . . . . . . . . . . . 9 74 5.2. Passing a Request Object by Reference . . . . . . . . . . 10 75 5.2.1. URL Referencing the Request Object . . . . . . . . . 12 76 5.2.2. Request using the "request_uri" Request Parameter . . 13 77 5.2.3. Authorization Server Fetches Request Object . . . . . 13 78 6. Validating JWT-Based Requests . . . . . . . . . . . . . . . . 13 79 6.1. Encrypted Request Object . . . . . . . . . . . . . . . . 13 80 6.2. JWS Signed Request Object . . . . . . . . . . . . . . . . 14 81 6.3. Request Parameter Assembly and Validation . . . . . . . . 14 82 7. Authorization Server Response . . . . . . . . . . . . . . . . 14 83 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . 14 84 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 15 85 10. Security Considerations . . . . . . . . . . . . . . . . . . . 15 86 10.1. Choice of Algorithms . . . . . . . . . . . . . . . . . . 15 87 10.2. Choice of Parameters to include in the Request Object . 15 88 10.3. Request Source Authentication . . . . . . . . . . . . . 15 89 10.4. Explicit Endpoints . . . . . . . . . . . . . . . . . . . 16 90 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 16 91 11.1. Collection limitation . . . . . . . . . . . . . . . . . 17 92 11.2. Disclosure Limitation . . . . . . . . . . . . . . . . . 17 93 11.2.1. Request Disclosure . . . . . . . . . . . . . . . . . 17 94 11.2.2. Tracking using Request Object URI . . . . . . . . . 18 95 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 96 13. Revision History . . . . . . . . . . . . . . . . . . . . . . 18 97 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 98 14.1. Normative References . . . . . . . . . . . . . . . . . . 21 99 14.2. Informative References . . . . . . . . . . . . . . . . . 22 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 102 1. Introduction 104 The Authorization Request in OAuth 2.0 [RFC6749] utilizes query 105 parameter serialization and typically sent through user agents such 106 as web browsers. 108 For example, the parameters "response_type", "client_id", "state", 109 and "redirect_uri" are encoded in the URI of the request: 111 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 112 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 113 Host: server.example.com 115 While it is easy to implement, the encoding in the URI does not allow 116 application layer security with confidentiality and integrity 117 protection to be used. While TLS is used to offer communication 118 security between the Client and the user-agent and the user-agent and 119 the Authorization Server, TLS sessions are terminated in the user- 120 agent. In addition, TLS sessions may be terminated prematurely at 121 some middlebox (such as a load balancer). 123 As the result, the Authorization Request of [RFC6749] has a property 124 that 126 (a) the communication through the user agents are not integrity 127 protected and thus the parameters can be tainted (integrity 128 protection failure); 130 (b) the source of the communication is not authenticated (source 131 authentication failure); and 133 (c) the communication through the user agents can be monitored 134 (containment / confidentiality failure). 136 Because of these weaknesses, several attacks against the protocol, 137 such as Redirection URI rewriting, has been discovered. 139 The use of application layer security mitigates these issues. 141 In addition, it allows requests to be prepared by a third party so 142 that a client application cannot request more permissions than 143 previously agreed. This offers an additional degree of privacy 144 protection. 146 Furthermore, the request by reference allows the reduction of over- 147 the- wire overhead. 149 The JWT [RFC7519] encoding has been chosen because of 151 (1) its close relationship with JSON, which is used as OAuth's 152 response format; 154 (2) its developer friendliness due to its textual nature; 156 (3) its relative compactness compared to XML; 158 (4) its development status that it is an RFC and so is its 159 associated signing and encryption methods as [RFC7515] and 160 [RFC7516]; 162 (5) relative ease of JWS and JWE compared to XML Signature and 163 Encryption. 165 The parameters "request" and "request_uri" are introduced as 166 additional authorization request parameters for the OAuth 2.0 167 [RFC6749] flows. The "request" parameter is a JSON Web Token (JWT) 168 [RFC7519] whose JWT Claims Set holds the JSON encoded OAuth 2.0 169 authorization request parameters. This JWT is integrity protected 170 and source authenticated using JWS. 172 The JWT [RFC7519] can be passed to the authorization endpoint by 173 reference, in which case the parameter "request_uri" is used instead 174 of the "request". 176 Using JWT [RFC7519] as the request encoding instead of query 177 parameters has several advantages: 179 (a) (integrity protection) The request can be signed so that the 180 integrity of the request can be checked ; 182 (b) (source authentication) The request can be signed so that the 183 signer can be authenticated ; 185 (c) (confidentiality protection) The request can be encrypted so 186 that end-to-end confidentiality can be provided even if the TLS 187 connection is terminated at one point or another ; and 189 (d) (collection minimization) The request can be signed by a third 190 party attesting that the authorization request is compliant to 191 certain policy. For example, a request can be pre-examined by a 192 third party that all the personal data requested is strictly 193 necessary to perform the process that the end-user asked for, 194 and statically signed by that third party. The client would 195 then send the request along with dynamic parameters such as 196 state. The authorization server then examines the signature and 197 shows the conformance status to the end-user, who would have 198 some assurance as to the legitimacy of the request when 199 authorizing it. In some cases, it may even be desirable to skip 200 the authorization dialogue under such circumstances. 202 There are a few cases that request by reference are useful such as: 204 1. When it is desirable to reduce the size of transmitted request. 205 The use of application layer security increases the size of the 206 request, particularly when public key cryptography is used. 208 2. The client can make a signed Request Object and put it at a place 209 that the Authorization Server can access. This may just be done 210 by a client utility or other process, so that the private key 211 does not have to reside on the client, simplifying programming. 212 Downside of it is that the signed portion just become a token. 214 3. When the server wants the requests to be cacheable: The 215 "request_uri" may include a SHA-256 hash of the contents of the 216 resources referenced by the Request Object URI. With this, the 217 server knows if the resource has changed without fetching it, so 218 it does not have to re-fetch the same content, which is a win as 219 well. This is explained in Section 5.2. 221 4. When the client does not want to do the crypto: The Authorization 222 Server may provide an endpoint to accept the Authorization 223 Request through direct communication with the Client so that the 224 Client is authenticated and the channel is TLS protected. 226 This capability is in use by OpenID Connect [OpenID.Core]. 228 1.1. Requirements Language 230 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 231 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 232 document are to be interpreted as described in RFC 2119 [RFC2119]. 234 2. Terminology 236 For the purposes of this specification, the following terms and 237 definitions in addition to what is defined in OAuth 2.0 Framework 239 [RFC6749], JSON Web Signature [RFC7515], and JSON Web Encryption 240 [RFC7519] apply. 242 2.1. Request Object 244 JWT [RFC7519] that holds an OAuth 2.0 authorization request as JWT 245 Claims Set 247 2.2. Request Object URI 249 Absolute URI from which the Request Object (Section 2.1) can be 250 obtained 252 3. Symbols and abbreviated terms 254 The following abbreviations are common to this specification. 256 JSON Javascript Object Notation 258 JWT JSON Web Token 260 JWS JSON Web Signature 262 JWE JSON Web Encryption 264 URI Uniform Resource Identifier 266 URL Uniform Resource Locator 268 WAP Wireless Application Protocol 270 4. Request Object 272 A Request Object (Section 2.1) is used to provide authorization 273 request parameters for an OAuth 2.0 authorization request. It 274 contains OAuth 2.0 [RFC6749] authorization request parameters 275 including extension parameters. The parameters are represented as 276 the JWT claims. Parameter names and string values MUST be included 277 as JSON strings. Since it is a JWT, JSON strings MUST be represented 278 in UTF-8. Numerical values MUST be included as JSON numbers. It MAY 279 include any extension parameters. This JSON [RFC7159] constitutes 280 the JWT Claims Set [RFC7519]. The JWS Claims Set is then signed, 281 encrypted, or signed and encrypted. 283 To sign, JSON Web Signature (JWS) [RFC7515] is used. The result is a 284 JWS signed JWT [RFC7519]. If signed, the Authorization Request 285 Object SHOULD contain the Claims "iss" (issuer) and "aud" (audience) 286 as members, with their semantics being the same as defined in the JWT 287 [RFC7519] specification. 289 To encrypt, JWE [RFC7516] is used. Unless the algorithm used in JWE 290 allows for the source to be authenticated, JWS signature should also 291 be applied. In this case, it MUST be signed then encrypted, with the 292 result being a Nested JWT, as defined in JWT [RFC7519]. 294 The Authorization Request Object may be sent by value as described in 295 Section 5.1 or by reference as described in Section 5.2. 297 Required OAuth 2.0 Authorization Request parameters that are not 298 included in the Request Object MUST be sent as query parameters. If 299 a required parameter is missing from both the query parameters and 300 the Request Object, the request is malformed. 302 "request" and "request_uri" parameters MUST NOT be included in 303 Request Objects. 305 If the parameter exists in both the query string and the 306 Authorization Request Object, the values in the Request Object take 307 precedence. This means that if it intends to use a cached request 308 object, it cannot include parameters such as "state" that are 309 expected to differ in every request. It is fine to include them in 310 the request object if it is going to be prepared afresh every time. 312 The following is a non-normative example of the Claims in a Request 313 Object before base64url encoding and signing. Note that it includes 314 extension variables such as "nonce" and "max_age". 316 { 317 "iss": "s6BhdRkqt3", 318 "aud": "https://server.example.com", 319 "response_type": "code id_token", 320 "client_id": "s6BhdRkqt3", 321 "redirect_uri": "https://client.example.org/cb", 322 "scope": "openid", 323 "state": "af0ifjsldkj", 324 "nonce": "n-0S6_WzA2Mj", 325 "max_age": 86400 326 } 328 Signing it with the "RS256" algorithm results in this Request Object 329 value (with line wraps within values for display purposes only): 331 eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3 332 F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQogInJl 333 c3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNk 334 JoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1w 335 bGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiAic3RhdGUiOiAiYWYwaW 336 Zqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWoiLA0KICJtYXhfYWdlIjog 337 ODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXNlcmluZm8iOiANCiAgICB7DQ 338 ogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgIm5p 339 Y2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjogeyJlc3NlbnRpYWwiOiB0cnVlfS 340 wNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAg 341 ICAgInBpY3R1cmUiOiBudWxsDQogICAgfSwNCiAgICJpZF90b2tlbiI6IA0KICAgIH 342 sNCiAgICAgImdlbmRlciI6IG51bGwsDQogICAgICJiaXJ0aGRhdGUiOiB7ImVzc2Vu 343 dGlhbCI6IHRydWV9LA0KICAgICAiYWNyIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOm 344 luY29tbW9uOmlhcDpzaWx2ZXIiXX0NCiAgICB9DQogIH0NCn0.nwwnNsk1-Zkbmnvs 345 F6zTHm8CHERFMGQPhos-EJcaH4Hh-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyF 346 KzuMXZFSZ3p6Mb8dkxtVyjoy2GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx 347 0GxFbuPbj96tVuj11pTnmFCUR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8K 348 ol-cSLWoYE9l5QqholImzjT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPG 349 iyon_-Te111V8uE83IlzCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw 351 The following RSA public key, represented in JWK format, can be used 352 to validate the Request Object signature in this and subsequent 353 Request Object examples (with line wraps within values for display 354 purposes only): 356 { 357 "kty":"RSA", 358 "kid":"k2bdc", 359 "n":"y9Lqv4fCp6Ei-u2-ZCKq83YvbFEk6JMs_pSj76eMkddWRuWX2aBKGHAtKlE5P 360 7_vn__PCKZWePt3vGkB6ePgzAFu08NmKemwE5bQI0e6kIChtt_6KzT5OaaXDF 361 I6qCLJmk51Cc4VYFaxgqevMncYrzaW_50mZ1yGSFIQzLYP8bijAHGVjdEFgZa 362 ZEN9lsn_GdWLaJpHrB3ROlS50E45wxrlg9xMncVb8qDPuXZarvghLL0HzOuYR 363 adBJVoWZowDNTpKpk2RklZ7QaBO7XDv3uR7s_sf2g-bAjSYxYUGsqkNA9b3xV 364 W53am_UZZ3tZbFTIh557JICWKHlWj5uzeJXaw", 365 "e":"AQAB" 366 } 368 5. Authorization Request 370 The client constructs the authorization request URI by adding one of 371 the following parameters but not both to the query component of the 372 authorization endpoint URI using the "application/x-www-form- 373 urlencoded" format: 375 request The Request Object (Section 2.1) that holds authorization 376 request parameters stated in the section 4 of OAuth 2.0 [RFC6749]. 378 request_uri The absolute URL that points to the Request Object 379 (Section 2.1) that holds authorization request parameters stated 380 in the section 4 of OAuth 2.0 [RFC6749]. 382 The client directs the resource owner to the constructed URI using an 383 HTTP redirection response, or by other means available to it via the 384 user-agent. 386 For example, the client directs the end-user's user-agent to make the 387 following HTTPS request: 389 GET /authz?request=eyJhbG..AlMGzw HTTP/1.1 390 Host: server.example.com 392 The value for the request parameter is abbreviated for brevity. 394 The authorization request object MUST be either 396 (a) JWS signed; or 398 (b) JWE encrypted; or 400 (c) JWS signed and JWE encrypted. 402 When the Request Object is used, the OAuth 2.0 request parameter 403 values contained in the JWS Signed and/or JWE Encrypted JWT supersede 404 those passed using the OAuth 2.0 request syntax. Parameters MAY also 405 be passed using the OAuth 2.0 request syntax even when a Request 406 Object is used in the cases such as (a) to achieve backward 407 compatibility with [RFC6749] or (b) to enable a cached, pre-signed 408 (and possibly pre-encrypted) Request Object value to be used 409 containing the fixed request parameters, while parameters that can 410 vary with each request, such as "state" and "nonce" of OpenID 411 Connect, are passed as OAuth 2.0 parameters. In such case, one needs 412 to carefully assess the risk associated with it as unprotected 413 parameters would create additional attack surfaces. See Section 10.2 414 as well. 416 5.1. Passing a Request Object by Value 418 The Client sends the Authorization Request as a Request Object to the 419 Authorization Endpoint as the "request" parameter value. 421 The following is a non-normative example of an Authorization Request 422 using the "request" parameter (with line wraps within values for 423 display purposes only): 425 https://server.example.com/authorize? 426 request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiA 427 iczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmN 428 vbSIsDQogInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWV 429 udF9pZCI6ICJzNkJoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8 430 vY2xpZW50LmV4YW1wbGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiA 431 ic3RhdGUiOiAiYWYwaWZqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWo 432 iLA0KICJtYXhfYWdlIjogODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXN 433 lcmluZm8iOiANCiAgICB7DQogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWw 434 iOiB0cnVlfSwNCiAgICAgIm5pY2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjo 435 geyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJ 436 lc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgInBpY3R1cmUiOiBudWxsDQogICAgfSw 437 NCiAgICJpZF90b2tlbiI6IA0KICAgIHsNCiAgICAgImdlbmRlciI6IG51bGwsDQo 438 gICAgICJiaXJ0aGRhdGUiOiB7ImVzc2VudGlhbCI6IHRydWV9LA0KICAgICAiYWN 439 yIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOmluY29tbW9uOmlhcDpzaWx2ZXIiXX0 440 NCiAgICB9DQogIH0NCn0.nwwnNsk1-ZkbmnvsF6zTHm8CHERFMGQPhos-EJcaH4H 441 h-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyFKzuMXZFSZ3p6Mb8dkxtVyjoy2 442 GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx0GxFbuPbj96tVuj11pTnmFC 443 UR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8Kol-cSLWoYE9l5QqholImz 444 jT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPGiyon_-Te111V8uE83Il 445 zCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw 447 5.2. Passing a Request Object by Reference 449 The "request_uri" Authorization Request parameter enables OAuth 450 authorization requests to be passed by reference, rather than by 451 value. This parameter is used identically to the "request" 452 parameter, other than that the Request Object value is retrieved from 453 the resource at the specified URL, rather than passed by value. 455 When the "request_uri" parameter is used, the OAuth 2.0 authorization 456 request parameter values contained in the referenced JWT supersede 457 those passed using the OAuth 2.0 request syntax. Parameters MAY also 458 be passed using the OAuth 2.0 request syntax even when a Request 459 Object is used in the cases such as (a) to achieve backward 460 compatibility with [RFC6749] or (b) to enable a cached, pre-signed 461 (and possibly pre-encrypted) Request Object value to be used 462 containing the fixed request parameters, while parameters that can 463 vary with each request, such as "state" and "nonce" of OpenID 464 Connect, are passed as OAuth 2.0 parameters. In such case, one needs 465 to carefully assess the risk associated with it as unprotected 466 parameters would create additional attack surfaces. See Section 10.2 467 as well. 469 Servers MAY cache the contents of the resources referenced by Request 470 Object URIs. If the contents of the referenced resource could ever 471 change, the URI SHOULD include the base64url encoded SHA-256 hash as 472 defined in RFC6234 [RFC6234] of the referenced resource contents as 473 the fragment component of the URI. If the fragment value used for a 474 URI changes, it signals the server that any cached value for that URI 475 with the old fragment value is no longer valid. 477 The entire Request URI MUST NOT exceed 512 ASCII characters. There 478 are three reasons for this restriction. 480 1. Many WAP / feature phones do not accept large payloads. The 481 restriction are typically either 512 or 1024 ASCII characters. 483 2. The maximum URL length supported by older versions of Internet 484 Explorer is 2083 ASCII characters. 486 3. On a slow connection such as 2G mobile connection, a large URL 487 would cause the slow response and using such is not advisable 488 from the user experience point of view. 490 The contents of the resource referenced by the URL MUST be a Request 491 Object. The scheme used in the "request_uri" value MUST be "https", 492 unless the target Request Object is signed in a way that is 493 verifiable by the Authorization Server. The "request_uri" value MUST 494 be reachable by the Authorization Server, and SHOULD be reachable by 495 the Client. 497 The following is a non-normative example of the contents of a Request 498 Object resource that can be referenced by a "request_uri" (with line 499 wraps within values for display purposes only): 501 eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa3 502 F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQogInJl 503 c3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNk 504 JoZFJrcXQzIiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1w 505 bGUub3JnL2NiIiwNCiAic2NvcGUiOiAib3BlbmlkIiwNCiAic3RhdGUiOiAiYWYwaW 506 Zqc2xka2oiLA0KICJub25jZSI6ICJuLTBTNl9XekEyTWoiLA0KICJtYXhfYWdlIjog 507 ODY0MDAsDQogImNsYWltcyI6IA0KICB7DQogICAidXNlcmluZm8iOiANCiAgICB7DQ 508 ogICAgICJnaXZlbl9uYW1lIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAgICAgIm5p 509 Y2tuYW1lIjogbnVsbCwNCiAgICAgImVtYWlsIjogeyJlc3NlbnRpYWwiOiB0cnVlfS 510 wNCiAgICAgImVtYWlsX3ZlcmlmaWVkIjogeyJlc3NlbnRpYWwiOiB0cnVlfSwNCiAg 511 ICAgInBpY3R1cmUiOiBudWxsDQogICAgfSwNCiAgICJpZF90b2tlbiI6IA0KICAgIH 512 sNCiAgICAgImdlbmRlciI6IG51bGwsDQogICAgICJiaXJ0aGRhdGUiOiB7ImVzc2Vu 513 dGlhbCI6IHRydWV9LA0KICAgICAiYWNyIjogeyJ2YWx1ZXMiOiBbInVybjptYWNlOm 514 luY29tbW9uOmlhcDpzaWx2ZXIiXX0NCiAgICB9DQogIH0NCn0.nwwnNsk1-Zkbmnvs 515 F6zTHm8CHERFMGQPhos-EJcaH4Hh-sMgk8ePrGhw_trPYs8KQxsn6R9Emo_wHwajyF 516 KzuMXZFSZ3p6Mb8dkxtVyjoy2GIzvuJT_u7PkY2t8QU9hjBcHs68PkgjDVTrG1uRTx 517 0GxFbuPbj96tVuj11pTnmFCUR6IEOXKYr7iGOCRB3btfJhM0_AKQUfqKnRlrRscc8K 518 ol-cSLWoYE9l5QqholImzjT_cMnNIznW9E7CDyWXTsO70xnB4SkG6pXfLSjLLlxmPG 519 iyon_-Te111V8uE83IlzCYIb_NMXvtTIVc1jpspnTSD7xMbpL-2QgwUsAlMGzw 521 5.2.1. URL Referencing the Request Object 523 The Client stores the Request Object resource either locally or 524 remotely at a URL the Authorization Server can access. The URL MUST 525 be HTTPS URL. This URL is the Request Object URI, "request_uri". 527 It is possible for the Request Object to include values that is to be 528 revealed only to the Authorization Server. As such, the 529 "request_uri" MUST have appropriate entropy for its lifetime. It is 530 RECOMMENDED that it be removed if it is known that it will not be 531 used again or after a reasonable timeout unless access control 532 measures are taken. 534 Unless the access to the "request_uri" over TLS provides adequate 535 authentication of the source of the Request Object, the Request 536 Object MUST be JWS Signed. 538 The following is a non-normative example of a Request Object URI 539 value (with line wraps within values for display purposes only): 541 https://client.example.org/request.jwt# 542 GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM 544 5.2.2. Request using the "request_uri" Request Parameter 546 The Client sends the Authorization Request to the Authorization 547 Endpoint. 549 The following is a non-normative example of an Authorization Request 550 using the "request_uri" parameter (with line wraps within values for 551 display purposes only): 553 https://server.example.com/authorize? 554 response_type=code%20id_token 555 &client_id=s6BhdRkqt3 556 &request_uri=https%3A%2F%2Fclient.example.org%2Frequest.jwt 557 %23GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM 558 &state=af0ifjsldkj 560 5.2.3. Authorization Server Fetches Request Object 562 Upon receipt of the Request, the Authorization Server MUST send an 563 HTTP "GET" request to the "request_uri" to retrieve the referenced 564 Request Object, unless it is already cached, and parse it to recreate 565 the Authorization Request parameters. 567 Note that the client SHOULD use a unique URI for each request 568 containing distinct parameters values, or otherwise prevent the 569 Authorization Server from caching the "request_uri". 571 The following is a non-normative example of this fetch process: 573 GET /request.jwt HTTP/1.1 574 Host: client.example.org 576 6. Validating JWT-Based Requests 578 6.1. Encrypted Request Object 580 The Authorization Server MUST decrypt the JWT in accordance with the 581 JSON Web Encryption [RFC7516] specification. If the result is a 582 signed request object, signature validation MUST be performed as 583 defined in Section 6.2 as well. 585 If decryption fails, the Authorization Server MUST return 586 "invalid_request_object" error. 588 6.2. JWS Signed Request Object 590 To perform JWS Signature Validation, the "alg" Header Parameter in 591 the JOSE Header MUST match the value of the pre-registered algorithm. 592 The signature MUST be validated against the appropriate key for that 593 "client_id" and algorithm. 595 If signature validation fails, the Authorization Server MUST return 596 "invalid_request_object" error. 598 6.3. Request Parameter Assembly and Validation 600 The Authorization Server MUST assemble the set of Authorization 601 Request parameters to be used from the Request Object value and the 602 OAuth 2.0 Authorization Request parameters (minus the "request" or 603 "request_uri" parameters). If the same parameter exists both in the 604 Request Object and the OAuth Authorization Request parameters, the 605 parameter in the Request Object is used. Using the assembled set of 606 Authorization Request parameters, the Authorization Server then 607 validates the request as specified in OAuth 2.0 [RFC6749]. 609 7. Authorization Server Response 611 Authorization Server Response is created and sent to the client as in 612 Section 4 of OAuth 2.0 [RFC6749] . 614 In addition, this document uses these additional error values: 616 invalid_request_uri The "request_uri" in the Authorization Request 617 returns an error or contains invalid data. 619 invalid_request_object The request parameter contains an invalid 620 Request Object. 622 request_not_supported The Authorization Server does not support the 623 use of the "request" parameter. 625 request_uri_not_supported The Authorization Server does not support 626 use of the "request_uri" parameter. 628 8. TLS Requirements 630 Client implementations supporting the Request Object URI method MUST 631 support TLS as recommended in Recommendations for Secure Use of 632 Transport Layer Security (TLS) and Datagram Transport Layer Security 633 (DTLS) [RFC7525]. 635 To protect against information disclosure and tampering, 636 confidentiality protection MUST be applied using TLS with a 637 ciphersuite that provides confidentiality and integrity protection. 639 Whenever TLS is used, the identity of the service provider encoded in 640 the TLS server certificate MUST be verified using the procedures 641 described in Section 6 of [RFC6125]. 643 9. IANA Considerations 645 This specification requests no actions by IANA. 647 10. Security Considerations 649 In addition to the all the security considerations discussed in OAuth 650 2.0 [RFC6819], the following security considerations should be taken 651 into account. 653 10.1. Choice of Algorithms 655 When sending the authorization request object through "request" 656 parameter, it MUST either be JWS signed with then considered 657 appropriate algorithm or encrypted using [RFC7516]. 659 10.2. Choice of Parameters to include in the Request Object 661 Unless there is a compelling reasons to do otherwise, it is strongly 662 recommended to create a request object that covers all the parameters 663 so that the entire request is integrity protected. 665 This means that the request object is going to be prepared fresh each 666 time an authorization request is made and caching cannot be used. It 667 has a performance disadvantage, but where such disadvantage is 668 permissible, it should be considered. 670 Unless the server and the client have agreed prior to the 671 authorization request to use the non-protected parameters, the 672 authorization server SHOULD reject a request that is not fully 673 integrity protected and source authenticated. 675 10.3. Request Source Authentication 677 The source of the Authorization Request MUST always be verified. 678 There are several ways to do it in this specification. 680 (a) Verifying the JWS Signature of the Request Object. 682 (b) Verifying the TLS Server Identity of the Request Object URI. In 683 this case, the Authorization Server MUST know out of band that 684 the Client uses Request Object URI and only the Client is 685 covered by the TLS certificate. In general, it is not a 686 reliable method. 688 (c) Authorization Server is providing an endpoint that provides a 689 Request Object URI in exchange for a Request Object. In this 690 case, the Authorization Server MUST perform Client 691 Authentication to accept the Request Object and bind the Client 692 Identifier to the Request Object URI it is providing. Since 693 Request Object URI can be replayed, the lifetime of the Request 694 Object URI MUST be short and preferably one-time use. The 695 entropy of the Request Object URI MUST be sufficiently large. 697 (d) A third party, such as a Trust Framework Provider, provides an 698 endpoint that provides a Request Object URI in exchange for a 699 Request Object. The same requirements as (b) above applies. In 700 addition, the Authorization Server MUST know out-of-band that 701 the Client utilizes the Trust Framework Operator. 703 10.4. Explicit Endpoints 705 Although this specification does not require them, researchs such as 706 [BASIN] points out that it is a good practice to explicitly state the 707 intended interaction endpoints and the message position in the 708 sequence in a tamper evident manner so that the intent of the 709 initiator is unambiguous. The endpoints that comes into question in 710 this specification are 712 (a) Protected Resources ("protected_resources"); 714 (b) Authorization Endpoint ("authorization_endpoint"); 716 (c) Redirection URI ("redirect_uri"); and 718 (d) Token Endpoint ("token_endpoint"). 720 While Redirection URI is included, others are not included in the 721 Authorization Request Object. It is probably a good idea to include 722 these in it to reduce the attack surface. An extension specification 723 should be created. 725 11. Privacy Considerations 727 When the Client is being granted access to a protected resource 728 containing personal data, both the Client and the Authorization 729 Server need to adhere to Privacy Principles. ISO/IEC 29100 731 [ISO29100] is a freely accessible International Standard and its 732 Privacy Principles are good to follow. 734 Most of the provision would apply to The OAuth 2.0 Authorization 735 Framework [RFC6749] and The OAuth 2.0 Authorization Framework: Bearer 736 Token Usage [RFC6750] and not specific to this specification. In 737 what follows, only the specific provisions to this specification are 738 noted. 740 11.1. Collection limitation 742 When the Client is being granted access to a protected resource 743 containing personal data, the Client SHOULD limit the collection of 744 personal data to that which is within the bounds of applicable law 745 and strictly necessary for the specified purpose(s). 747 It is often hard for the user to find out if the personal data asked 748 for is strictly necessary. A Trust Framework Provider can help the 749 user by examining the Client request and comparing to the proposed 750 processing by the Client and certifying the request. After the 751 certification, the Client, when making an Authorization Request, can 752 submit Authorization Request to the Trust Framework Provider to 753 obtain the Request Object URI. 755 Upon receiving such Request Object URI in the Authorization Request, 756 the Authorization Server first verifies that the authority portion of 757 the Request Object URI is a legitimate one for the Trust Framework 758 Provider. Then, the Auhtorization Server issues HTTP GET request to 759 the Request Object URI. Upon connecting, the Authorization Server 760 MUST verify the server identity represented in the TLS certificate is 761 legitimate for the Request Object URI. Then, the Authorization 762 Server can obtain the Request Object, which includes the "client_id" 763 representing the Client. 765 The Consent screen MUST indicate the Client and SHOULD indicate that 766 the request has been vetted by the Trust Framework Operator for the 767 adherence to the Collection Limitation principle. 769 11.2. Disclosure Limitation 771 11.2.1. Request Disclosure 773 This specification allows extension parameters. These may include 774 potentially sensitive information. Since URI query parameter may 775 leak through various means but most notably through referrer and 776 browser history, if the authorization request contains potentially 777 sensitive parameter, the Client SHOULD JWE [RFC7516] encrypt the 778 request object. 780 Where Request Object URI method is being used, if the request object 781 contains personally identifiable or sensitive information, the 782 "request_uri" SHOULD be of one-time use and MUST have large enough 783 entropy deemed necessary with applicable security policy unless the 784 Request Object itself is JWE [RFC7516] Encrypted. 786 11.2.2. Tracking using Request Object URI 788 Even if the protected resource does not include a personally 789 identifiable information, it is sometimes possible to identify the 790 user through the Request Object URI if persistent per-user Request 791 Object URI is used. A third party may observe it through browser 792 history etc. and start correlating the user's activity using it. It 793 is in a way a data disclosure as well and should be avoided. 795 Therefore, per-user Request Object URI should be avoided. 797 12. Acknowledgements 799 The following people contributed to the creation of this document in 800 the OAuth WG. (Affiliations at the time of the contribution is 801 used.) 803 Sergey Beryozkin, Brian Campbell (Ping Identity), Vladimir Dzhuvinov 804 (Connect2id), Michael B. Jones (Microsoft), Torsten Lodderstedt 805 (Deutche Telecom) Jim Manico, Axel Nenker(Deutche Telecom), Hannes 806 Tschofenig (ARM). 808 The following people contributed to creating this document through 809 the OpenID Connect Core 1.0 [OpenID.Core]. 811 Brian Campbell (Ping Identity), George Fletcher (AOL), Ryo Itou 812 (Mixi), Edmund Jay (Illumila), Michael B. Jones (Microsoft), Breno 813 de Medeiros (Google), Hideki Nara (TACT), Justin Richer (MITRE). 815 In addition, the following people contributed to this and previous 816 versions through the OAuth Working Group. 818 Dirk Balfanz (Google), James H. Manger (Telstra), John Panzer 819 (Google), David Recordon (Facebook), Marius Scurtescu (Google), Luke 820 Shepard (Facebook). 822 13. Revision History 824 -09 826 o Minor Editorial Nits. 828 o Section 10.4 added. 830 o Explicit reference to Security consideration (10.2) added in 831 section 5 and section 5.2. 833 o , (add yourself) removed from the acknowledgement. 835 -08 837 o Applied changes proposed by Hannes on 2016-06-29 on IETF OAuth 838 list recorded as https://bitbucket.org/Nat/oauth-jwsreq/ 839 issues/12/. 841 o TLS requirements added. 843 o Security Consideration reinforced. 845 o Privacy Consideration added. 847 o Introduction improved. 849 -07 851 o Changed the abbrev to OAuth JAR from oauth-jar. 853 o Clarified sig and enc methods. 855 o Better English. 857 o Removed claims from one of the example. 859 o Re-worded the URI construction. 861 o Changed the example to use request instead of request_uri. 863 o Clarified that Request Object parameters takes precedence 864 regardless of request or request_uri parameters were used. 866 o Generalized the language in 4.2.1 to convey the intent more 867 clearly. 869 o Changed "Server" to "Authorization Server" as a clarification. 871 o Stopped talking about request_object_signing_alg. 873 o IANA considerations now reflect the current status. 875 o Added Brian Campbell to the contributors list. Made the lists 876 alphabetic order based on the last names. Clarified that the 877 affiliation is at the time of the contribution. 879 o Added "older versions of " to the reference to IE uri length 880 limitations. 882 o Stopped talking about signed or unsigned JWS etc. 884 o 1.Introduction improved. 886 -06 888 o Added explanation on the 512 chars URL restriction. 890 o Updated Acknowledgements. 892 -05 894 o More alignment with OpenID Connect. 896 -04 898 o Fixed typos in examples. (request_url -> request_uri, cliend_id -> 899 client_id) 901 o Aligned the error messages with the OAuth IANA registry. 903 o Added another rationale for having request object. 905 -03 907 o Fixed the non-normative description about the advantage of static 908 signature. 910 o Changed the requirement for the parameter values in the request 911 itself and the request object from 'MUST MATCH" to 'Req Obj takes 912 precedence. 914 -02 916 o Now that they are RFCs, replaced JWS, JWE, etc. with RFC numbers. 918 -01 920 o Copy Edits. 922 14. References 924 14.1. Normative References 926 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 927 Requirement Levels", BCP 14, RFC 2119, 928 DOI 10.17487/RFC2119, March 1997, 929 . 931 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 932 Verification of Domain-Based Application Service Identity 933 within Internet Public Key Infrastructure Using X.509 934 (PKIX) Certificates in the Context of Transport Layer 935 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 936 2011, . 938 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 939 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 940 DOI 10.17487/RFC6234, May 2011, 941 . 943 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 944 RFC 6749, DOI 10.17487/RFC6749, October 2012, 945 . 947 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 948 Framework: Bearer Token Usage", RFC 6750, 949 DOI 10.17487/RFC6750, October 2012, 950 . 952 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 953 Threat Model and Security Considerations", RFC 6819, 954 DOI 10.17487/RFC6819, January 2013, 955 . 957 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 958 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 959 2014, . 961 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 962 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 963 2015, . 965 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 966 RFC 7516, DOI 10.17487/RFC7516, May 2015, 967 . 969 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 970 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 971 . 973 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 974 "Recommendations for Secure Use of Transport Layer 975 Security (TLS) and Datagram Transport Layer Security 976 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 977 2015, . 979 14.2. Informative References 981 [BASIN] Basin, D., Cremers, C., and S. Meier, "Provably Repairing 982 the ISO/IEC 9798 Standard for Entity Authentication", 983 Journal of Computer Security - Security and Trust 984 Principles Volume 21 Issue 6, Pages 817-846, November 985 2013, 986 . 989 [ISO29100] 990 "ISO/IEC 29100 Information technology - Security 991 techniques - Privacy framework", December 2011, 992 . 995 [OpenID.Core] 996 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 997 C. Mortimore, "OpenID Connect Core 1.0", OpenID 998 Foundation Standards, February 2014, 999 . 1001 Authors' Addresses 1003 Nat Sakimura 1004 Nomura Research Institute 1005 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 1006 Chiyoda-ku, Tokyo 100-0005 1007 Japan 1009 Phone: +81-3-5533-2111 1010 Email: n-sakimura@nri.co.jp 1011 URI: http://nat.sakimura.org/ 1012 John Bradley 1013 Ping Identity 1014 Casilla 177, Sucursal Talagante 1015 Talagante, RM 1016 Chile 1018 Phone: +44 20 8133 3718 1019 Email: ve7jtb@ve7jtb.com 1020 URI: http://www.thread-safe.com/