Skip to content
Connect2id

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, obtain an opaque URI handle for them, 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.

PAR is specified in this draft and supported since v8.0.

2. The PAR endpoint URL

The PAR endpoint URL can be found out from the server metadata endpoint and looks like this:

https://[base-server-url]/par

3. Client authentication

Confidential clients must authenticate themselves to the Connect2id server with their registered credentials for the token endpoint in order to make a PAR request. Clients registered for client_secret_basic authentication submit it in the Authorization header. Clients registered for client_secret_post, client_secret_jwt and private_key_jwt authentication include it in the request body. Clients registered for self_signed_tls_client_auth submit their client X.509 certificate with the HTTP request.

Public clients (that have not been issued a credential) will be identified by the client_id parameter of the authorisation request.

4. Web API overview

Resources
Representations Errors

4. Resources

4.1 /par

4.1.1 POST

Submits the OAuth 2.0 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.

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.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Missing client authentication"
}

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