Singpass Developer Docs
Legacy Myinfo v3/v4
Legacy Myinfo v3/v4
  • Legacy Myinfo v3/v4
  • Data Catalog
  • Key Principles
  • Technical Specifications
    • Myinfo v4
      • Difference between v3 and v4
      • Technical Guidelines
      • Technical Concepts
        • OAuth 2.1 Concepts
        • Proof of Key Code Exchange (PKCE)
        • JSON Web Token (JWT)
        • Client Assertions
        • JSON Web Key Store (JWKS)
        • Demonstration of Proof-of-Possession (DPoP)
      • API Specifications
      • Tutorials
        • Tutorial 1: Myinfo Person sample Data
        • Tutorial 2: End-to-end Integration with Myinfo v4 APIs
      • Resources
        • Myinfo Connectors
        • Error Codes
      • FAQ
    • Myinfo v3
      • Technical Guidelines
      • API Specifications
      • Latest X.509 Public Key Certificate
      • Tutorials
        • Tutorial 1: Basic Person API
        • Tutorial 2: Using OAuth2
        • Tutorial 3: Implementing PKI Digital Signature
      • Resources
        • Myinfo Connectors
        • Error Codes
      • FAQ
Powered by GitBook
On this page
  • 1.JSON Web Token (JWT)
  • 2.JSON Web Signature (JWS)
  • 3.JSON Web Encryption (JWE)
  • 3.1 What is the JWE (JSON Web Encryption) Compact Serialization format?
  • 3.2 How can I decrypt the JWE?
  • 3.3 How does JWE library decrypt the JWE in detail?

Was this helpful?

  1. Technical Specifications
  2. Myinfo v4
  3. Technical Concepts

JSON Web Token (JWT)

PreviousProof of Key Code Exchange (PKCE)NextClient Assertions

Last updated 1 month ago

Was this helpful?

1.JSON Web Token (JWT)

JSON Web Tokens consist of three parts separated by dots (.), which are:

  • Header

  • Payload

  • Signature

Therefore, a JWT typically looks like the following: `xxxxx.yyyyy.zzzzz`

The header and the payload are Base64Url encoded. The signature is created using these two, a secret and the hashing algorithm being used (as specified in the header: ES256).

To parse the JWT, you can use one of the libraries listed in the for Token Signing/Verification section of .

2.JSON Web Signature (JWS)

The decrypted payload is signed in format, similar to the access_token.

  • The signature algorithm used is ES256.

You may download our Public JWKS from Myinfo JWKS URI for verification, after application is created during onboarding on the application details page upon login.

Copy to clipboard

module.exports.verifyJWS = async (compactJWS, jwksUrl) => {
  var jwks = await getJwks(jwksUrl);
   
  try {
    let keyStore = await jose.JWK.asKeyStore(jwks);
   
    let result = await jose.JWS.createVerify(keyStore).verify(compactJWS);
    let payload = JSON.parse(Buffer.from(result.payload).toString());
   
    return payload;
  } catch (error) {
    console.error("Error with verifying JWS:", error);
    throw constant.ERROR_VERIFY_JWS;
  }
};

The code example above verify the JWS and return the JSON object, which is the person's data.

3.JSON Web Encryption (JWE)

  • The encryption is done using your application's public key you provided during onboarding. So the payload's decryption should use your corresponding private key.

  • Current encryption algorithms used:

    • ECDH-ES+A256KW (for content key wrapping)

    • AES256GCM (for content key wrapping)

3.1 What is the JWE (JSON Web Encryption) Compact Serialization format?

The format consists of five parts separated by dots (.), which are:

PART
DESCRIPTION

Header

Contains the encryption algorithms used to produce the

  1. cipher text(encrypted data)

  2. encrypted key (symmetric key encrypted with application's RSA public key)

Encrypted Key

The encrypted symmetric key that was used to encrypt the data.

Initialization Vector

Secure random value used together with the symmetric key to encrypt the data.

Ciphertext

The encrypted data.

Tag

Value used to ensure integrity of the encrypted data and header.

Therefore, a JWE typically looks like the following: aaaaa.bbbbb.ccccc.ddddd.eeeee

3.2 How can I decrypt the JWE?

You will need to use a library that performs JWE decryption to decrypt the Ciphertext. Such libraries are readily available on the internet.

For example, in our sample application (using Node.js), we use the jose.jwe.decrypt method from jose library. If the decryption fails, the library will throw an error the application needs to handle.

3.3 How does JWE library decrypt the JWE in detail?

Firstly, your JWE library will decrypt the Encrypted Key inside the JWE using your application's corresponding Encryption private key. Once it's decrypted, your library can retrieve the symmetric key that is used to encrypt the Ciphertext in JWE. Next, the JWE library will decrypt the Ciphertext using that symmetric key together with the Initialization Vector, Tag and the encryption algorithm in the ASCII-encoded Header.


With reference to myinfo-connector/lib/securityHelper.js sample application connector code:

Copy to clipboard

module.exports.decryptJWEWithKey = async (compactJWE, encryptionPrivateKey) => {
  try {
    let keystore = jose.JWK.createKeyStore();
    let jweParts = compactJWE.split("."); // header.encryptedKey.iv.ciphertext.tag
    if (jweParts.length != 5) {
      throw constant.ERROR_INVALID_DATA_OR_SIGNATURE;
    }
     
    //Session encryption private key should correspond to the session encryption public key passed in to client assertion
    let key = await keystore.add(encryptionPrivateKey, "pem");
     
    let data = {
      "type": "compact",
      "protected": jweParts[0],
      "encrypted_key": jweParts[1],
      "iv": jweParts[2],
      "ciphertext": jweParts[3],
      "tag": jweParts[4],
      "header": JSON.parse(jose.util.base64url.decode(jweParts[0]).toString())
    };
     
    let result = await jose.JWE.createDecrypt(key).decrypt(data);
     
    return result.payload.toString();
  } catch (error) {
    throw constant.ERROR_DECRYPT_JWE;
  }
};

The code example above decrypts the JWE and returns the payload signed in JWS;

JWT Libraries
JWT.io
JWS (JSON Web Signature)