JWKS Specification
Last updated
Was this helpful?
Last updated
Was this helpful?
The client must provide the public key(s) during onboarding by host the JWKS on a publicly accessible URL. This endpoint must be compatible with Singpass's Service Level Expectations. These public keys will be used to verify the signature of the token in Initiate Sign Request and Get Signing Result.
RP are allowed to provide multiple keys on the JWKS url.
Must have key use of value sig per
Must contain a key ID in the standard kid field per
Will be used by Singpass to select the relevant key to verify the client assertion
Must be an EC key, with curves: P-256, P-384 or P-521 (NIST curves, aka secp256r1, secp384r1, secp521r1 respectively)
Our server cache the key for 1 hour. When performing key rotation, do ensure that:
New key should be added to the JWKS at least 1 hour before it is used to sign new JWTs.
Old key must remain available for at least 1 hour after stop signing with it, ensuring that previously issued JWTs can still be validated.
Sign requires that any JWKS is published on an endpoint that
is served behind HTTPS on port 443 using a TLS server certificate issued by a standard publicly verifiable CA issuer (no private CAs), with complete cert chain presented by the server;
is publicly accessible (no IP whitelisting, mTLS or other custom HTTP header requirements outside standard HTTP headers such as Content-Type, Accept);
is able to respond in a timely fashion with respect to the below configuration.
Per try timeout: 3s
Max attempts: 3
Cache duration for retrieved JWKS: 1h
Note: While the above is a technical requirement; the user experience of your users may be affected if we are unable to retrieve your JWKS in a timely fashion upon our cache expiry due to slower token exchanges with your backend. We recommend aiming for this response to be as fast as possible based on an in-memory cache; or simple static asset retrieval.
Public keys returned from this endpoint could be in random sequence or rotated for security enhancement.
Staging
Production
For varying reasons, keys used for signing can and will be rotated/changed with no defined schedule, and at the full discretion of Singpass. When a key rotation happens, the new key will be available from the JWKS endpoint and will have a different kid value. The new kid value will be reflected in all the new JWTs signed by Singpass. In such cases, cached copies of Singpass public keys must be refreshed by re-invoking the JWKS endpoint.
If the validation of the Singpass signature fails, re-fetch from the JWKS endpoint once for that validation.
Please read through the list of DON’Ts below:
Do not assume the position of a signing key among the list of the returned keys.
Do not validate Singpass signatures using a hardcoded public key. Always determine the correct key (for signature verification) by inspecting the kid from the JWS header, and use it to retrieve the public key from our JWKS endpoint.
Do not cache only 1 key. Caching should be done for the entire JWKS.
RP can verify the signature of a JWT from Sign with Singpass by acquiring the signing public key from this endpoint. More information about a JSON Web Key (JWK) endpoint can be found .