[Singpass Login] Decrypting or Decoding Payloads from Token Endpoint

Introduction

If you're working with ID tokens and facing challenges decrypting or decoding them, this guide is for you. We'll walk you through the steps to decrypt ID tokens, retrieve NRIC or UUID, and understand various attributes in the ID token header.

Table of Contents

1. Decrypting the id Token
2. Retrieving NRIC or UUID
3. Understanding the 'epk' Attribute
4. Sample Successful JWE Response
5. Open Source Libraries for Decryption
6. Conclusion

1. Decrypting the id Token

Steps to Decrypt

1. Decrypt the Cipher Text: Use your private key from the 'enc' key in your published JWKS URL to decrypt the cipher text.
2. Verify the Signature: After decrypting, verify the signature of the decoded JWS using the Singpass public key.
3. Decode to Clear Text: Decode the BASE64URL to clear text to obtain the user token payload.

2. Retrieving NRIC or UUID

How to Retrieve

• For NRIC: If you have requested NRIC, you will get a JWS in a JWE. After decrypting and decoding, the "s" value in the payload would be your NRIC.
• For UUID: If you have requested a UUID, you will get a JWS. The UUID will be in the payload.

Sample Decrypted Payload

{ "sub": "s=S12345678B,u=d1df1d10-da12-1c11-9111-782b", "aud": "XXXXXXXXXXXXX", "amr": ["pwd", "swk"], "iss": "https://id.singpass.gov.sg", "exp": 1646215601, "iat": 1646215001, "nonce": "dummySessionNonce" }

3. Understanding the 'epk' Attribute

The 'epk' (Ephemeral Public Key) is used for content encryption. You can generally ignore this key as your programming library will handle it during the decryption process. For more information, refer to OpenID Specifications.

4. Sample Successful JWE Response

Here's a sample of a successful JWE response:

{ "access_token": "rBZYpDYeUlDVkmNCTrffhWIpGKBZ5bH+AHIa9DsHq4s=", "token_type": "Bearer", "id_token": "eyJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJiUk94NmF0cVFXYnBLaGRrcVpOS3A0b2hqdm5HYzhfZDlhbnA3X0dsVmkwIiwieSI6ImRCMTYyRm84Q3VxblF0U0tjYWtTeERUVlRmTVFCX1ZQVXYtYXdwWURmM2cifSwia2lkIjoib2N0b3B1czhfZW5jX2tleV8wMSIsImN0eSI6IkpXVCIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJhbGciOiJFQ0RILUVTK0EyNTZLVyJ9..." }

5. Open Source Libraries for Decryption

Here are some libraries you can use for decryption:

• JavaScript: node-jose
• Go: go-jose
• .NET: jose-jwt
• Python: authlib
• Java: nimbus-jose-jwt
• PHP: jwt-framework
• C/C++: cjose

6. Conclusion

This guide should help you understand how to decrypt and decode id tokens, as well as retrieve NRIC or UUID. If you encounter any issues, you can refer back to this guide for troubleshooting steps.