# Client Assertion JWT

Corppass supports **JWT-based client authentication** using the mechanism defined in [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523). Clients must generate and sign a JWT — known as a **client assertion** — and present it to Corppass when authenticating at the [PAR](https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/2.-authorization-endpoint) or [Token](https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/3.-token-endpoint) endpoints.

This method is especially suitable for **confidential clients** that can securely manage private keys.

### When to Use

A client assertion JWT must be used whenever the client authenticates with Corppass, including during:

* [Pushed authorization requests](https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/1.-pushed-authorization-request-par-endpoint)
* [Token requests](https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/3.-token-endpoint)

The JWT is passed as two fields:

```markup
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<signed-JWT>
```

{% hint style="warning" %}
Corppass **strongly recommends** clients to use **libraries** to handle JWTs instead of attempting it themselves.&#x20;

See [here](https://www.jwt.io/libraries) for an overview of JWT libraries that clients can use to do so.
{% endhint %}

## JWT Structure

A signed client assertion JWT follows the typical JWS format:

```markup
<base64url-encoded header>.<base64url-encoded payload>.<base64url-encoded signature>
```

### JWT Header Example

```json
{
    "typ" : "JWT",
    "kid": "d591e152-886e-46cc-aa70-36a4431162a6",
    "alg" : "ES256"
}
```

<table><thead><tr><th width="217">Field</th><th>Description</th></tr></thead><tbody><tr><td>alg</td><td>The algorithm used for signing the JWT. Supported values are <code>ES256</code>, <code>ES256K</code>, <code>ES384</code>, and <code>ES512</code>.</td></tr><tr><td>kid</td><td>The Key ID associated with the signing key, matching the JWK provided during onboarding.</td></tr><tr><td>typ</td><td>The type of the token, typically set to <code>"JWT"</code>.</td></tr></tbody></table>

### JWT Claims (Payload) Example

```json
{
  "iss": "your-client-id",
  "sub": "your-client-id",
  "aud": "https://id.corppass.gov.sg/token",
  "jti": "random-uuid-12345",
  "exp": 1712486400,
  "iat": 1712486100
}
```

<table><thead><tr><th width="132.19140625">Claims</th><th width="117.03515625">Required</th><th>Description</th></tr></thead><tbody><tr><td>sub</td><td>Yes</td><td>The client ID of the registered client.</td></tr><tr><td>aud</td><td>Yes</td><td>The intended audience for this JWT. Must match the <code>issuer</code> field (<code>iss</code>) from the OpenID Discovery endpoint.</td></tr><tr><td>iss</td><td>Yes</td><td>The client ID of the registered client.</td></tr><tr><td>iat</td><td>Yes</td><td>The time at which the JWT was issued.</td></tr><tr><td>exp</td><td>Yes</td><td>The expiration time after which the JWT is no longer valid.</td></tr><tr><td>jti</td><td>Yes</td><td>The unique identifier for the JWT, used to prevent token reuse.</td></tr></tbody></table>

{% hint style="warning" %}

## **Token Maximum Lifetime Requirement**

Corppass will **reject** client assertion JWTs if the **maximum token lifespan** is more than **2 minutes.** This means that the `exp` claim must be **within 2 minutes or less** than the `iat`.&#x20;

This follows the best practices outlined in [Section 3 of RFC 7523](https://www.rfc-editor.org/rfc/rfc7523#section-3). RPs should ensure tokens are short-lived and avoid excessive clock skew.&#x20;
{% endhint %}