Skip to main content
For Authlete 2.x documentation, see 2.x version.

​
Introduction

RFC 9126: OAuth 2.0 Pushed Authorization Requests (PAR) is one the most impactful security enhancements to the OAuth2 framework. It allows clients to “push” (submit directly) content of an authorization request to the authorization server in advance, instead of sending it conventionally through a user agent. The PAR specification defines a new endpoint (PAR EP) that accepts the authorization request content. The PAR EP sends back an identifier (request_uri) so that the client can include it in the following authorization request. The segregation of the provisioning of the authorization request content from the authorization request creates one more option to enhance the security, for instance: SPAs (single page applications) can rely on server side to create the authorization request content without disclosing any detail of the authorization request to the browser, or mobile apps can create and send the authorization request content before forwarding it to browser. ​​This article describes an overview of PAR support in Authlete, and instructions to enable it.

​
Implementing PAR EP

In order to support PAR, you have to implement a PAR EP in an authorization server (or an OP on OIDC parlance), and configure PAR settings in Authlete. The PAR EP of the authorization server can employ /pushed_auth_req API of Authlete as a backend. This API has the same design principle as the other endpoints: it allows your authorization server to simply forward the pushed authorization request from a client to Authlete. puahed-authorization-requests_en Authorization code flow using Pushed Authorization Requests Authlete’s /pushed_auth_req API expects the same payload of /auth/authorization API, plus the client authentication. The /pushed_auth_req API will provide content of a pushed authorization response (responseContent) to be sent back to the client. The content includes a request_uri so that the client can use it on making an authorization request.

​
Sample request and response

The authorization request content pushed from the client to the PAR EP is similar to ones in a usual request to an authorization endpoint, except that the client sends the authorization request using POST method and application/x-www-form-urlencoded media type. 
POST /as/par HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

response_type=code&
client_id=3280859750204&
redirect_uri=https%3A%2F%2Fmobile.example.com%2Fcb&
code_challenge=W78hCS0q72DfIHa...kgZkEJuAFaT4&
code_challenge_method=S256
The sample request below, shows an interaction between an authorization server and Authlete’s /pushed_auth_req API. The authorization request content, which initiates an authorization code flow with PKCE in this example, should be provisioned by a client. 
The response from Authlete is the action “CREATED” and a requestUri, meaning that the authorization request was provisioned with an identifier as the requestUri value. Authlete also creates responseContent, whose value is intended to be used as a pushed authorization response from the PAR EP to the client.
  • Request
curl --request POST 'https://us.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Bearer ************' \
--header 'Content-Type: application/json' \
--data '{
    "parameters": "response_type=code&
                   client_id=3280859750204&
                   redirect_uri=https%3A%2F%2Fmobile.example.com%2Fcb&
                   code_challenge=W78hCS0q72DfIHa...kgZkEJuAFaT4&
                   code_challenge_method=S256",
    "clientId": "3280859750204"}'
  • Response
{
    "type": "pushedAuthReqResponse",
    "resultCode": "A245001",
    "resultMessage": "[A245001] Successfully registered a request object for client (3280859750204), URI is urn:ietf:params:oauth:request_uri:UymBrux4ZEMrBRKx9UyKyIm98zpX1cHmAPGAGNofmm4.",
    "action": "CREATED",**    "requestUri": "urn:ietf:params:oauth:request_uri:UymBrux4ZEMrBRKx9UyKyIm98zpX1cHmAPGAGNofmm4",**    "responseContent": "{\"expires_in\":600,\"request_uri\":\"urn:ietf:params:oauth:request_uri:UymBrux4ZEMrBRKx9UyKyIm98zpX1cHmAPGAGNofmm4\"}"
}
Using the request_uri returned from the PAR EP, the client sends an authorization request to the authorization server via a user agent. On receiving the request, the authorization server makes a request to Authlete’s /auth/authorization API as follows. 
curl --request POST 'https://api.authlete.com/api/auth/authorization' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic *************' \
--data '{
    "parameters":
        "client_id=3280859750204&
        request_uri=**urn:ietf:params:oauth:request\_uri:UymBrux4ZEMrBRKx9UyKyIm98zpX1cHmAPGAGNofmm4"
}'
A response from Authlete is the same as the regular authorization request. A ticket will be created - check the details under the note describing Authlete ticket .

​
PAR configuration on Authlete

Log in to the Authlete Management Console and open Service Settings for your Authlete service to configure it as the backend for the PAR endpoint on the authorization server. In the Pushed Authorization Request (PAR) tab, you can:
  • Specify whether the usage of PAR is mandatory for every client by toggling the Require PAR option.
  • Configure how long a pushed authorization request remains valid (set the duration in seconds).
Make the necessary changes and click Save Changes to apply the configuration. Screen_Shot_2021-07-26_at_20 Pushed Authorization Request config on service level You can make PAR mandatory for a specific client, even if the Authlete service is not configured to require it. To enable this:
  1. Open Client Settings for your client.
  2. Navigate to Endpoints > General > Pushed Authorization Request.
  3. Toggle the Require PAR switch to enable it.
This setting ensures that the client must use PAR, overriding the service-level configuration. Screen_Shot_2021-07-26_at_21 Flag to force a specific client to use pushed authorization request

​
Client authentication

