Client Assertion JWT

Corppass supports JWT-based client authentication using the mechanism defined in RFC 7523. Clients must generate and sign a JWT — known as a client assertion — and present it to Corppass when authenticating at the PAR or Token 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:

• Token requests

• Pushed authorization requests

The JWT is passed as two fields:

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

Corppass strongly recommends clients to use libraries to handle JWTs instead of attempting it themselves.

See here for an overview of JWT libraries that clients can use to do so.

JWT Structure

A signed client assertion JWT follows the typical JWS format:

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

JWT Header Example

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

Field	Description
alg	The algorithm used for signing the JWT. Supported values are ES256, ES256K, ES384, and ES512.
kid	The Key ID associated with the signing key, matching the JWK provided during onboarding.
typ	The type of the token, typically set to "JWT".

JWT Claims (Payload) Example

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

Claims	Required	Description
sub	Yes	The client ID of the registered client.
aud	Yes	The intended audience for this JWT. Must match the issuer field (iss) from the OpenID Discovery endpoint.
iss	Yes	The client ID of the registered client.
iat	Yes	The time at which the JWT was issued.
exp	Yes	The expiration time after which the JWT is no longer valid.
jti	Yes	The unique identifier for the JWT, used to prevent token reuse.

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.

This follows the best practices outlined in Section 3 of RFC 7523. RPs should ensure tokens are short-lived and avoid excessive clock skew.