Table of Contents
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.
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.
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.
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.
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"}'
{
"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 .
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:
Make the necessary changes and click Save Changes to apply the configuration.
You can make PAR mandatory for a specific client, even if the Authlete service is not configured to require it. To enable this:
This setting ensures that the client must use PAR, overriding the service-level configuration.
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:
These settings define how clients authenticate when accessing the token endpoint.
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-----"]}'