Skip to main content
This page is for Authlete 2.x. For current (3.0) documentation, see this page.

​
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, in advance of sending conventional one (via a user agent indirectly), to an authorization server. The PAR specification defines an 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://api.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Basic ************' \
--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

Under the Service Owner Console, the administrator can configure an Authlete service to work as a backend of the PAR EP on the authorization server, for how long a pushed authorization request will be valid, and if the usage of PAR is mandatory for every client. Screen_Shot_2021-07-26_at_20 Pushed Authorization Request config on service level You can configure PAR to be mandatory for a specific client, even if the Authlete service is configured not to require it. Under “Authorization” tab of the client in the Developer Console, you find the parameter below: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. Under the Developer Console, you can find “Client Authentication Method” under “Authorization” tab of each client.\ 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://api.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Basic MjQzNDE1ND*********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://api.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Basic MjQzNDE1ND*********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://api.authlete.com/api/pushed_auth_req' \
--header 'Authorization: Basic MjQzNDE1ND*********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-----"]}'