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, 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

It can be found out from the pushed_authorization_request_endpoint advertised in the Connect2id server metadata and has this form:

https://[base-server-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 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