Generation Of Client Assertion

If you are using a certified OIDC Relying Party library, the generation of client assertion will be handled by the library, as long as you specify that the private_key_jwt method is used for authentication.

Overview

When your backend calls our APIs, you will need to generate a client assertion to authenticate yourself. The generation of this client assertion should be done using the private_key_jwt mechanism specified in the OIDC specifications. This mechanism involves you building a client assertion by signing a JWT using one of your signing keys defined in your JWKS.

Client assertions need to be sent in the Pushed Authorization Request and the Token Request.

Generation of JWT

To reduce complexity, we recommend that you use a JWT library to perform the JWT encoding and signing on your behalf, instead of implementing this on your own. You may refer to this list to look for a suitable library for your programming language.

The JWT must have the structure outlined below.

JWT Header

The JWT header should contain the following parameters:

Parameter	Description	Data Type
alg	The signature algorithm that you are using to sign this JWT	One of the following strings: ES256 ES384 ES512
typ	The type of this JWT	Must be the string JWT
kid	The kid of the signing key that you are using to sign this JWT header. If this is not provided, we will test against all of the signing keys in your JWKS when attempting to verify the signature.	String, optional

Sample JWT header

{
  "typ" : "JWT",
  "alg" : "ES256",
  "kid" : "my_key_id_01"
}

JWT Payload

The JWT payload should contain the following claims:

Claim	Description	Data type
sub	The client ID of your registered client, provided by Singpass during app onboarding.	A 32-character case-sensitive alphanumeric string.
aud	This should be the issuer identifier of our authorization server. You can obtain this value from the issuer field in the OpenID configuration of our authorization server.	String
iss	The client ID of your registered client, provided by Singpass during app onboarding.	A 32-character case-sensitive alphanumeric string.
iat	The unix timestamp, in seconds, at which you generated this JWT.	Number
exp	The unix timestamp, in seconds, on or after which this JWT must not be accepted by us for processing. Note also that this must be less than or equal to 2 minutes after iat.	Number
jti	A unique identifier for this token. This identifier must only be used once. You should generate a new jti value for every request	String
code	The authorization code issued by us, obtained from the redirect URL in the previous step.	A base64url-encoded string.

Sample JWT Payload

{
  "sub": "T5sM5a53Yaw3URyDEv2y9129CbElCN2F",
  "aud": "https://id.singpass.gov.sg/fapi",
  "iss": "T5sM5a53Yaw3URyDEv2y9129CbElCN2F",
  "iat": "1756785377",
  "exp": "1756785493",
  "code": "XcyzlSeX1hIyJFlstxsSF_UeXC5DtiYkFgJ8VVx52mg"
}

Sample Signed JWT

eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjY3NTUxZWE2ZWE2NDk2ZmZiMWRkZmI4YTFhM2FlYjA0In0.eyJzdWIiOiJUNXNNNWE1M1lhdzNVUnlERXYyeTkxMjlDYkVsQ04yRiIsImF1ZCI6Imh0dHBzOi8vaWQuc2luZ3Bhc3MuZ292LnNnL2ZhcGkiLCJpc3MiOiJUNXNNNWE1M1lhdzNVUnlERXYyeTkxMjlDYkVsQ04yRiIsImlhdCI6IjE3NTY3ODUzNzciLCJleHAiOiIxNzU2Nzg1NDkzIiwiY29kZSI6IlhjeXpsU2VYMWhJeUpGbHN0eHNTRl9VZVhDNUR0aVlrRmdKOFZWeDUybWcifQ.fQMHTVNeCsa_mK6pmfjfi0rxERxDtu6eiMFkkpFdQrirc3u9LxP1_-E_7yIalIhmot1NdBQxbA9s_VztlQUhTQ