RFC 9126 | OAuth PAR | September 2021 |
Lodderstedt, et al. | Standards Track | [Page] |
This document defines the pushed authorization request (PAR) endpoint, which allows clients to push the payload of an OAuth 2.0 authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9126.¶
Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
This document defines the pushed authorization request (PAR) endpoint, which enables an OAuth [RFC6749] client to push the payload of an authorization request directly to the authorization server. A request URI value is received in exchange; it is used as reference to the authorization request payload data in a subsequent call to the authorization endpoint via the user agent.¶
In OAuth [RFC6749], authorization request parameters are typically sent as URI query parameters via redirection in the user agent. This is simple but also yields challenges:¶
JWT-Secured Authorization Request (JAR) [RFC9101] provides solutions for the security challenges by allowing OAuth clients to wrap authorization request parameters in a Request Object, which is a signed and optionally encrypted JSON Web Token (JWT) [RFC7519].
In order to cope with the size restrictions, JAR introduces the request_uri
parameter that allows clients to send a reference to a Request Object instead of the Request Object itself.¶
This document complements JAR by providing an interoperable way to push the payload of an authorization request directly to the authorization server in exchange for a request_uri
value usable at the authorization server in a subsequent authorization request.¶
PAR fosters OAuth security by providing clients a simple means for a confidential and integrity-protected authorization request. Clients requiring an even higher security level, especially cryptographically confirmed non-repudiation, are able to use JWT-based Request Objects as defined by [RFC9101] in conjunction with PAR.¶
PAR allows the authorization server to authenticate the client before any user interaction happens. The increased confidence in the identity of the client during the authorization process allows the authorization server to refuse illegitimate requests much earlier in the process, which can prevent attempts to spoof clients or otherwise tamper with or misuse an authorization request.¶
Note that HTTP POST
requests to the authorization endpoint via the user agent, as described in Section 3.1 of [RFC6749] and Section 3.1.2.1 of [OIDC], could also be used to cope with the request size limitations described above. However, it's only optional per [RFC6749], and, even when supported, it is a viable option for conventional web applications but is prohibitively difficult to use with installed mobile applications. As described in [RFC8252], those apps use platform-specific APIs to open the authorization request URI in the system browser. When a mobile app launches a browser, however, the resultant initial request is constrained to use the GET
method. Using POST
for the authorization request would require the app to first direct the browser to open a URI that the app controls via GET
while somehow conveying the sizable authorization request payload and then having the resultant response contain the content and script to initiate a cross-site form POST
towards the authorization server. PAR is simpler to use and has additional security benefits, as described above.¶
In conventional OAuth 2.0, a client typically initiates an authorization request by directing the user agent to make an HTTP request like the following to the authorization server's authorization endpoint (extra line breaks and indentation for display purposes only):¶
Such a request could instead be pushed directly to the authorization server by the client with a POST
request to the PAR endpoint as illustrated in the following example (extra line breaks and spaces for display purposes only).
The client can authenticate (e.g., using JWT client assertion-based authentication as shown) because the request is made directly to the authorization server.¶
The authorization server responds with a request URI:¶
The client uses the request URI value to create the subsequent authorization request by directing the user agent to make an HTTP request to the authorization server's authorization endpoint like the following (extra line breaks and indentation for display purposes only):¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This specification uses the terms "access token", "authorization server", "authorization endpoint", "authorization request", "token endpoint", and "client" defined by "The OAuth 2.0 Authorization Framework" [RFC6749].¶
Clients MAY use the request
parameter as defined in JAR [RFC9101] to push a Request Object JWT to the authorization server. The rules for processing, signing, and encryption of the Request Object as defined in JAR [RFC9101] apply. Request parameters required by a given client authentication method are included in the application/x-www-form-urlencoded
request directly and are the only parameters other than request
in the form body (e.g., mutual TLS client authentication [RFC8705] uses the client_id
HTTP request parameter, while JWT assertion-based client authentication [RFC7523] uses client_assertion
and client_assertion_type
). All other request parameters, i.e., those pertaining to the authorization request itself, MUST appear as claims of the JWT representing the authorization request.¶
The following is an example of a pushed authorization request using a signed Request Object with the same authorization request payload as the example in Section 2.1. The client is authenticated with JWT client assertion-based authentication [RFC7523] (extra line breaks and spaces for display purposes only):¶
The authorization server MUST take the following steps beyond the processing rules defined in Section 2.1:¶
client_id
does not match the client_id
claim in the Request Object. Additionally, requiring the iss
claim to match the client_id
is at the discretion of the authorization server.¶
The following RSA key pair, represented in JSON Web Key (JWK) format [RFC7517], can be used to validate or recreate the Request Object signature in the above example (extra line breaks and indentation within values for display purposes only):¶
{ "kty": "RSA", "kid":"k2bdc", "n": "y9Lqv4fCp6Ei-u2-ZCKq83YvbFEk6JMs_pSj76eMkddWRuWX2aBKGHAtKlE 5P7_vn__PCKZWePt3vGkB6ePgzAFu08NmKemwE5bQI0e6kIChtt_6KzT5Oa aXDFI6qCLJmk51Cc4VYFaxgqevMncYrzaW_50mZ1yGSFIQzLYP8bijAHGVj dEFgZaZEN9lsn_GdWLaJpHrB3ROlS50E45wxrlg9xMncVb8qDPuXZarvghL L0HzOuYRadBJVoWZowDNTpKpk2RklZ7QaBO7XDv3uR7s_sf2g-bAjSYxYUG sqkNA9b3xVW53am_UZZ3tZbFTIh557JICWKHlWj5uzeJXaw", "e": "AQAB", "d": "LNwG_pCKrwowALpCpRdcOKlSVqylSurZhE6CpkRiE9cpDgGKIkO9CxPlXOL zjqxXuQc8MdMqRQZTnAwgd7HH0B6gncrruV3NewI-XQV0ckldTjqNfOTz1V Rs-jE-57KAXI3YBIhu-_0YpIDzdk_wBuAk661Svn0GsPQe7m9DoxdzenQu9 O_soewUhlPzRrTH0EeIqYI715rwI3TYaSzoWBmEPD2fICyj18FF0MPy_SQz k3noVUUIzfzLnnJiWy_p63QBCMqjRoSHHdMnI4z9iVpIwJWQ3jO5n_2lC2- cSgwjmKsFzDBbQNJc7qMG1N6EssJUwgGJxz1eAUFf0w4YAQ", "qi": "J-mG0swR4FTy3atrcQ7dd0hhYn1E9QndN- -sDG4EQO0RnFj6wIefCvwIc4 7hCtVeFnCTPYJNc_JyV-mU-9vlzS5GSNuyR5qdpsMZXUMpEvQcwKt23ffPZ YGaqfKyEesmf_Wi8fFcE68H9REQjnniKrXm7w2-IuG_IrVJA9Ox-uU", "q": "4hlMYAGa0dvogdK1jnxQ7J_Lqpqi99e-AeoFvoYpMPhthChTzwFZO9lQmUo BpMqVQTws_s7vWGmt7ZAB3ywkurf0pV7BD0fweJiUzrWk4KJjxtmP_auuxr jvm3s2FUGn6f0wRY9Z8Hj9A7C72DnYCjuZiJQMYCWDsZ8-d-L1a-s", "p": "5sd9Er3I2FFT9R-gy84_oakEyCmgw036B_nfYEEOCwpSvi2z7UcIVK3bSEL 5WCW6BNgB3HDWhq8aYPirwQnqm0K9mX1E-4xM10WWZ-rP3XjYpQeS0Snru5 LFVWsAzi-FX7BOqBibSAXLdEGXcXa44l08iec_bPD3xduq5V_1YoE", "dq": "Nz2PF3XM6bEc4XsluKZO70ErdYdKgdtIJReUR7Rno_tOZpejwlPGBYVW19 zpAeYtCT82jxroB2XqhLxGeMxEPQpsz2qTKLSe4BgHY2ml2uxSDGdjcsrbb NoKUKaN1CuyZszhWl1n0AT_bENl4bJgQj_Fh0UEsQj5YBBUJt5gr_k", "dp": "Zc877jirkkLOtyTs2vxyNe9KnMNAmOidlUc2tE_-0gAL4Lpo1hSwKCtKwe ZJ-gkqt1hT-dwNx_0Xtg_-NXsadMRMwJnzBMYwYAfjApUkfqABc0yUCJJl3 KozRCugf1WXkU9GZAH2_x8PUopdNUEa70ISowPRh04HANKX4fkjWAE" }¶
The following authorization server metadata parameters [RFC8414] are introduced to signal the server's capability and policy with respect to PAR.¶
request_uri
value usable at the authorization server.¶
false
.¶
Note that the presence of pushed_authorization_request_endpoint
is sufficient for a client to determine that it may use the PAR flow. A request_uri
value obtained from the PAR endpoint is usable at the authorization endpoint regardless of other authorization server metadata such as request_uri_parameter_supported
oder require_request_uri_registration
[OIDC.Disco].¶
The Dynamic Client Registration Protocol [RFC7591] defines an API for dynamically registering OAuth 2.0 client metadata with authorization servers. The metadata defined by [RFC7591], and registered extensions to it, also imply a general data model for clients that is useful for authorization server implementations even when the Dynamic Client Registration Protocol isn't in play. Such implementations will typically have some sort of user interface available for managing client configuration. The following client metadata parameter is introduced by this document to indicate whether pushed authorization requests are required for the given client.¶
false
.¶
An attacker could attempt to guess and replay a valid request URI value and try to impersonate the respective client. The authorization server MUST account for the considerations given in JAR [RFC9101], Section 10.2, clause (d) on request URI entropy.¶
An attacker could try to register a redirect URI pointing to a site under their control in order to obtain authorization codes or launch other attacks towards the user. The authorization server MUST only accept new redirect URIs in the pushed authorization request from authenticated clients.¶
An attacker could replay a request URI captured from a legitimate authorization request. In order to cope with such attacks, the authorization server SHOULD make the request URIs one-time use.¶
The client policy might change between the lodging of the Request Object and the authorization request using a particular Request Object. Therefore, it is recommended that the authorization server check the request parameter against the client policy when processing the authorization request.¶
An attacker could capture the request URI from one request and then substitute it into a different authorization request. For example, in the context of OpenID Connect, an attacker could replace a request URI asking for a high level of authentication assurance with one that requires a lower level of assurance. Clients SHOULD make use of PKCE [RFC7636], a unique state
parameter [RFC6749], or the OIDC "nonce" parameter [OIDC] in the pushed Request Object to prevent this attack.¶
OAuth 2.0 is a complex and flexible framework with broad-ranging privacy implications due to its very nature of having one entity intermediate user authorization to data access between two other entities. The privacy considerations of all of OAuth are beyond the scope of this document, which only defines an alternative way of initiating one message sequence in the larger framework. However, using PAR may improve privacy by reducing the potential for inadvertent information disclosure since it passes the authorization request data directly between the client and authorization server over a secure connection in the message body of an HTTP request rather than in the query component of a URL that passes through the user agent in the clear.¶
IANA has registered the following value in the IANA "OAuth Dynamic Client Registration Metadata" registry of [IANA.OAuth.Parameters] established by [RFC7591].¶
IANA has registered the following value in the "OAuth URI" registry of [IANA.OAuth.Parameters] established by [RFC6755].¶
urn:ietf:params:oauth:request_uri:
¶
This specification is based on the work on Pushed Request Object conducted at the Financial-grade API Working Group at the OpenID Foundation. We would like to thank the members of the WG for their valuable contributions.¶
We would like to thank Vladimir Dzhuvinov, Aaron Parecki, Justin Richer, Sascha Preibisch, Daniel Fett, Michael B. Jones, Annabelle Backman, Joseph Heenan, Sean Glencross, Maggie Hung, Neil Madden, Karsten Meyer zu Selhausen, Roman Danyliw, Meral Shirazipour, and Takahiko Kawasaki for their valuable feedback on this document.¶