OAuth 2.0 Pushed Authorization Requests

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 21 August 2020.¶

Copyright Notice

Copyright (c) 2020 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.¶

Table of Contents

1. Introduction

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:¶

• There is no cryptographic integrity and authenticity protection, i.e. the request can be modified on its way through the user-agent and attackers can impersonate legitimate clients.¶

• There is no mechanism to ensure confidentiality of the request parameters.¶

• Authorization request URLs can become quite large, especially in scenarios requiring fine-grained authorization data.¶

JWT Secured Authorization Request (JAR) [I-D.ietf-oauth-jwsreq] provides solutions for those challenges by allowing OAuth clients to wrap authorization request parameters in a signed, and optionally encrypted, JSON Web Token (JWT), the so-called "Request Object".¶

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 a request object directly to the AS in exchange for a request_uri.¶

It also allows for clients to push the form encoded authorization request parameters to the AS in order to exchange them for a request URI that the client can use in a subsequent authorization request.¶

For example, the following authorization request,¶

  GET /authorize?response_type=code
   &client_id=s6BhdRkqt3&state=af0ifjsldkj
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
  Host: as.example.com

could be pushed directly to the AS by the client as follows:¶

  POST /as/par HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

  response_type=code
  &client_id=s6BhdRkqt3&state=af0ifjsldkj
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

The AS responds with a request URI,¶

  HTTP/1.1 201 Created
  Cache-Control: no-cache, no-store
  Content-Type: application/json

  {

    "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2",
    "expires_in": 90
  }

which is used by the client in the subsequent authorization request as follows,¶

  GET /authorize?request_uri=
    urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1

The pushed authorization request endpoint fosters OAuth security by providing all clients a simple means for an integrity protected authorization request, but it also allows clients requiring an even higher security level, especially cryptographically confirmed non-repudiation, to explicitly adopt JWT-based request objects.¶

As a further benefit, the pushed authorization request allows the AS to authenticate the clients before any user interaction happens, i.e., the AS may refuse unauthorized requests much earlier in the process and has much higher confidence in the client's identity in the authorization process than before.¶

This is directly utilized by this draft to allow confidential clients to set the redirect URI for every authorization request, which gives them more flexibility in building redirect URI. And if the client IDs and credentials are managed by some external authority (e.g. a certification authority), explicit client registration with the particular AS could practically be skipped.¶

2. Pushed Authorization Request Endpoint

The pushed authorization request endpoint is an HTTP API at the authorization server that accepts POST requests with parameters in the HTTP request entity-body using the application/x-www-form-urlencoded format with a character encoding of UTF-8 as described in Appendix B of [RFC6749].¶

The endpoint accepts the parameters defined in [RFC6749] for the authorization endpoint as well as all applicable extensions defined for the authorization endpoint. Some examples of such extensions include PKCE [RFC7636], Resource Indicators [I-D.ietf-oauth-resource-indicators], and OpenID Connect [OIDC].¶

The rules for client authentication as defined in [RFC6749] for token endpoint requests, including the applicable authentication methods, apply for the pushed authorization request endpoint as well. If applicable, the token_endpoint_auth_method client metadata parameter indicates the registered authentication method for the client to use when making direct requests to the authorization server, including requests to the pushed authorization request endpoint.¶

Note that there's some potential ambiguity around the appropriate audience value to use when JWT client assertion based authentication is employed. To address that ambiguity the issuer identifier URL of the AS according to [RFC8414] SHOULD be used as the value of the audience. In order to facilitate interoperability the AS MUST accept its issuer identifier, token endpoint URL, or pushed authorization request endpoint URL as values that identify it as an intended audience.¶

  POST /as/par HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

  response_type=code&
  state=af0ifjsldkj&
  client_id=s6BhdRkqt3&
  redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&
  code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U&
  code_challenge_method=S256&
  scope=ais

  HTTP/1.1 201 Created
  Content-Type: application/json
  Cache-Control: no-cache, no-store

  {
    "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2",
    "expires_in": 3600
  }

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-cache, no-store

  {
    "error": "invalid_request",
    "error_description":
      "The redirect_uri is not valid for the given client"
  }

3. "request" Parameter

Clients MAY use the request parameter as defined in JAR [I-D.ietf-oauth-jwsreq] to push a request object JWT to the AS. The rules for processing, signing, and encryption of the request object as defined in JAR [I-D.ietf-oauth-jwsreq] apply. When the application/x-www-form-urlencoded HTTP entity-body request parameter is used, the request object MUST contain all the authorization request parameters as claims of the JWT. Additional request parameters as required by the given client authentication method are to be included as 'application/x-www-form-urlencoded' parameters in the HTTP request entity-body (e.g. Mutual TLS client authentication [I-D.ietf-oauth-mtls] uses the client_id HTTP request parameter while JWT assertion based client authentication [RFC7523] uses client_assertion and client_assertion_type).¶

