PAR in a Nutshell

OAuth 2.0 Pushed Authorization Requests (PAR) is an OAuth 2.0 specification for the PAR endpoint that allows client applications to push the payloads of authorization requests to authorization server (in this case, Cloudentity) via direct requests to the PAR endpoint. In return, the client application receives a request URI that is used as a reference to the previously sent payload data in a subsequent call to the authorization server (Cloudentity).

When to Use PAR

PAR should be used by client applications that require the highest level of security. It is one of the prerequisites to be compliant with some of the profiles for FAPI security profile, as well as some of the profiles for Consumer Data Right (CDR) Australian Open Banking directive. Even if you are not pursuing FAPI or CDR certification, you should consider enabling PAR for your client applications to further enhance their security level.

PAR in Depth

With OAuth 2.0 or OpenID Connect, authorization request parameters are usually provided to authorization servers using URI query parameters via redirection in the user agent (typically, a browser), which presents some risks:

• There is no cryptographical integrity or authenticity protection involved and the access scope requested can be modified.

• Confidentiality of the request parameters cannot be ensured even when HTTPS protocol is used as the data passes through the user agent and can be leaked to the webserver logs or other sites via referrer.

• Authorization request URL can become too long for the user agent to be processed successfully.

The biggest benefit of Pushed Authorization Requests is solving the problems listed above. It improves the security of your requests by providing client applications with a secure mean for a confidential and integrity-protected authorization requests.

Cloudentity’s PAR Endpoint

Cloudentity’s /par endpoint is fully compliant with the OAuth 2.0 Pushed Authorization Requests specification. It is an HTTP API that accepts POST requests and uses the https scheme and the application/x-www-form-urlencoded format. It accepts all authorization requests parameters defined in the RFC6749 specification for the authorization endpoint and parameters provided by the extensions like Proof Key for Code Exchange (PKCE) or OpenID Connect (OIDC).

Client applications that send requests to Cloudentity’s PAR endpoint, must authenticate themselves using one of the Cloudentity’s client authentication methods but to the /par endpoint instead of the /token endpoint.

Requests sent to the /par endpoint reflect the requests sent to the Cloudentity’s /authorize endpoint as they share the same parameters like, for example, client_id, response_type, redirect_uri, and more. Requests to the /par endpoint, however, must also include parameters necessary for client authentication which depend on the chosen method of authentication. For example, with the client_secret_post method set for the client application, the request to the /par endpoint includes the client_id and the client_secret parameters.

Authorization Grant With PAR Flow

1. Client application sends a request to the Cloudentity’s /par endpoint.

   The request:

   • must contain the same parameters as it does when a request is sent to the Cloudentity’s OAuth 2.0 authorize endpoint.

   • The request must also contain the parameters used for client authentication method set for this client.

2. When the request reaches Cloudentity:

   1. Cloudentity authenticates the client in the same way as the client would be authenticated when making a call to the Cloudentity’s OAuth 2.0 token endpoint

      Client Authentication

      To learn more, see client authentication methods article.

   2. Cloudentity rejects the request if it contains the request_uri parameter.

      The request_uri parameter is used for getting client applications authorized. Cloudentity rejects requests to the PAR endpoint that contain the request_uri as allowing it would cause a conflict between the request_uri provided in the request and the request_uri received as a response parameter after making a successful call to the /par endpoint.

   3. Cloudentity validates the request as it would validate a request to the OAuth 2.0 authorize endpoint.

      For example, Cloudentity validates if the redirection URI matches the redirection URIs configured for the client application that is making a request to the /par endpoint. Among other checks, Cloudentity also validates if the client application is authorized to request the scope provided in the request.

      Policies Enforcement

      Even though Cloudentity performs validation of the request, the policies are not enforced for the /par endpoint. It means that, for example, if you have a policy for APIs that checks if your request contains a particular scope or header, this policy does not apply for the /par endpoint and its result is only evaluated when a call to the OAuth 2.0 authorize endpoint is made.

3. After a successful verification of the request, Cloudentity responds with the 201 HTTP status code and provides two response parameters:

   • Single-use request_uri that is corresponding to the authorization request to be posted.

   • expires_in which is a JSON number that represents the lifetime of your request URI. If the request URI expires, any request to the OAuth 2.0 authorize endpoint made using this URI is declined.

     PAR lifetime

     You can adjust your expiration time for your request URIs in your workspace authorization settings.

4. The client application can now make a request to the OAuth 2.0 authorize endpoint using the request URI that it received as the response when calling the /par endpoint.

Enforcing PAR

Pushed authorization requests can be enforced on the server (workspace) and/or client application level. If PAR is enforced on the workspace level, all client applications that are registered within this workspace must use pushed authorization requests. If PAR is not enforced on the server level, but is enforced for a particular application, only this application must use PAR.

Server Level Enforcement

1. Go to Auth Server > OAuth > General.

