Using Request Parameter

Overview

The Pushed Authorization Request (PAR) endpoint allows clients to securely send authorization parameters such as client_id, scope, redirect_uri, and others in a compact JWT (JSON Web Token) format. This allows the client to generate a request_uri that can later be used with the /oidc/auth endpoint to initiate the authentication process.

What is the request Parameter?

The request parameter is an optional parameter used to send a signed JWT containing the authorization request details. By using the request parameter, you bundle all necessary authorization parameters (e.g., client_id, scope, redirect_uri, etc.) into a single JWT, which is sent securely to the /oidc/request endpoint.

This approach has several benefits:

• Compact and Secure: It avoids sending parameters like client_id, scope, or redirect_uri in plaintext in the body or query string, reducing the risk of parameter tampering and exposure.
• Signed JWT: The JWT is signed by the client using its private key, ensuring that the request is authentic and the data hasn't been altered in transit.

How Does the request Parameter Work?

When the client wants to initiate an OIDC authentication request, instead of including each parameter individually in the request body, the client creates a signed JWT that includes all the required parameters. This JWT is then included in the request parameter of the /oidc/request endpoint.

Once the signed JWT is sent, the server validates the JWT and, if successful, returns a request_uri that can be used with the /oidc/auth endpoint to initiate the authentication process.

Parameters Included in the request JWT

The JWT included in the request parameter typically contains the following parameters:

Required Fields

• iss (Issuer): The entity that issued the JWT (i.e., the client). This is typically the client_id.
• aud (Audience): The intended recipient of the JWT, which is the authorization server that will process the request.
• client_id: The client’s unique identifier.
• scope: The scopes being requested (must include openid).
• redirect_uri: The redirect URI to which the authorization server will send the response.
• response_type: The type of response the client expects (e.g., code, id_token).
• state: A random value used to maintain state between the request and the callback (helps prevent CSRF attacks).
• nonce: A security value to prevent replay attacks.

Optional Fields

• claims: Specific claims requested by the client for inclusion in the ID token.
• client_assertion: Client's assertion used for authentication with the authorization server (if applicable).
• client_assertion_type: The type of assertion, typically urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

When to Use the request Parameter

Use the request parameter when you want to:

1. Securely bundle authorization parameters: Instead of transmitting sensitive parameters like client_id or scope in plaintext, you can bundle them in a JWT, which is signed and therefore protected.
2. Minimize the risk of parameter tampering: The signed JWT ensures the integrity of the request parameters, preventing any alterations in transit.
3. Reduce the size of the request: Rather than sending multiple parameters individually, the request parameter consolidates them into a single signed JWT, reducing the overall size of the request.
4. Use the request_uri to initiate authentication: The request_uri generated after the /oidc/request request can be used in the /oidc/auth endpoint to start the authentication flow.

Example of a request JWT

The JWT in the request parameter could look something like this (note: this is an example payload, and the actual JWT will be signed by the client):

{
  "iss": "67e5c1ce-1a3b-4ca8-a2d8-49ab822dbc24",         
  "aud": "https://auth.example.com",                    
  "client_id": "67e5c1ce-1a3b-4ca8-a2d8-49ab822dbc24",
  "scope": "openid id:1ffe704d39629a929c8e293880fb449a",
  "redirect_uri": "http://localhost:3001",
  "response_type": "code",
  "state": "random-state",
  "nonce": "random-nonce"
}

 

Benefits of Using the request Parameter

• Security: The signed JWT ensures that the request parameters are protected against tampering.
• Simplicity: By using the request parameter, you don't need to manually specify individual parameters in the body of the request.
• Compactness: Reduces the size of the authorization request, which can be beneficial in scenarios where you have many parameters.
• Flexibility: The client has full control over what is included in the JWT, including optional fields like claims, state, and nonce.

What Happens After Using the request Parameter?

Once the client sends a signed JWT in the request parameter to the /oidc/request endpoint, the server validates the JWT. If the request is valid, the server responds with a request_uri and an expiration time. This request_uri can then be used in the /oidc/auth endpoint to initiate the authentication flow.

Conclusion

The request parameter is a powerful and secure way for clients to submit OIDC authentication requests in a compact and signed JWT format. By using this approach, you enhance the security of your request and simplify the process by reducing the need for multiple parameters in the body of the request.