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:
- The authorisation request parameters, together with any client authentication parameters.
Success:
Code:
200
Content-Type:
application/json
Body: {object} The PAR response.
Errors:
- 400 Bad Request with a PAR error code.
- 401 Unauthorised with a PAR error code.
- 500 Internal Server Error
- Other HTTP status codes are possible if a PAR validator is installed.
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:
request_uri The request URI handle to use at the authorisation endpoint.
expires_in The configured lifetime of the request URI, in seconds.
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