Sign with Singpass
Singpass Developer DocsAsk a Question
  • START HERE
    • Overview of Sign
    • How do our Digital Signatures work?
    • Frequently Asked Questions
  • FOR USERS
    • How to sign
    • Verifying Sign with Singpass Signatures
      • Loading Singpass Root Signing Certificate
  • FOR RELYING PARTIES
    • Use Cases
    • Getting Started
      • How to Onboard our API
      • Digital Signing Partners
        • Docusign
        • Tungsten Automation
        • OneSpan
        • Tessaract Technologies Pte Ltd
        • Netrust Pte Ltd
        • Modus Consulting
        • Redoc.co by Real Estate Doc Pte Ltd.
        • CrimsonLogic
        • Zoho Sign
        • Securemetric Technology Pte. Ltd.
        • Rently Pte. Ltd.
    • API Documentation
      • Document Signing V3
        • Initiate Sign Request
        • Redirect From Sign with Singpass
        • Accept Success Signing Webhook
        • Get Signing Result
        • JWKS Specification
        • Sign Portal
      • Document Signing V1
      • Transaction Signing
        • Embedding Singpass JS
        • Init Transaction Signing
        • Exchange Transaction Signature
    • UX Guidelines
      • User Journey Illustration
    • Support
Powered by GitBook
On this page
  • JWKS Endpoint requirements for RP
  • Key requirements:
  • Example
  • Key Rotation Best Practices
  • Service Level Expectations
  • Sign with Singpass JWKS
  • URLs
  • Cache and key rotation

Was this helpful?

  1. FOR RELYING PARTIES
  2. API Documentation
  3. Document Signing V3

JWKS Specification

PreviousGet Signing ResultNextSign Portal

Last updated 6 days ago

Was this helpful?

JWKS Endpoint requirements for RP

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.

is a useful open-source tool to generate different types of JWK for signing and encryption; compliant with Singpass's broad requirements on structure. While we DO NOT suggest this as a secure way to generate your real keypair (including private key); this can be a useful tool to understand how JWK works; and how it is represented for signing and encryption purposes; while you are reviewing against our supported algorithms below.

Key requirements:

  • 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)

Example

{
    "keys": [
        {
            "kty": "EC",
            "use": "sig",
            "crv": "P-256",
            "kid": "6X_-_oLSH0DQLtz16o-NTKcm0lG0J-VDGHOz6tPx0Jc",
            "x": "1tR88zrGoPUV-Fr4bh_9NR-mDhC9rLswDp85hkbKBT0",
            "y": "1vYh1M53NK_b7l9Y-1FgCENOp6Fl9StVVLr3KqK_Ka8",
            "alg": "ES256"
        }
    ]
}

Key Rotation Best Practices

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.

Service Level Expectations

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.

Sign with Singpass JWKS

Public keys returned from this endpoint could be in random sequence or rotated for security enhancement.

URLs

Environment
URL

Staging

Production

Cache and key rotation

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 .

mkjwk.org
rfc7517#section-4.2
rfc7517#section-4.5
here
https://static.staging.sign.singpass.gov.sg/.well-known/keys.json
https://static.app.sign.singpass.gov.sg/.well-known/keys.json