Products » Connect2id server » Documentation » Standard endpoints »

Pushed authorisation requests (PAR)

1. Back-channel submission of authorisation parameters

The Pushed Authorisation Request (PAR) endpoint gives OAuth 2.0 clients a back-channel to post the parameters of an authorisation request to the Connect2id server, to obtain an opaque URI handle for them, and then continue with the front-end redirection to the authorisation endpoint as usual.

Introducing an extra back-end call to submit the authorisation parameters has three benefits:

  • Frees the authorisation request from any browser URL length limits. They can become an issue with complex requests, such as RAR.

  • Keeps the parameters confidential between client and server. Regular requests expose them in the URL query string and hence to the browser, the end-user and logs.

  • Confidential OAuth clients will be authenticated up-front and the request parameters will be checked for errors, before sending the end-user to the authorisation endpoint for login and consent.

A client can be forced to use the PAR endpoint by setting a special registration parameter.

PAR is specified in RFC 9126 and supported since v8.0.

2. The PAR endpoint URL

It is advertised in the pushed_authorization_request_endpoint server metadata and has this form:

[issuer-url]/par

3. Client authentication

Confidential clients must authenticate and public clients must identify themselves as they would at the token endpoint.

4. Web API overview

Resources
Representations Errors

4. Resources

4.1 /par

4.1.1 POST

Submits the authorisation request parameters to obtain a request_uri handle for use at the authorisation endpoint.

Header parameters:

  • [ Authorization ] Used for HTTP basic authentication of the client.

  • Content-Type Must be set to application/x-www-form-urlencoded.

  • [ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} The PAR response.

Errors:

Example PAR request for a confidential client registered for client_secret_basic authentication:

POST /par HTTP/1.1
Host: c2id.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

response_type=code
&scope=openid%20email
&client_id=fcb5e4f1
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Example PAR request for a public client with PKCE:

POST /par HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

response_type=code
&scope=openid%20email
&client_id=fcb5e4f1
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&code_challenge_method=S256
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

Example response with a request URI to complete the authorisation:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "request_uri" : "urn:ietf:params:oauth:request_uri:OsL1Z3VqIxAT9R77wB7KCw.5-cQUNt9DygE4XxnYjysnw",
  "expires_in"  : 60
}

5. Representations

5.1 PAR response

JSON object with members:

Example:

{
  "request_uri" : "urn:ietf:params:oauth:request_uri:OsL1Z3VqIxAT9R77wB7KCw.5-cQUNt9DygE4XxnYjysnw",
  "expires_in"  : 60
}

5.2 PAR error

JSON object with members:

  • error An error code which can take one of the following values (if a PAR validator is installed it may set its own):

    • invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
    • invalid_client Client authentication failed, due to missing or invalid client credentials.
    • unauthorized_client The client is not registered for the requested response_type.
    • unsupported_response_type The server doesn't support the requested response_type.

  • [ error_description ] Optional text providing additional information about the error that occurred.

  • [ error_uri ] Optional URI for a web page with information about the error that occurred.

Example PAR error:

{
  "error"             : "invalid_request",
  "error_description" : "Invalid redirect_uri parameter: Not an URI"
}

6. Errors

400 Bad Request

Invalid request. See PAR error codes for more information.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Invalid redirect_uri parameter: Not an URI"
}

401 Unauthorized

The request was denied due to an invalid or missing client authentication. See PAR error codes for more information. The error_description is a checklist of all possible causes why the client authentication may have failed. The client_auth_id can be used to identify the exact cause.

Example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Invalid client: Possible causes may be missing /
                         invalid client_id, missing client authentication,
                         invalid or expired client secret, invalid or expired
                         JWT authentication, invalid or expired client X.509
                         certificate, or an unexpected client authentication
                         method",
  "client_auth_id"    : "cgXB4EyYViWPt6g2"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error