idnits 2.17.1 draft-ietf-oauth-par-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 : ---------------------------------------------------------------------------- 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 (14 May 2021) is 1076 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) == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-18 == Outdated reference: A later version (-10) exists of draft-ietf-oauth-v2-1-02 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Authorization Protocol T. Lodderstedt 3 Internet-Draft yes.com 4 Intended status: Standards Track B. Campbell 5 Expires: 15 November 2021 Ping Identity 6 N. Sakimura 7 NAT.Consulting 8 D. Tonge 9 Moneyhub Financial Technology 10 F. Skokan 11 Auth0 12 14 May 2021 14 OAuth 2.0 Pushed Authorization Requests 15 draft-ietf-oauth-par-08 17 Abstract 19 This document defines the pushed authorization request endpoint, 20 which allows clients to push the payload of an OAuth 2.0 21 authorization request to the authorization server via a direct 22 request and provides them with a request URI that is used as 23 reference to the data in a subsequent call to the authorization 24 endpoint. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 15 November 2021. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Introductory Example . . . . . . . . . . . . . . . . . . 4 61 1.2. Conventions and Terminology . . . . . . . . . . . . . . . 5 62 2. Pushed Authorization Request Endpoint . . . . . . . . . . . . 5 63 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.2. Successful Response . . . . . . . . . . . . . . . . . . . 8 65 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 9 66 2.4. Management of Client Redirect URIs . . . . . . . . . . . 10 67 3. The "request" Request Parameter . . . . . . . . . . . . . . . 11 68 4. Authorization Request . . . . . . . . . . . . . . . . . . . . 13 69 5. Authorization Server Metadata . . . . . . . . . . . . . . . . 14 70 6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 15 71 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 72 7.1. Request URI Guessing . . . . . . . . . . . . . . . . . . 15 73 7.2. Open Redirection . . . . . . . . . . . . . . . . . . . . 15 74 7.3. Request Object Replay . . . . . . . . . . . . . . . . . . 16 75 7.4. Client Policy Change . . . . . . . . . . . . . . . . . . 16 76 7.5. Request URI Swapping . . . . . . . . . . . . . . . . . . 16 77 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 16 78 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 79 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 80 10.1. OAuth Authorization Server Metadata . . . . . . . . . . 17 81 10.2. OAuth Dynamic Client Registration Metadata . . . . . . . 17 82 10.3. OAuth URI Registration . . . . . . . . . . . . . . . . . 17 83 11. Normative References . . . . . . . . . . . . . . . . . . . . 18 84 12. Informative References . . . . . . . . . . . . . . . . . . . 18 85 Appendix A. Document History . . . . . . . . . . . . . . . . . . 20 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 88 1. Introduction 90 Pushed authorization requests (PAR), defined by this document, enable 91 OAuth [RFC6749] clients to push the payload of an authorization 92 request directly to the authorization server in exchange for a 93 request URI value, which is used as reference to the authorization 94 request payload data in a subsequent call to the authorization 95 endpoint via the user-agent. 97 In OAuth [RFC6749] authorization request parameters are typically 98 sent as URI query parameters via redirection in the user-agent. This 99 is simple but also yields challenges: 101 * There is no cryptographic integrity and authenticity protection. 102 An attacker could, for example, modify the scope of access 103 requested or swap the context of a payment transaction by changing 104 scope values. Although protocol facilities exist to enable 105 clients or users to detect some such changes, preventing 106 modifications early in the process is a more robust solution. 108 * There is no mechanism to ensure confidentiality of the request 109 parameters. Although HTTPS is required for the authorization 110 endpoint, the request data passes through the user-agent in the 111 clear and query string data can inadvertently leak to web server 112 logs and to other sites via referer. The impact of which can be 113 significant, if personal identifiable information or other 114 regulated data is sent in the authorization request (which might 115 well be the case in identity, open banking, and similar 116 scenarios). 118 * Authorization request URLs can become quite large, especially in 119 scenarios requiring fine-grained authorization data, which might 120 cause errors in request processing. 122 JWT Secured Authorization Request (JAR) [I-D.ietf-oauth-jwsreq] 123 provides solutions for the security challenges by allowing OAuth 124 clients to wrap authorization request parameters in a request object, 125 which is a signed and optionally encrypted JSON Web Token (JWT) 126 [RFC7519]. In order to cope with the size restrictions, JAR 127 introduces the "request_uri" parameter that allows clients to send a 128 reference to a request object instead of the request object itself. 130 This document complements JAR by providing an interoperable way to 131 push the payload of an authorization request directly to the 132 authorization server in exchange for a "request_uri" value usable at 133 the authorization server in a subsequent authorization request. 135 PAR fosters OAuth security by providing clients a simple means for a 136 confidential and integrity protected authorization request. Clients 137 requiring an even higher security level, especially cryptographically 138 confirmed non-repudiation, are able to use JWT-based request objects 139 as defined by [I-D.ietf-oauth-jwsreq] in conduction with a pushed 140 authorization request. 142 PAR allows the authorization server to authenticate the client before 143 any user interaction happens. The increased confidence in the 144 identity of the client during the authorization process allows the 145 authorization server to refuse illegitimate requests much earlier in 146 the process, which can prevent attempts to spoof clients or otherwise 147 tamper with or misuse an authorization request. 149 Note that HTTP "POST" requests to the authorization endpoint via the 150 user-agent, as described in Section 3.1 of [RFC6749] and 151 Section 3.1.2.1 of [OIDC], could also be used to cope with the 152 request size limitations described above. However, it's only 153 optional per [RFC6749] and, even when supported, it is a viable 154 option for traditional web applications but is prohibitively 155 difficult to use with mobile apps. Those apps typically invoke a 156 custom tab with an URL that is translated into a GET request. Using 157 "POST" would require the app to first open a web page under its 158 control in the custom tab that in turn would initiate the form "POST" 159 towards the authorization server. PAR is simpler to use and has 160 additional security benefits as described above. 162 1.1. Introductory Example 164 A client typically initiates an authorization request by directing 165 the user-agent to make an HTTP request like the following to the 166 authorization server's authorization endpoint (extra line breaks and 167 indentation for display purposes only): 169 GET /authorize?response_type=code 170 &client_id=s6BhdRkqt3&state=af0ifjsldkj 171 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 172 Host: as.example.com 174 Such a request could instead be pushed directly to the authorization 175 server by the client with a "POST" request to the pushed 176 authorization request endpoint as illustrated in the following 177 example (extra line breaks for display purposes only). The client 178 can authenticate (e.g., using the "Authorization" header as shown) 179 because the the request is made directly to the authorization server. 181 POST /as/par HTTP/1.1 182 Host: as.example.com 183 Content-Type: application/x-www-form-urlencoded 184 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 186 response_type=code 187 &client_id=s6BhdRkqt3&state=af0ifjsldkj 188 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 190 The authorization server responds with a request URI: 192 HTTP/1.1 201 Created 193 Cache-Control: no-cache, no-store 194 Content-Type: application/json 196 { 197 "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2", 198 "expires_in": 90 199 } 201 The client uses the request URI value to create the subsequent 202 authorization request by directing the user-agent to make an HTTP 203 request to the authorization server's authorization endpoint like the 204 following (extra line breaks and indentation for display purposes 205 only): 207 GET /authorize?client_id=s6BhdRkqt3 208 &request_uri=urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 209 Host: as.example.com 211 1.2. Conventions and Terminology 213 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 214 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 215 "OPTIONAL" in this document are to be interpreted as described in BCP 216 14 [RFC2119] [RFC8174] when, and only when, they appear in all 217 capitals, as shown here. 219 This specification uses the terms "access token", "authorization 220 server", "authorization endpoint", "authorization request", "token 221 endpoint", and "client" defined by The OAuth 2.0 Authorization 222 Framework [RFC6749]. 224 2. Pushed Authorization Request Endpoint 226 The pushed authorization request endpoint is an HTTP API at the 227 authorization server that accepts HTTP "POST" requests with 228 parameters in the HTTP request entity-body using the "application/x- 229 www-form-urlencoded" format with a character encoding of UTF-8 as 230 described in Appendix B of [RFC6749]. The pushed authorization 231 request endpoint URL MUST use the "https" scheme. 233 Authorization servers supporting pushed authorization requests SHOULD 234 include the URL of their pushed authorization request endpoint in 235 their authorization server metadata document [RFC8414] using the 236 "pushed_authorization_request_endpoint" parameter as defined in 237 Section 5. 239 The endpoint accepts the authorization request parameters defined in 240 [RFC6749] for the authorization endpoint as well as all applicable 241 extensions defined for the authorization endpoint. Some examples of 242 such extensions include PKCE [RFC7636], Resource Indicators 243 [RFC8707], and OpenID Connect [OIDC]. The endpoint MAY also support 244 sending the set of authorization request parameters as a request 245 object according to [I-D.ietf-oauth-jwsreq] and Section 3. 247 The rules for client authentication as defined in [RFC6749] for token 248 endpoint requests, including the applicable authentication methods, 249 apply for the pushed authorization request endpoint as well. If 250 applicable, the "token_endpoint_auth_method" client metadata 251 [RFC7591] parameter indicates the registered authentication method 252 for the client to use when making direct requests to the 253 authorization server, including requests to the pushed authorization 254 request endpoint. Similarly, the 255 "token_endpoint_auth_methods_supported" authorization server metadata 256 [RFC8414] parameter lists client authentication methods supported by 257 the authorization server when accepting direct requests from clients, 258 including requests to the pushed authorization request endpoint. 260 Due to historical reasons there is potential ambiguity regarding the 261 appropriate audience value to use when employing JWT client assertion 262 based authentication (defined in Section 2.2 of [RFC7523] with 263 "private_key_jwt" or "client_secret_jwt" authentication method names 264 per Section 9 of [OIDC]). To address that ambiguity the issuer 265 identifier URL of the authorization server according to [RFC8414] 266 SHOULD be used as the value of the audience. In order to facilitate 267 interoperability the authorization server MUST accept its issuer 268 identifier, token endpoint URL, or pushed authorization request 269 endpoint URL as values that identify it as an intended audience. 271 2.1. Request 273 A client sends the parameters that comprise an authorization request 274 directly to the pushed authorization request endpoint. A typical 275 parameter set might include: "client_id", "response_type", 276 "redirect_uri", "scope", "state", "code_challenge", and 277 "code_challenge_method" as shown in the example below. However, the 278 pushed authorization request can be composed of any of the parameters 279 applicable for use at authorization endpoint including those defined 280 in [RFC6749] as well as all applicable extensions. The "request_uri" 281 authorization request parameter is one exception, which MUST NOT be 282 provided. 284 The request also includes, as appropriate for the given client, any 285 additional parameters necessary for client authentication (e.g., 286 "client_secret", or "client_assertion" and "client_assertion_type"). 288 Such parameters are defined and registered for use at the token 289 endpoint but are applicable only for client authentication. When 290 present in a pushed authorization request, they are relied upon only 291 for client authentication and are not germane to the authorization 292 request itself. Any token endpoint parameters that are not related 293 to client authentication have no defined meaning for a pushed 294 authorization request. The "client_id" parameter is defined with the 295 same semantics for both authorization requests and requests to the 296 token endpoint; as a required authorization request parameter, it is 297 similarly required in a pushed authorization request. 299 The client adds the parameters in "x-www-form-urlencoded" format with 300 a character encoding of UTF-8 as described in Appendix B of [RFC6749] 301 to the body of an HTTP "POST" request. If applicable, the client 302 also adds its authentication credentials to the request header or the 303 request body using the same rules as for token endpoint requests. 305 This is illustrated by the following example (extra line breaks in 306 the message-body for display purposes only): 308 POST /as/par HTTP/1.1 309 Host: as.example.com 310 Content-Type: application/x-www-form-urlencoded 311 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 313 response_type=code&state=af0ifjsldkj&client_id=s6BhdRkqt3 314 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 315 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U 316 &code_challenge_method=S256&scope=account-information 318 The authorization server MUST process the request as follows: 320 1. Authenticate the client in the same way as at the token endpoint 321 (Section 2.3 of [RFC6749]). 323 2. Reject the request if the "request_uri" authorization request 324 parameter is provided. 326 3. Validate the pushed request as it would an authorization request 327 sent to the authorization endpoint. For example, the 328 authorization server checks whether the redirect URI matches one 329 of the redirect URIs configured for the client and also checks 330 whether the client is authorized for the scope for which it is 331 requesting access. This validation allows the authorization 332 server to refuse unauthorized or fraudulent requests early. The 333 authorization server MAY omit validation steps that it is unable 334 to perform when processing the pushed request, however such 335 checks MUST then be performed at the authorization endpoint. 337 The authorization server MAY allow clients with authentication 338 credentials to establish per-authorization request redirect URIs with 339 every pushed authorization request. Described in more detail in 340 Section 2.4, this is possible since, in contrast to [RFC6749], this 341 specification gives the authorization server the ability to 342 authenticate clients and validate client requests before the actual 343 authorization request is performed. 345 2.2. Successful Response 347 If the verification is successful, the server MUST generate a request 348 URI and return a JSON response with the following members at the top 349 level with "201 Created" HTTP response code. 351 * "request_uri" : The request URI corresponding to the authorization 352 request posted. This URI is used as reference to the respective 353 request data in the subsequent authorization request only. The 354 way the authorization process obtains the authorization request 355 data is at the discretion of the authorization server and out of 356 scope of this specification. There is no need to make the 357 authorization request data available to other parties via this 358 URI. 360 * "expires_in" : A JSON number that represents the lifetime of the 361 request URI in seconds as a positive integer. The request URI 362 lifetime is at the discretion of the authorization server but will 363 typically be relatively short (e.g., between 5 and 600 seconds). 365 The format of the "request_uri" value is at the discretion of the 366 authorization server but it MUST contain some part generated using a 367 cryptographically strong pseudorandom algorithm such that it is 368 computationally infeasible to predict or guess a valid value (see 369 Section 10.10 of [RFC6749] for specifics). The authorization server 370 MAY construct the "request_uri" value using the form 371 "urn:ietf:params:oauth:request_uri:" with 372 "" as the random part of the URI that references the 373 respective authorization request data. 375 The "request_uri" value MUST be bound to the client that posted the 376 authorization request. 378 The following is an example of such a response: 380 HTTP/1.1 201 Created 381 Content-Type: application/json 382 Cache-Control: no-cache, no-store 384 { 385 "request_uri": 386 "urn:ietf:params:oauth:request_uri:bwc4JK-ESC0w8acc191e-Y1LTC2", 387 "expires_in": 60 388 } 390 2.3. Error Response 392 The authorization server returns an error response with the same 393 format as is specified for error responses from the token endpoint in 394 Section 5.2 of [RFC6749] using the appropriate error code from 395 therein or from Section 4.1.2.1 of [RFC6749]. In those cases where 396 Section 4.1.2.1 of [RFC6749] prohibits automatic redirection with an 397 error back to the requesting client and hence doesn't define an error 398 code, for example when the request fails due to a missing, invalid, 399 or mismatching redirection URI, the "invalid_request" error code can 400 be used as the default error code. Error codes defined by OAuth 401 extension can also be used when such an extension is involved in the 402 initial processing of authorization request that was pushed. Since 403 initial processing of the pushed authorization request does not 404 involve resource owner interaction, error codes related to user 405 interaction, such as "consent_required" defined by [OIDC], are never 406 returned. 408 If the client is required to use signed request objects, either by 409 authorization server or client policy (see [I-D.ietf-oauth-jwsreq], 410 section 10.5), the authorization server MUST only accept requests 411 complying with the definition given in Section 3 and MUST refuse any 412 other request with HTTP status code 400 and error code 413 "invalid_request". 415 In addition to the above, the pushed authorization request endpoint 416 can also make use of the following HTTP status codes: 418 * 405: If the request did not use the "POST" method, the 419 authorization server responds with an HTTP 405 (Method Not 420 Allowed) status code. 422 * 413: If the request size was beyond the upper bound that the 423 authorization server allows, the authorization server responds 424 with an HTTP 413 (Payload Too Large) status code. 426 * 429: If the number of requests from a client during a particular 427 time period exceeds the number the authorization server allows, 428 the authorization server responds with an HTTP 429 (Too Many 429 Requests) status code. 431 The following is an example of an error response from the pushed 432 authorization request endpoint: 434 HTTP/1.1 400 Bad Request 435 Content-Type: application/json 436 Cache-Control: no-cache, no-store 438 { 439 "error": "invalid_request", 440 "error_description": 441 "The redirect_uri is not valid for the given client" 442 } 444 2.4. Management of Client Redirect URIs 446 While OAuth 2.0 [RFC6749] allows clients to use unregistered 447 "redirect_uri" values in certain circumstances, or for the 448 authorization server to apply its own matching semantics to the 449 "redirect_uri" value presented by the client at the authorization 450 endpoint, the OAuth Security BCP [I-D.ietf-oauth-security-topics] as 451 well as OAuth 2.1 [I-D.ietf-oauth-v2-1] require an authorization 452 server exactly match the "redirect_uri" parameter against the set of 453 redirect URIs previously established for a particular client. This 454 is a means for early detection of client impersonation attempts and 455 prevents token leakage and open redirection. As a downside, this can 456 make client management more cumbersome since the redirect URI is 457 typically the most volatile part of a client policy. 459 The exact matching requirement MAY be relaxed when using pushed 460 authorization requests for clients that have established 461 authentication credentials with the authorization server. This is 462 possible since, in contrast to a traditional authorization request, 463 the authorization server authenticates the client before the 464 authorization process starts and thus ensures it is interacting with 465 the legitimate client. The authorization server MAY allow such 466 clients to specify "redirect_uri" values that were not previously 467 registered with the authorization server. This will give the client 468 more flexibility (e.g. to mint distinct redirect URI values per 469 authorization server at runtime) and can simplify client management. 470 It is at the discretion of the authorization server to apply 471 restrictions on supplied "redirect_uri" values, e.g. the 472 authorization server MAY require a certain URI prefix or allow only a 473 query parameter to vary at runtime. 475 Note: The ability to set up transaction specific redirect URIs is 476 also useful in situations where client ids and corresponding 477 credentials and policies are managed by a trusted 3rd party, e.g. via 478 client certificates containing client permissions. Such an 479 externally managed client could interact with an authorization server 480 trusting the respective 3rd party without the need for an additional 481 registration step. 483 3. The "request" Request Parameter 485 Clients MAY use the "request" parameter as defined in JAR 486 [I-D.ietf-oauth-jwsreq] to push a request object JWT to the 487 authorization server. The rules for processing, signing, and 488 encryption of the request object as defined in JAR 489 [I-D.ietf-oauth-jwsreq] apply. When the "application/x-www-form- 490 urlencoded" HTTP entity-body "request" parameter is used, the request 491 object MUST contain all the authorization request parameters as 492 claims of the JWT. Additional request parameters as required by the 493 given client authentication method are to be included as 494 'application/x-www-form-urlencoded' parameters in the HTTP request 495 entity-body (e.g. Mutual TLS client authentication [RFC8705] uses 496 the "client_id" HTTP request parameter while JWT assertion based 497 client authentication [RFC7523] uses "client_assertion" and 498 "client_assertion_type"). 500 The following is an example of a pushed authorization request using a 501 signed request object. The client is authenticated by its client 502 secret using the HTTP Basic Authentication scheme specified in 503 Section 2.3.1 of [RFC6749] (extra line breaks for display purposes 504 only): 506 POST /as/par HTTP/1.1 507 Host: as.example.com 508 Content-Type: application/x-www-form-urlencoded 509 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 511 request=eyJraWQiOiJrMmJkYyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJzNkJoZ 512 FJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJyZXNwb2 513 5zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmV 514 jdF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm9yZy9jYiIsInNjb3BlIjoi 515 YWlzIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImNvZGVfY2hhbGxlbmdlIjoiSzItb 516 HRjODNhY2M0aDBjOXc2RVNDX3JFTVRKM2J3dy11Q0hhb2VLMXQ4VSIsImNvZGVfY2 517 hhbGxlbmdlX21ldGhvZCI6IlMyNTYifQ.O49ffUxRPdNkN3TRYDvbEYVr1CeAL64u 518 W4FenV3n9WlaFIRHeFblzv-wlEtMm8-tusGxeE9z3ek6FxkhvvLEqEpjthXnyXqqy 519 Jfq3k9GSf5ay74ml_0D6lHE1hy-kVWg7SgoPQ-GB1xQ9NRhF3EKS7UZIrUHbFUCF0 520 MsRLbmtIvaLYbQH_Ef3UkDLOGiU7exhVFTPeyQUTM9FF-u3K-zX-FO05_brYxNGLh 521 VkO1G8MjqQnn2HpAzlBd5179WTzTYhKmhTiwzH-qlBBI_9GLJmE3KOipko9TfSpa2 522 6H4JOlMyfZFl0PCJwkByS0xZFJ2sTo3Gkk488RQohhgt1I0onw 523 &client_id=s6BhdRkqt3 525 The authorization server MUST take the following steps beyond the 526 processing rules defined in Section 2.1: 528 1. If applicable, decrypt the request object as specified in JAR 529 [I-D.ietf-oauth-jwsreq], section 6.1. 531 2. Validate the request object signature as specified in JAR 532 [I-D.ietf-oauth-jwsreq], section 6.2. 534 3. If the client has authentication credentials established with the 535 authorization server, reject the request if the authenticated 536 "client_id" does not match the "client_id" claim in the request 537 object. Additionally requiring the "iss" claim to match the 538 "client_id" is at the discretion of authorization server. 540 The following RSA key pair, represented in JWK [RFC7517] format, can 541 be used to validate or recreate the request object signature in the 542 above example (extra line breaks and indentation within values for 543 display purposes only): 545 { 546 "kty": "RSA", 547 "kid":"k2bdc", 548 "n": "y9Lqv4fCp6Ei-u2-ZCKq83YvbFEk6JMs_pSj76eMkddWRuWX2aBKGHAtKlE 549 5P7_vn__PCKZWePt3vGkB6ePgzAFu08NmKemwE5bQI0e6kIChtt_6KzT5Oa 550 aXDFI6qCLJmk51Cc4VYFaxgqevMncYrzaW_50mZ1yGSFIQzLYP8bijAHGVj 551 dEFgZaZEN9lsn_GdWLaJpHrB3ROlS50E45wxrlg9xMncVb8qDPuXZarvghL 552 L0HzOuYRadBJVoWZowDNTpKpk2RklZ7QaBO7XDv3uR7s_sf2g-bAjSYxYUG 553 sqkNA9b3xVW53am_UZZ3tZbFTIh557JICWKHlWj5uzeJXaw", 554 "e": "AQAB", 555 "d": "LNwG_pCKrwowALpCpRdcOKlSVqylSurZhE6CpkRiE9cpDgGKIkO9CxPlXOL 556 zjqxXuQc8MdMqRQZTnAwgd7HH0B6gncrruV3NewI-XQV0ckldTjqNfOTz1V 557 Rs-jE-57KAXI3YBIhu-_0YpIDzdk_wBuAk661Svn0GsPQe7m9DoxdzenQu9 558 O_soewUhlPzRrTH0EeIqYI715rwI3TYaSzoWBmEPD2fICyj18FF0MPy_SQz 559 k3noVUUIzfzLnnJiWy_p63QBCMqjRoSHHdMnI4z9iVpIwJWQ3jO5n_2lC2- 560 cSgwjmKsFzDBbQNJc7qMG1N6EssJUwgGJxz1eAUFf0w4YAQ", 561 "qi": "J-mG0swR4FTy3atrcQ7dd0hhYn1E9QndN- 562 -sDG4EQO0RnFj6wIefCvwIc4 563 7hCtVeFnCTPYJNc_JyV-mU-9vlzS5GSNuyR5qdpsMZXUMpEvQcwKt23ffPZ 564 YGaqfKyEesmf_Wi8fFcE68H9REQjnniKrXm7w2-IuG_IrVJA9Ox-uU", 565 "q": "4hlMYAGa0dvogdK1jnxQ7J_Lqpqi99e-AeoFvoYpMPhthChTzwFZO9lQmUo 566 BpMqVQTws_s7vWGmt7ZAB3ywkurf0pV7BD0fweJiUzrWk4KJjxtmP_auuxr 567 jvm3s2FUGn6f0wRY9Z8Hj9A7C72DnYCjuZiJQMYCWDsZ8-d-L1a-s", 568 "p": "5sd9Er3I2FFT9R-gy84_oakEyCmgw036B_nfYEEOCwpSvi2z7UcIVK3bSEL 569 5WCW6BNgB3HDWhq8aYPirwQnqm0K9mX1E-4xM10WWZ-rP3XjYpQeS0Snru5 570 LFVWsAzi-FX7BOqBibSAXLdEGXcXa44l08iec_bPD3xduq5V_1YoE", 571 "dq": "Nz2PF3XM6bEc4XsluKZO70ErdYdKgdtIJReUR7Rno_tOZpejwlPGBYVW19 572 zpAeYtCT82jxroB2XqhLxGeMxEPQpsz2qTKLSe4BgHY2ml2uxSDGdjcsrbb 573 NoKUKaN1CuyZszhWl1n0AT_bENl4bJgQj_Fh0UEsQj5YBBUJt5gr_k", 574 "dp": "Zc877jirkkLOtyTs2vxyNe9KnMNAmOidlUc2tE_-0gAL4Lpo1hSwKCtKwe 575 ZJ-gkqt1hT-dwNx_0Xtg_-NXsadMRMwJnzBMYwYAfjApUkfqABc0yUCJJl3 576 KozRCugf1WXkU9GZAH2_x8PUopdNUEa70ISowPRh04HANKX4fkjWAE" 577 } 579 4. Authorization Request 581 The client uses the "request_uri" value returned by the authorization 582 server to build an authorization request as defined in 583 [I-D.ietf-oauth-jwsreq]. This is shown in the following example 584 where the client directs the user-agent to make the following HTTP 585 request (extra line breaks and indentation for display purposes 586 only): 588 GET /authorize?client_id=s6BhdRkqt3&request_uri=urn%3Aietf%3Aparams 589 %3Aoauth%3Arequest_uri%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 590 Host: as.example.com 592 Since parts of the authorization request content, e.g. the 593 "code_challenge" parameter value, are unique to a particular 594 authorization request, the client MUST only use a "request_uri" value 595 once. Authorization servers SHOULD treat "request_uri" values as 596 one-time use but MAY allow for duplicate requests due to a user 597 reloading/refreshing their user-agent. 599 The authorization server MUST validate authorization requests arising 600 from a pushed request as it would any other authorization request. 601 The authorization server MAY omit validation steps that it performed 602 when the request was pushed, provided that it can validate that the 603 request was a pushed request, and that the request or the 604 authorization server's policy has not been modified in a way that 605 would affect the outcome of the omitted steps. 607 Authorization server policy MAY dictate, either globally or on a per- 608 client basis, that pushed authorization requests are the only means 609 for a client to pass authorization request data. In this case, the 610 authorization server will refuse, using the "invalid_request" error 611 code, to process any request to the authorization endpoint that does 612 not have a "request_uri" parameter with a value obtained from the 613 pushed authorization request endpoint. 615 Note: authorization server and clients MAY use metadata as defined in 616 Section 5 and Section 6 to signal the desired behavior. 618 5. Authorization Server Metadata 620 The following authorization server metadata [RFC8414] parameters are 621 introduced to signal the server's capability and policy with respect 622 to pushed authorization requests. 624 "pushed_authorization_request_endpoint" The URL of the pushed 625 authorization request endpoint at which a client can post an 626 authorization request in exchange for a "request_uri" value usable 627 at the authorization server. 629 "require_pushed_authorization_requests" Boolean parameter indicating 630 whether the authorization server accepts authorization request 631 data only via the pushed authorization request method. If 632 omitted, the default value is "false". 634 Note that the presence of "pushed_authorization_request_endpoint" is 635 sufficient for a client to determine that it may use the pushed 636 authorization request flow. A "request_uri" value obtained from the 637 PAR endpoint is usable at the authorization endpoint regardless of 638 other authorization server metadata such as 639 "request_uri_parameter_supported" or 640 "require_request_uri_registration". 642 6. Client Metadata 644 The Dynamic Client Registration Protocol [RFC7591] defines an API for 645 dynamically registering OAuth 2.0 client metadata with authorization 646 servers. The metadata defined by [RFC7591], and registered 647 extensions to it, also imply a general data model for clients that is 648 useful for authorization server implementations even when the Dynamic 649 Client Registration Protocol isn't in play. Such implementations 650 will typically have some sort of user interface available for 651 managing client configuration. The following client metadata 652 parameter is introduced by this document to indicate whether pushed 653 authorization requests are required for the given client. 655 "require_pushed_authorization_requests" Boolean parameter indicating 656 whether the only means of initiating an authorization request the 657 client is allowed to use is a pushed authorization request. If 658 omitted, the default value is "false". 660 7. Security Considerations 662 7.1. Request URI Guessing 664 An attacker could attempt to guess and replay a valid request URI 665 value and try to impersonate the respective client. The 666 authorization server MUST consider the considerations given in JAR 667 [I-D.ietf-oauth-jwsreq], section 10.2, clause (d) on request URI 668 entropy. 670 7.2. Open Redirection 672 An attacker could try register a redirect URI pointing to a site 673 under his control in order to obtain authorization codes or launch 674 other attacks towards the user. The authorization server MUST only 675 accept new redirect URIs in the pushed authorization request from 676 authenticated clients. 678 7.3. Request Object Replay 680 An attacker could replay a request URI captured from a legitimate 681 authorization request. In order to cope with such attacks, the 682 authorization server SHOULD make the request URIs one-time use. 684 7.4. Client Policy Change 686 The client policy might change between the lodging of the request 687 object and the authorization request using a particular request 688 object. It is therefore recommended that the authorization server 689 check the request parameter against the client policy when processing 690 the authorization request. 692 7.5. Request URI Swapping 694 An attacker could capture the request URI from one request and then 695 substitute it into a different authorization request. For example, 696 in the context of OpenID Connect, an attacker could replace a request 697 URI asking for a high level of authentication assurance with one that 698 requires a lower level of assurance. Clients SHOULD make use of PKCE 699 [RFC7636], a unique "state" parameter [RFC6749], or the OIDC "nonce" 700 parameter [OIDC] in the pushed request object to prevent this attack. 702 8. Privacy Considerations 704 OAuth 2.0 is a complex and flexible framework with broad ranging 705 privacy implications due to the very nature of it having one entity 706 intermediate user authorization to data access between two other 707 entities. The privacy considerations of all of OAuth are beyond the 708 scope of this document, which only defines an alternative way of 709 initiating one message sequence in the larger framework. Using 710 pushed authorization requests, however, may improve privacy by 711 reducing the potential for inadvertent information disclosure due to 712 passing authorization request data directly between client and 713 authorization server over a secure connection in the message-body of 714 an HTTP request rather than in the query component of a URL that 715 passes through the user-agent in the clear. 717 9. Acknowledgements 719 This specification is based on the work towards Pushed Request Object 720 (https://bitbucket.org/openid/fapi/src/master/ 721 Financial_API_Pushed_Request_Object.md) conducted at the Financial- 722 grade API working group at the OpenID Foundation. We would like to 723 thank the members of the WG for their valuable contributions. 725 We would like to thank Vladimir Dzhuvinov, Aaron Parecki, Justin 726 Richer, Sascha Preibisch, Daniel Fett, Michael B. Jones, Annabelle 727 Backman, Joseph Heenan, Sean Glencross, Maggie Hung, Neil Madden, 728 Karsten Meyer zu Selhausen, Roman Danyliw, and Takahiko Kawasaki for 729 their valuable feedback on this draft. 731 10. IANA Considerations 733 10.1. OAuth Authorization Server Metadata 735 This specification requests registration of the following values in 736 the IANA "OAuth Authorization Server Metadata" registry of 737 [IANA.OAuth.Parameters] established by [RFC8414]. 739 Metadata Name: "pushed_authorization_request_endpoint" 740 Metadata Description: URL of the authorization server's pushed 741 authorization request endpoint 742 Change Controller: IESG 743 Specification Document(s): Section 5 of [[ this document ]] 745 Metadata Name: "require_pushed_authorization_requests" 746 Metadata Description: Indicates whether the authorization server 747 accepts authorization request only via the pushed authorization 748 request method. 749 Change Controller: IESG 750 Specification Document(s): Section 5 of [[ this document ]] 752 10.2. OAuth Dynamic Client Registration Metadata 754 This specification requests registration of the following value in 755 the IANA "OAuth Dynamic Client Registration Metadata" registry of 756 [IANA.OAuth.Parameters] established by [RFC7591]. 758 Metadata Name: "require_pushed_authorization_requests" 759 Metadata Description: Indicates whether the client is required to 760 use the pushed authorization request method to initiate 761 authorization requests. 762 Change Controller: IESG 763 Specification Document(s): Section 6 of [[ this document ]] 765 10.3. OAuth URI Registration 767 This specification requests registration of the following value in 768 the "OAuth URI" registry of [IANA.OAuth.Parameters] established by 769 [RFC6755]. 771 URN: "urn:ietf:params:oauth:request_uri:" 772 Common Name: A URN Sub-Namespace for OAuth Request URIs. 774 Change Controller: IESG 775 Specification Document(s): Section 2.2 of [[ this document ]] 777 11. Normative References 779 [I-D.ietf-oauth-jwsreq] 780 Sakimura, N., Bradley, J., and M. B. Jones, "The OAuth 2.0 781 Authorization Framework: JWT Secured Authorization Request 782 (JAR)", Work in Progress, Internet-Draft, draft-ietf- 783 oauth-jwsreq-34, 8 April 2021, 784 . 786 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 787 Requirement Levels", BCP 14, RFC 2119, 788 DOI 10.17487/RFC2119, March 1997, 789 . 791 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 792 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 793 May 2017, . 795 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 796 Authorization Server Metadata", RFC 8414, 797 DOI 10.17487/RFC8414, June 2018, 798 . 800 12. Informative References 802 [I-D.ietf-oauth-security-topics] 803 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 804 "OAuth 2.0 Security Best Current Practice", Work in 805 Progress, Internet-Draft, draft-ietf-oauth-security- 806 topics-18, 13 April 2021, . 809 [I-D.ietf-oauth-v2-1] 810 Hardt, D., Parecki, A., and T. Lodderstedt, "The OAuth 2.1 811 Authorization Framework", Work in Progress, Internet- 812 Draft, draft-ietf-oauth-v2-1-02, 15 March 2021, 813 . 815 [IANA.OAuth.Parameters] 816 IANA, "OAuth Parameters", 817 . 819 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 820 C. Mortimore, "OpenID Connect Core 1.0 incorporating 821 errata set 1", 8 November 2014, 822 . 824 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 825 RFC 6749, DOI 10.17487/RFC6749, October 2012, 826 . 828 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 829 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 830 . 832 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 833 DOI 10.17487/RFC7517, May 2015, 834 . 836 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 837 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 838 . 840 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 841 (JWT) Profile for OAuth 2.0 Client Authentication and 842 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 843 2015, . 845 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 846 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 847 RFC 7591, DOI 10.17487/RFC7591, July 2015, 848 . 850 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 851 for Code Exchange by OAuth Public Clients", RFC 7636, 852 DOI 10.17487/RFC7636, September 2015, 853 . 855 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 856 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 857 and Certificate-Bound Access Tokens", RFC 8705, 858 DOI 10.17487/RFC8705, February 2020, 859 . 861 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 862 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 863 February 2020, . 865 Appendix A. Document History 867 [[ To be removed from the final specification ]] 869 -08 871 * Updates to address feedback from AD Review 872 https://mailarchive.ietf.org/arch/msg/oauth/ 873 bGSyonUqsvJ1vtY7l_ohwov25SA/ 874 (https://mailarchive.ietf.org/arch/msg/oauth/ 875 bGSyonUqsvJ1vtY7l_ohwov25SA/) 877 -07 879 * updated references (however they did not actually update due to 880 tooling issues - some info in this thread: 881 https://mailarchive.ietf.org/arch/msg/xml2rfc/ 882 zqYiMxZ070SCIi7CRNF9vbDeYno/ 883 (https://mailarchive.ietf.org/arch/msg/xml2rfc/ 884 zqYiMxZ070SCIi7CRNF9vbDeYno/) ) 886 -06 888 * Add a note clarifying that the presence of 889 "pushed_authorization_request_endpoint" is sufficient for a client 890 to know that it can use the PAR flow 892 -05 894 * Mention use of "invalid_request" error code for cases, like a bad 895 "redirect_uri", that don't have a more specific one 897 -04 899 * Edits to address WGLC comments 901 * Replace I-D.ietf-oauth-mtls reference with now published RFC8705 903 * Moved text about redirect URI management from introduction into 904 separate section 906 -03 908 * Editorial updates 910 * Mention that https is required for the PAR endpoint 911 * Add some discussion of browser form posting an authz request vs. 912 the benefits of PAR for any application 914 * Added text about motivations behind PAR - integrity, 915 confidentiality and early client auth 917 * Better explain one-time use recommendation of the request_uri 919 * Drop the section on special error responses for request objects 921 * Clarify authorization request examples to say that the client 922 directs the user-agent to make the HTTP GET request (vs. making 923 the request itself) 925 -02 927 * Update Resource Indicators reference to the somewhat recently 928 published RFC 8707 930 * Added metadata in support of pushed authorization requests only 931 feature 933 * Update to comply with draft-ietf-oauth-jwsreq-21, which requires 934 "client_id" in the authorization request in addition to the 935 "request_uri" 937 * Clarified timing of request validation 939 * Add some guidance/options on the request URI structure 941 * Add the key used in the request object example so that a reader 942 could validate or recreate the request object signature 944 * Update to draft-ietf-oauth-jwsreq-25 and added note regarding 945 "require_signed_request_object" 947 -01 949 * Use the newish RFC v3 XML and HTML format 950 * Added IANA registration request for 951 "pushed_authorization_request_endpoint" 952 * Changed abbrev to "OAuth PAR" 954 -00 (WG draft) 956 * Reference RFC6749 sec 2.3.1 for client secret basic rather than 957 RFC7617 959 * further clarify that a request object JWT contains all the 960 authorization request parameters while client authentication 961 params, if applicable, are outside that JWT as regular form 962 encoded params in HTTP body 964 -01 966 * List "client_id" as one of the basic parameters 967 * Explicitly forbid "request_uri" in the processing rules 968 * Clarification regarding client authentication and that public 969 clients are allowed 970 * Added option to let clients register per-authorization request 971 redirect URIs 972 * General clean up and wording improvements 974 -00 976 * first draft 978 Authors' Addresses 980 Torsten Lodderstedt 981 yes.com 983 Email: torsten@lodderstedt.net 985 Brian Campbell 986 Ping Identity 988 Email: bcampbell@pingidentity.com 990 Nat Sakimura 991 NAT.Consulting 993 Email: nat@sakimura.org 995 Dave Tonge 996 Moneyhub Financial Technology 998 Email: dave@tonge.org 1000 Filip Skokan 1001 Auth0 1002 Email: panva.ip@gmail.com