Setup JSON Web Key Store (JWKS)

Singpass uses JSON Object Signing and Encryption (JOSE) standards to ensure the security and integrity of data transmitted during authentication and authorization processes. The technologies involved signing using JSON Web Signature (JWS) and optionally encrypted using JSON Web Encryption (JWE).

The relying party (RP) is expected to generate a set of asymmetric private and public keys and provide the public keys to Singpass in JSON Web Key (JWK) format. JWK format provides a standard JSON representation for cryptographic keys which will be used in the following (non-exhaustive) scenarios in the later steps:

• Signature JWK used to verify the signature of the client assertion JWT presented during the token request

• Encryption JWK is used to encrypt an ID token. This is mandatory if the client’s profile requires both UUID and NRIC

Mkjwk is an example of an online key generator. 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

Sample Guide on generating keys via Mkjwk.

Step 1: Generate Public Keys for Signing

• Generate a set of asymmetric private and public keys for signing. The signature JWK should have the following attributes:

• Must have key ”use” of value ”sig”. Ref
• Must have key “kid” field with a key id. Will be used by Singpass to select the relevant key to verify the client assertion. Ref
• Must have key “kty” of value “EC” key

• Must have key “crv” of value: P-256, P-384 or P-521

Below is an example of an EC signing key using P-256 and a key ID "sig-2024"for kid generated via Mkjwk.

Do not use these sample signing keys for actual integration as the private key has been exposed.

{
    "kty": "EC",
    "use": "sig",
    "crv": "P-256",
    "kid": "sig-2024",
    "x": "2Zr5WjsGWZ9yYwZb7gF3ZplnCe7sGHQrjgOI4G02FaA",
    "y": "nOSqDj_udpR9HtyySsha8_PPfGS6gW6n0yf3PDsUsjY"
}

Step 2: Generate Public Keys for Encryption

• Generate a set of asymmetric private and public keys for encryption. This is mandatory only if the client's profile requires both UUID and NRIC. Else can proceed to step 3.

• Must have key ”use” of value ”enc”. Ref
• Must have key “kid” field with a key id. Will be used by Singpass to select the relevant key to verify the client assertion. Ref
• Must have key “kty” of value “EC” key

• Must have key “crv” of value: P-256, P-384 or P-521. Ref
• Must have key “alg” of value: ECDH-ES+A128KW, ECDH-ES+A192KW, or ECDH-ES+A256KW. Ref

Below is an example of an EC encryption key using P-256, alg ECDH-ES+A128KW, and a key ID "enc-2024" for kid generated via Mkjwk.

Do not use these sample signing keys for actual integration as the private key has been exposed.

{
    "kty": "EC",
    "use": "enc",
    "crv": "P-256",
    "kid": "enc-2024",
    "x": "FsoBwfsC92QlhFyrcyn4mO3fwWJQZpSUlBUWfssgAy4",
    "y": "SNhy7ce6Bn5ynr1dumR2GjFfQ0K1cp11hZfNm339PF0",
    "alg": "ECDH-ES+A128KW"
}

Step 3: Verify the generated key pairs

Use Singpass JWKS Verifier to verify whether the keys generated meet Singpass's requirements.

The JWKS verifier can only validate the JWK if it's provided in a valid JSON format. JSON Formatter is an example of an online JSON formatter.

• Paste the keys in the following format to the JWKS verifier:

Example of Both Signature and Signing JWK

{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "crv": "P-256",
      "kid": "sig-2024",
      "x": "dzYJGhmkHRb4W1dM-Ytpv9SKdN5GKxgiboUR4BsMuVg",
      "y": "U8Fx5cXXSx4W0ii4j8gIYyM9fgLx98WSobxBYYBw-MU",
      "alg": "ES256"
    },
    {
      "kty": "EC",
      "use": "enc",
      "crv": "P-256",
      "kid": "enc-2024",
      "x": "l8TIMVKWVywTW3nKKLgswdV3vyyx9RydPMQs5boB0aQ",
      "y": "8zE2HqRfkfIIhHIA0I-VTgV8gQl-_AWDqJw_RbFEkR8",
      "alg": "ECDH-ES+A128KW"
    }
  ]
}

• Click Verify to verify the JSON Web Key Set (JWKS) provided meets the Singpass's requirement.

If you passed the verification, your JSON Web Key Sets (JSON) are ready to be used for the later steps.

Next steps

• Configure your Singpass Application via the Singpass Developer Portal
• If you have already configured it, proceed to call the Authorization Endpoint