An authorization server may authenticate clients on a PAR EP. Authlete applies authentication method settings for a token endpoint to the PAR EP as well. The mechanism is described in the following article. In the Service Settings under the Token tab, you can configure the supported Client Authentication Methods for the token endpoint. Select methods like PRIVATE_KEY_JWT or TLS_CLIENT_AUTH based on your requirements. To configure:
  1. Navigate to Endpoints > Token in Service Settings.
  2. Select the desired authentication methods under Supported Client Authentication Methods.
  3. Click Save Changes.
These settings define how clients authenticate when accessing the token endpoint. Screen_Shot_2021-07-28_at_20 Client authentication method on token and PAR endpoint for each client For the authentication method CLIENT_SECRET_BASIC, the client will be authenticated on the PAR EP using basic HTTP authentication. The authorization server will make a request to Authlete’s /pushed_auth_req API with the credentials submitted from the client, by using the “clientId” and “clientSecret” attributes (check snipped below). 
curl --location --request POST 'https://us.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Bearer c2JwsOb6ID8iCC5DN*********LWtv' \
--header 'Content-Type: application/json' \
--data-raw '{
    "parameters": "response_type=code%20id_token&client_id=3280859750204&redirect_uri=https%3A%2F%2Fserver.example.com%2Fcb&state=SOME_VALUE_ABLE_TO_PREVENT_CSRF&scope=openid&nonce=SOME_VALUE_ABLE_TO_PREVENT_REPLAY_ATTACK&code_challenge=GyeodZxSpq0iyjNbEQE6N96MxomMXYpYUkfuEpvQ3Js&code_challenge_method=S256",
    "clientId": "3280859750204",
    "clientSecret": "qfd0ScLHhD**************YDg"
}'
If the client is configured for a client certificate based authentication method, the request will be similar to the request below. 
curl --location --request POST 'https://us.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Bearer c2JwsOb6ID8iCC5DN*********LWtv' \
--header 'Content-Type: application/json' \
--data-raw '{
    "parameters":"response_type=code&client_id=....",
    "clientId":3282602314604,
    "clientCertificate":"\n-----BEGIN CERTIFICATE-----\nMIICnDCCAYSgAwIBAgIGAXqsMta0MA0GCSqGSIb3DQEBCwUAMA8xDTALBgNVBAMM\nBGtleTEwHhcNMjEwNzE1MjIwNDEwWhcNMjIwNTExMjIwNDEwWjAPMQ0wCwYDVQQD\nDARrZXkxMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAh517rALrL+I9\npvOpCVr9wuJ/TE3l3CndvE9oRrU2BpBYSn0LVnIT6anKgrYSJNP/YOkgHqUQQIoq\n0j7Uv7fiYL02OuAuVouOP3pxC1QiRGNInZkmYVJ0EsNz8Gft3JW7A9pUHc/Sx0P1\nTbN1hL9J5auasCNjUhd3GCB7bEJeIlez066qkUeZR/Jtpqdh9TVJrnBjEiihrcwL\nlixo4G5Y2Tg9vpjOCKgoL1tni6wbxY64BzksF2y10OEfvcwacmLBsMxHhN3l0qU2\nnbKbYKb2R0xRq8DU5woG0Rkbi5z6FRF4DLzpjig6vk6ENjwenHFYt8XMhulmSdnX\nGvDe2/BWYQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQABRsoLK5hn5DesBpnDCBfq\nZnyMiWyUbh8qmIhO5Ta6Hq/AeUSM16gqJqBsLQm6UllfsW30Qn9EwkCMG1Fb4g8t\n5TVigtvtVcTkn3H2Ib6EhtsB5Evs1U273W5Z/y7QUDrS2TahraKNKK2k81UbHhZf\nY1qyDMTK1+a+EAcuUaFOPsOzZo3Yxa2GDXQ8ZjHwk4E7tIri953P66gGHC3GNTy\n92hrXw8KgoIXJXKyZ5WeyziTIfAypnlI6EzUU\n-----END CERTIFICATE-----"
}'
In case of TLS_CLIENT_AUTH using PKI authentication - where Authlete can validate the client certificate chain against a list of root CAs - the authentication will be similar to the request below. 
curl --location --request POST 'https://us.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Bearer c2JwsOb6ID8iCC5DN*********LWtv' \
--header 'Content-Type: application/json' \
--data '{
   "parameters":"response_type=code&client_id=3289644915401&...",
   "clientId":3289644915401,
   "clientCertificate":"\n-----BEGIN CERTIFICATE-----\nMIIDmzCCAoOgAwIBAgI.....ftMPIhU1ocI0Uh9ObkPq5atK0lx\n39OTMXLj1kHxlf3RnoRo\n-----END CERTIFICATE-----",
   "clientCertificatePath":["\n-----BEGIN CERTIFICATE-----\nMIIE3TCCAsWgAwI.....9HEtxsOeIDWmILz453xtSBdorV7rN7QcEK6Hd62czruZtk/ItPjQMnB1moBT3d\n5g==\n-----END CERTIFICATE-----",
                            "\n-----BEGIN CERTIFICATE-----\nMIIFuDCCA6CgAwI.....FRVZqvemtV0gZM0C3tkDBQzGsb/KW\nnFWbOABBQequSMJN0MjWd+fkiDZAJq/X0Gw==\n-----END CERTIFICATE-----"]}'