idnits 2.17.1 draft-lodderstedt-oauth-par-00.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 21, 2019) is 1679 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) -- Looks like a reference, but probably isn't: '1' on line 503 == Outdated reference: A later version (-34) exists of draft-ietf-oauth-jwsreq-19 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). 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: March 24, 2020 Ping Identity 6 N. Sakimura 7 Nomura Research Institute 8 D. Tonge 9 Moneyhub Financial Technology 10 F. Skokan 11 Auth0 12 September 21, 2019 14 OAuth 2.0 Pushed Authorization Requests 15 draft-lodderstedt-oauth-par-00 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 authorization request. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on March 24, 2020. 42 Copyright Notice 44 Copyright (c) 2019 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 4 61 2. Pushed Authorization Request Endpoint . . . . . . . . . . . . 4 62 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 2.2. Successful Response . . . . . . . . . . . . . . . . . . . 6 64 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 7 65 2.3.1. Error responses . . . . . . . . . . . . . . . . . . . 7 66 3. "request" Parameter . . . . . . . . . . . . . . . . . . . . . 8 67 3.1. Error responses for Request Object . . . . . . . . . . . 9 68 3.1.1. Authentication Required . . . . . . . . . . . . . . . 9 69 4. Authorization Request . . . . . . . . . . . . . . . . . . . . 9 70 5. Authorization Server Metadata . . . . . . . . . . . . . . . . 9 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 72 6.1. Request URI Guessing . . . . . . . . . . . . . . . . . . 10 73 6.2. Request Object Replay . . . . . . . . . . . . . . . . . . 10 74 6.3. Client Policy Change . . . . . . . . . . . . . . . . . . 10 75 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 76 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 79 9.2. Informative References . . . . . . . . . . . . . . . . . 11 80 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 Appendix A. Document History . . . . . . . . . . . . . . . . . . 11 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 84 1. Introduction 86 In OAuth [RFC6749] authorization request parameters are typically 87 sent as URI query parameters via redirection in the user-agent. This 88 is simple but also yields challenges: 90 o There is no cryptographical integrity and authenticity protection, 91 i.e. the request can be modified on its way through the user-agent 92 and attackers can impersonate legitimate clients. 94 o There is no mechanism to ensure confidentiality of the request 95 parameters. 97 o Authorization request URLs can become quite large, especially in 98 scenarios requiring fine-grained authorization data. 100 JWT Secured Authorization Request (JAR) [I-D.ietf-oauth-jwsreq] 101 provides solutions for those challenges by allowing OAuth clients to 102 wrap authorization request parameters in a signed, and optionally 103 encrypted, JSON Web Token (JWT), the so-called "Request Object". 105 In order to cope with the size restrictions, JAR introduces the 106 "request_uri" parameter that allows clients to send a reference to a 107 request object instead of the request object itself. 109 This document complements JAR by providing an interoperable way to 110 push the payload of a request object directly to the AS in exchange 111 for a "request_uri". 113 It also allows for clients to push the form encoded authorization 114 request parameters to the AS in order to 115 exchange them for a request URI that the client can use in a 116 subsequent authorization request. 118 For example, the following authorization request, 120 GET /authorize?response_type=code 121 &client_id=s6BhdRkqt3&state=af0ifjsldkj 122 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 123 Host: as.example.com 125 could be pushed directly to the AS by the client as follows, 127 POST /as/par HTTP/1.1 128 Host: as.example.com 129 Content-Type: application/x-www-form-urlencoded 130 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 132 response_type=code 133 &client_id=s6BhdRkqt3&state=af0ifjsldkj 134 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 136 The AS responds with a request URI, 137 HTTP/1.1 201 Created 138 Cache-Control: no-cache, no-store 139 Content-Type: application/json 141 { 143 "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2", 144 "expires_in": 90 145 } 147 which is used by the client in the subsequent authorization request 148 as follows, 150 GET /authorize?request_uri= 151 urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 153 The pushed authorization request endpoint thus fosters OAuth security 154 by providing all clients a simple means for an integrity protected 155 authorization request, but it also allows clients requiring an even 156 higher security level, especially cryptographically confirmed non- 157 repudiation, to explicitly adopt JWT-based request objects. 159 1.1. Conventions and Terminology 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 163 "OPTIONAL" in this document are to be interpreted as described in BCP 164 14 [RFC2119] [RFC8174] when, and only when, they appear in all 165 capitals, as shown here. 167 This specification uses the terms "access token", "refresh token", 168 "authorization server", "resource server", "authorization endpoint", 169 "authorization request", "authorization response", "token endpoint", 170 "grant type", "access token request", "access token response", and 171 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 173 2. Pushed Authorization Request Endpoint 175 The pushed authorization request endpoint shall be a RESTful API at 176 the authorization server that accepts "x-www-form-urlencoded" POST 177 requests. 179 The endpoint accepts the parameters defined in [RFC6749] for the 180 authorization endpoint as well as all applicable extensions defined 181 for the authorization endpoint. Some examples of such extensions 182 include PKCE [RFC7636], Resource Indicators 183 [I-D.ietf-oauth-resource-indicators], and OpenID Connect [OIDC]. 185 The rules for client authentication as defined in [RFC6749] for token 186 endpoint requests, including the applicable authentication methods, 187 apply for the pushed authorization request endpoint as well. If 188 applicable, the "token_endpoint_auth_method" client metadata 189 parameter indicates the registered authentication method for the 190 client to use when making direct requests to the authorization 191 server, including requests to the pushed authorization endpoint. 193 Note that there's some potential ambiguity around the appropriate 194 audience value to use when JWT client assertion based authentication 195 is employed. To address that ambiguity the issuer identifier URL of 196 the AS according to [RFC8414] SHOULD be used as the value of the 197 audience. In order to facilitate interoperability the AS MUST accept 198 its issuer identifier, token endpoint URL, or pushed authorization 199 request endpoint URL as values that identify it as an intended 200 audience. 202 2.1. Request 204 A client can send all the parameters that usually comprise an 205 authorization request to the pushed authorization request endpoint. 206 A basic parameter set will typically include: 208 o "response_type" 210 o "redirect_uri" 212 o "scope" 214 o "state" 216 o "code_challenge" 218 o "code_challenge_method" 220 Depending on client type and authentication method, the request might 221 also include the "client_id" parameter. The "request_uri" 222 authorization request parameter MUST NOT be provided in this case 223 (see Section 3). 225 The client adds the parameters in "x-www-form-urlencoded" format with 226 a character encoding of UTF-8 as described in Appendix B of [RFC6749] 227 to the body of a HTTP POST request. If applicable, the client also 228 adds client credentials to the request header or the request body 229 using the same rules as for token endpoint requests. 231 This is illustrated by the following example 233 POST /as/par HTTP/1.1 234 Host: as.example.com 235 Content-Type: application/x-www-form-urlencoded 236 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 238 response_type=code& 239 state=af0ifjsldkj& 240 client_id=s6BhdRkqt3& 241 redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb& 242 code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U& 243 code_challenge_method=S256& 244 scope=ais 246 The AS MUST process the request as follows: 248 1. The AS MUST authenticate the client in same way as at the token 249 endpoint. 251 2. The AS MUST validate the request the same way as at the 252 authorization endpoint. For example, the authorization server 253 checks whether the redirect URI matches one of the redirect URIs 254 configured for the "client_id". It may also check whether the 255 client is authorized for the "scope" for which it is requesting 256 access. This validation allows the authorization server to 257 refuse unauthorized or fraudulent requests early. 259 2.2. Successful Response 261 If the verification is successful, the server shall generate a 262 request URI and return a JSON response that contains "request_uri" 263 and "expires_in" members at the top level with "201 Created" HTTP 264 response code. 266 o "request_uri" : The request URI corresponding to the authorization 267 request posted. This URI is used as reference to the respective 268 request data in the subsequent authorization request only. The 269 way the authorization process obtains the authorization request 270 data is at the discretion of the authorization server and out of 271 scope of this specification. There is no need to make the 272 authorization request data available to other parties via this 273 URI. 275 o "expires_in" : A JSON number that represents the lifetime of the 276 request URI in seconds. The request URI lifetime is at the 277 discretion of the AS. 279 The "request_uri" value MUST be generated using a cryptographically 280 strong pseudorandom algorithm such that it is computationally 281 infeasible to predict or guess a valid value. 283 The "request URI" MUST be bound to the "client_id" of the client that 284 posted the authorization request. 286 Since the request URI can be replayed, its lifetime SHOULD be short 287 and preferably limited to one-time use. 289 The following is an example of such a response: 291 HTTP/1.1 201 Created 292 Date: Tue, 2 May 2017 15:22:31 GMT 293 Content-Type: application/json 295 { 296 "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2", 297 "expires_in": 3600 298 } 300 2.3. Error Response 302 2.3.1. Error responses 304 2.3.1.1. Authentication required 306 If the client authentication fails, the authorization server shall 307 return "401 Unauthorized" HTTP error response. 309 2.3.1.2. Authorization required 311 If the client is not authorized to perform the authorization request 312 it wanted to post, the authorization server shall return "403 313 Forbidden" HTTP error response. 315 2.3.1.3. Invalid request 317 If the request object received is invalid, the authorization server 318 shall return "400 Bad Request" HTTP error response. 320 2.3.1.4. Method not allowed 322 If the request did not use POST, the authorization server shall 323 return "405 Method Not Allowed" HTTP error response. 325 2.3.1.5. Request entity too large 327 If the request size was beyond the upper bound that the authorization 328 server allows, the authorization server shall return a "413 Request 329 Entity Too Large" HTTP error response. 331 2.3.1.6. Too many requests 333 If the request from the client per a time period goes beyond the 334 number the authorization server allows, the authorization server 335 shall return a "429 Too Many Requests" HTTP error response. 337 3. "request" Parameter 339 Clients MAY use the "request" parameter as defined in JAR to push a 340 request object to the AS. The rules for signing and encryption of 341 the request object as defined in JAR [I-D.ietf-oauth-jwsreq] apply. 343 Clients MUST NOT combine other authorization request parameters with 344 the "request" parameter at the pushed authorization request endpoint 345 other than the "client_id" parameter which may be a part of the 346 client authentication mechanism. 348 The following is an example of a request using a signed request 349 object. The client is authenticated using its client secret "BASIC" 350 authorization: 352 POST /as/par HTTP/1.1 353 Host: as.example.com 354 Content-Type: application/x-www-form-urlencoded 355 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 357 request=eyJraWQiOiJrMmJkYyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJzNkJoZ 358 FJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJyZXNwb2 359 5zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmV 360 jdF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm9yZy9jYiIsInNjb3BlIjoi 361 YWlzIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImNvZGVfY2hhbGxlbmdlIjoiSzItb 362 HRjODNhY2M0aDBjOXc2RVNDX3JFTVRKM2J3dy11Q0hhb2VLMXQ4VSIsImNvZGVfY2 363 hhbGxlbmdlX21ldGhvZCI6IlMyNTYifQ.O49ffUxRPdNkN3TRYDvbEYVr1CeAL64u 364 W4FenV3n9WlaFIRHeFblzv-wlEtMm8-tusGxeE9z3ek6FxkhvvLEqEpjthXnyXqqy 365 Jfq3k9GSf5ay74ml_0D6lHE1hy-kVWg7SgoPQ-GB1xQ9NRhF3EKS7UZIrUHbFUCF0 366 MsRLbmtIvaLYbQH_Ef3UkDLOGiU7exhVFTPeyQUTM9FF-u3K-zX-FO05_brYxNGLh 367 VkO1G8MjqQnn2HpAzlBd5179WTzTYhKmhTiwzH-qlBBI_9GLJmE3KOipko9TfSpa2 368 6H4JOlMyfZFl0PCJwkByS0xZFJ2sTo3Gkk488RQohhgt1I0onw 370 The AS needs to take the following steps beyond the processing rules 371 defined in Section 2.1: 373 1. If applicable, the AS decrypts the request object as specified in 374 JAR [I-D.ietf-oauth-jwsreq], section 6.1. 376 2. The AS validates the request object signature as specified in JAR 377 [I-D.ietf-oauth-jwsreq], section 6.2. 379 3. If the client is a confidential client, the authorization server 380 MUST check whether the authenticated "client_id" matches the 381 "client_id" claim in the request object. If they do not match, 382 the authorization server MUST refuse to process the request. It 383 is at the authorization server's discretion to require the "iss" 384 claim to match the "client_id" as well. 386 3.1. Error responses for Request Object 388 This section gives the error responses that go beyond the basic 389 Section 2.3. 391 3.1.1. Authentication Required 393 If the signature validation fails, the authorization server shall 394 return "401 Unauthorized" HTTP error response. The same applies if 395 the "client_id" or, if applicable, the "iss" claims in the request 396 object do not match the authenticated "client_id". 398 4. Authorization Request 400 The client uses the "request_uri" value as returned by the 401 authorization server as authorization request parameter 402 "request_uri". 404 GET /authorize?request_uri= 405 urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 407 Clients are encouraged to use the request URI as the only parameter 408 in order to use the integrity and authenticity provided by the pushed 409 authorization request. 411 5. Authorization Server Metadata 413 If the authorization server has a pushed authorization request 414 endpoint, it SHOULD include the following OAuth/OpenID Provider 415 Metadata parameter in discovery responses: 417 "pushed_authorization_request_endpoint" : The URL of the pushed 418 authorization request endpoint at which the client can exchange a 419 request object for a request URI. 421 6. Security Considerations 423 6.1. Request URI Guessing 425 An attacker could attempt to guess and replay a valid request URI 426 value and try to impersonat the respective client. The AS MUST 427 consider the considerations given in JAR [I-D.ietf-oauth-jwsreq], 428 section 10.2, clause d on request URI entropy. 430 6.2. Request Object Replay 432 An attacker could replay a request URI captured from a legit 433 authorization request. In order to cope with such attacks, the AS 434 SHOULD make the request URIs one-time use. 436 6.3. Client Policy Change 438 The client policy might change between the lodging of the request 439 object and the authorization request using a particular request 440 object. It is therefore recommended that the AS checks the request 441 parameter against the client policy when processing the authorization 442 request. 444 7. Acknowledgements 446 This specification is based on the work towards Pushed Request 447 Objects [1] conducted at the Financial Grade API working group at the 448 OpenID Foundation. We would would like to thank the members of this 449 WG for their valuable contributions work. 451 We would like to thank ... for their valuable feedback on this draft. 453 8. IANA Considerations 455 ... 457 9. References 459 9.1. Normative References 461 [I-D.ietf-oauth-jwsreq] 462 Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization 463 Framework: JWT Secured Authorization Request (JAR)", 464 draft-ietf-oauth-jwsreq-19 (work in progress), June 2019. 466 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 467 Requirement Levels", BCP 14, RFC 2119, 468 DOI 10.17487/RFC2119, March 1997, 469 . 471 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 472 RFC 6749, DOI 10.17487/RFC6749, October 2012, 473 . 475 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 476 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 477 May 2017, . 479 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 480 Authorization Server Metadata", RFC 8414, 481 DOI 10.17487/RFC8414, June 2018, 482 . 484 9.2. Informative References 486 [I-D.ietf-oauth-resource-indicators] 487 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 488 Indicators for OAuth 2.0", draft-ietf-oauth-resource- 489 indicators-08 (work in progress), September 2019. 491 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 492 C. Mortimore, "OpenID Connect Core 1.0 incorporating 493 errata set 1", Nov 2014, 494 . 496 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 497 for Code Exchange by OAuth Public Clients", RFC 7636, 498 DOI 10.17487/RFC7636, September 2015, 499 . 501 9.3. URIs 503 [1] https://bitbucket.org/openid/fapi/src/master/ 504 Financial_API_Pushed_Request_Object.md 506 Appendix A. Document History 508 [[ To be removed from the final specification ]] 510 -00 512 o first draft 514 Authors' Addresses 516 Torsten Lodderstedt 517 yes.com 519 Email: torsten@lodderstedt.net 521 Brian Campbell 522 Ping Identity 524 Email: bcampbell@pingidentity.com 526 Nat Sakimura 527 Nomura Research Institute 529 Email: nat@sakimura.org 531 Dave Tonge 532 Moneyhub Financial Technology 534 Email: dave@tonge.org 536 Filip Skokan 537 Auth0 539 Email: panva.ip@gmail.com