2. Under Pushed Authorization Requests (PAR), select Enforce PAR.

3. Optionally, you can also set a custom time-to-live for your request URIs.

4. Select Save changes.

Result

PAR is now enforced on the workspace level. All client applications registered within this workspace must make a call to the /par endpoint before requesting authorization.

Additionally, you cannot disable PAR enforcement for client applications in their settings. This means that all applications must use PAR, when it is enforced on the server level.

Demo Applications and PAR

If you had created a Demo Workspace and enabled the Demo application for this workspace, it stops working when you enforce PAR on the server level. Demo applications are not adapted for using pushed authorization requests.

Client Level Enforcement

1. Go to Applications > Clients > Your application > OAuth.

2. Under Pushed Authorization Requests (PAR), select Enforce PAR.

3. Optionally, you can also set a custom time-to-live for your request URIs.

4. Select Save changes.

Result

PAR is now enforced for your client application. From now on, your application must first make a request to the /par endpoint before requesting authorization.

Request Examples

You can test pushed authorization request using the examples provided below. Firstly, you need to meet prerequisites. Then, you are able to make a request to Cloudentity’s PAR endpoint and with the request URI provided in the response you are able to request authorization.

Prerequisites

1. Admin access to an Cloudentity tenant.

2. PAR enforced on the server level.

   Expiration time for request URIs

   For testing purposes, you can set a longer custom TTL for request URIs in your workspace PAR settings.

3. Client application created in a workspace of your choice.

   1. For the purpose of the request examples in this article, set your client application client authentication method to client_secret_post.

   2. Redirection URI is defined for your client application.

Authorize with PAR

1. Make the following POST request to the /par endpoint for your workspace:

   curl --location --request POST 'https://{tid}.us.authz.cloudentity.io/{tid}/{aid}/par' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'client_id={client_id}' \
   --data-urlencode 'client_secret={client_secret}' \
   --data-urlencode 'redirect_uri={redirect_uri}' \
   --data-urlencode 'response_type=code'
   

   The request contains the following parameter values that you should change:

   • {tid} which stands for the identifier for your tenant.

   • {aid} which stands for the authorization server (workspace) identifier.

   • {client_id} which value should be set to the client identifier of the client application making a pushed authorization request.

   • {client_secret} which value should be set to the client secret of the client application making a pushed authorization request.

   • {redirect_uri} which should be set to the redirection URI configured for the client application making the pushed authorization request.

   The client_id is a parameter required for the request to the OAuth 2.0 authorize endpoint. As you can see in the example, the request contains also the client_secret parameter. This parameter is included as the client application uses the client_secret_post client authentication method. Because you had provided the client identifier to fill the requirements for the authorization endpoint, you do not need to provide it once again to fill the requirements of the client_secret_post client authentication method. If you chose a different client authentication method, you must provide all parameters required by the method you chose.

   Expected response

   If the request is successful, you receive the response similar to the following:

   {"request_uri":"urn:ietf:params:oauth:request_uri:218swRPh4QX8ZfXKb413i936OxB","expires_in":120}
   

2. Edit the URL for the authorize endpoint so that it contains the request_uri and the client_id as request parameters. Find an example below:

   https://{tid}.us.authz.cloudentity.io/{tid}/{aid}/oauth2/authorize?client_id={client_id}&request_uri={request_uri}
   

   The URL contains the following parameter values that you should change:

   • {tid} which stands for the identifier for your tenant.

   • {aid} which stands for the authorization server (workspace) identifier.

   • {client_id} which value should be set to the client identifier of the client application that is to make the authorization request.

   • {request_uri} which value should be set to the request URI that you received as a response to a call to the /par endpoint, for example urn:ietf:params:oauth:request_uri:218swRPh4QX8ZfXKb413i936OxB.

3. Go to your browser and enter the URL that you have constructed in the second step.

   Result

   You are now presented with a login view for your tenant.

4. Log in to your tenant.

   Result

   After you log in to your tenant, you are taken to the redirection URI that you have configured for your client application. Your client application is now authorized. Notice how the URL now contains the authorization code that you can use to make a call to the Cloudentity’s OAuth 2.0 token endpoint.

   Below, you can find an example of a URL that you are redirected to:

   https://example.com/?code=G2etrHqokAerjQPOZw0RdPJzzHwkXhu-q91UCcrSNhY.SKvtouzqu6JZ1FEoU7yZIYDIQ7qD5thG9f_VMN9C9AM&scope=&state=
   

   In the example, you can see that the redirection URI for the client application is set to https://example.com. You can also find your authorization code, which, in this case, is set to:

   G2etrHqokAerjQPOZw0RdPJzzHwkXhu-q91UCcrSNhY.SKvtouzqu6JZ1FEoU7yZIYDIQ7qD5thG9f_VMN9C9AM
   

   As no specific scope was requested, the value for the scope parameter is empty.