The following is an example of a pushed authorization request using a signed request object. The client is authenticated by its client secret using the HTTP Basic Authentication scheme specified in Section 2.3.1 of [RFC6749]:¶

  POST /as/par HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

  request=eyJraWQiOiJrMmJkYyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJzNkJoZ
  FJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJyZXNwb2
  5zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmV
  jdF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm9yZy9jYiIsInNjb3BlIjoi
  YWlzIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImNvZGVfY2hhbGxlbmdlIjoiSzItb
  HRjODNhY2M0aDBjOXc2RVNDX3JFTVRKM2J3dy11Q0hhb2VLMXQ4VSIsImNvZGVfY2
  hhbGxlbmdlX21ldGhvZCI6IlMyNTYifQ.O49ffUxRPdNkN3TRYDvbEYVr1CeAL64u
  W4FenV3n9WlaFIRHeFblzv-wlEtMm8-tusGxeE9z3ek6FxkhvvLEqEpjthXnyXqqy
  Jfq3k9GSf5ay74ml_0D6lHE1hy-kVWg7SgoPQ-GB1xQ9NRhF3EKS7UZIrUHbFUCF0
  MsRLbmtIvaLYbQH_Ef3UkDLOGiU7exhVFTPeyQUTM9FF-u3K-zX-FO05_brYxNGLh
  VkO1G8MjqQnn2HpAzlBd5179WTzTYhKmhTiwzH-qlBBI_9GLJmE3KOipko9TfSpa2
  6H4JOlMyfZFl0PCJwkByS0xZFJ2sTo3Gkk488RQohhgt1I0onw

The AS needs to take the following steps beyond the processing rules defined in Section 2.1:¶

1. If applicable, the AS decrypts the request object as specified in JAR [I-D.ietf-oauth-jwsreq], section 6.1.¶

2. The AS validates the request object signature as specified in JAR [I-D.ietf-oauth-jwsreq], section 6.2.¶

3. If the client is a confidential client, the authorization server MUST check whether the authenticated client_id matches the client_id claim in the request object. If they do not match, the authorization server MUST refuse to process the request. It is at the authorization server's discretion to require the iss claim to match the client_id as well.¶

4. Authorization Request

The client uses the request_uri value returned by the authorization server as the authorization request parameter request_uri as defined in JAR.¶

  GET /authorize?request_uri=
    urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1

Clients are encouraged to use the request URI as the only parameter in order to use the integrity and authenticity provided by the pushed authorization request.¶

5. Authorization Server Metadata

If the authorization server has a pushed authorization request endpoint, it SHOULD include the following OAuth/OpenID Provider Metadata parameter in discovery responses:¶

pushed_authorization_request_endpoint : The URL of the pushed authorization request endpoint at which the client can post an authorization request and get a request URI in exchange.¶

6. Security Considerations

7. Acknowledgements

This specification is based on the work towards 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, Joseph Heenan, and Takahiko Kawasaki for their valuable feedback on this draft.¶

8. IANA Considerations

This specification requests registration of the following value in the IANA "OAuth Authorization Server Metadata" registry of [IANA.OAuth.Parameters] established by [RFC8414].¶

Metadata Name:

pushed_authorization_request_endpoint¶

Metadata Description:

URL of the authorization server's pushed authorization request endpoint¶

Change Controller:

IESG¶

Specification Document(s):

[[ this document ]]¶

Appendix A. Document History

[[ To be removed from the final specification ]]¶

-01¶

• Use the newish RFC v3 XML and HTML format¶

• Added IANA registration request for pushed_authorization_request_endpoint¶

• Changed abbrev to "OAuth PAR"¶

-00 (WG draft)¶

• Reference RFC6749 sec 2.3.1 for client secret basic rather than RFC7617¶

• further clarify that a request object JWT contains all the authorization request parameters while client authentication params, if applicable, are outside that JWT as regular form encoded params in HTTP body¶

-01¶

• List client_id as one of the basic parameters¶

• Explicitly forbid request_uri in the processing rules¶

• Clarification regarding client authentication and that public clients are allowed¶

• Added option to let clients register per-authorization request redirect URIs¶

• General clean up and wording improvements¶

-00¶

• first draft¶

Authors' Addresses