# 4. Parsing the ID Token The ID token returned during token exchange is a JSON Web Signature (JWS), which is also encrypted using JSON Web Encryption (JWE). The JWE and JWS components are represented using compact serialization form, as specified in [section 3.1 of RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516#section-3.1). To reduce complexity, we recommend that you use a JWT parsing library to decrypt the token and to verify the signature, instead of implementing the decryption and signature verification yourself. You may refer to [this list](https://www.jwt.io/libraries?support=verify\&algorithm=es256) to look for a suitable JWT library for your programming language, though you must also ensure that your library of choice supports decryption of JWTs encrypted using JWE. A sample ID token is shown below:

Sample encrypted ID token (this is a JWE)

{% code overflow="wrap" %} ``` eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiRUNESC1FUytBMjU2S1ciLCJraWQiOiJteS1lbmMta2V5IiwiZXBrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoidGIza3UwRHNyUTdFdHRkaVplcDVHUGdUOFgxaW5jYmR3M2YwSHB3ZHQ2SSIsInkiOiJEZzRFXzAwaWxGdEliVFhwMGRTcU84YUJTQXJPT3JSVWNOT3hKcFdReFFRIn19.hNnmqs2S9-vYzEXr7-Q9TmrzddUylJx-_n_HLjMWLQgeGECrwnmYPP2P638dQVGnlr_2KhJh6rFrm2wdoofSXv3YQR49zTC9.oEBMccRGsNtmMpbV1Oh6SA.TtYVOpO8cH1FpADKDIf0paepf7U8Rz2I_QYK2zITAk2wtuMuL3A3sUquvAA9a_KSm23F2WQ5vE0lA1qB54m9IYglWmaLT6epUQGw2gpkdQhrQmCuYMll2uvj1G-OV2TZgtLCNZakZY09U5SpSAjS32Sfa3H9iWmzjj8LiMQ_jLKBN-84TJpwiopOHW3b0O4tvEVdIq6bEfzqRjZ9qcqxkeWnyfajOC-NlCeqalXHJ_uRrJmVVRXmMjvMMOi1AEQJgVlyFaxBSvpkZGdXhuRRCv6LR3RK_SKizIDy1IwP0O5P6s4BKPXNaqjMwdoRKJdwB5euOGN3lK2Nh8hnzBO5Mp_lHf5XbbvdQ5oLWYDPRy19m6sSYPUIP4PfEguY7KmgbTjRd1ciptIetsRtQhKtYs6oLFp1hziwfk9AUYhkLN4dphSfamAZQeFct4lG4-Q865NezAupIs1BgTYPEu8q4Bw0-NXm0S0wISOJxmOCVng3h2uH4lqQY_bS7fGu4b8E30_-NWPesfKGc-dtVG3x7S1vEfDqjqnxY6XzzDnJOv-Op4cfjnATX067utxIJF2o9lo_9AG3Cul3xyGk9gx3DwHKImX_ldaJAajosUQQ8XUyuIsRjO_L8fQG2N9bYsKHt9qX2fK8fZGEfKsERw35i9AOifdlWxT5rcDM202zvZl9RGZOLGv3Z9JUfwtgAPKrEn5bXHwP__tefKgo9Ba__UUivtDzNwQE-ZVMoyKWMTKFLrULlfC9PaBO0UbVp4JsTVjcNgEVsLED-Y3rCBjNjehAGVyJxRcKUsngAEUAZJvNjGxaq149-Q6I7X6JOhrofY_8hqc74d4ROrDZ4vun2qVCzmrQmcCakEGpp9Y2wat0I-v7Q05COWWWu4EL_wdtgRnazA0DnH3el8ZUohsqNQ.fh6pMCnKcgo9yodwB5dPKcxdTZftoEmHKkB-KRxZPiI ``` {% endcode %}

Sample decrypted ID token (this is a JWS)

{% code overflow="wrap" %} ``` eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFsaWFzL3N0Zy1zcC1hdXRoLWFwaS1pZC10b2tlbi1zaWduaW5nLWtleS1rbXMtYXN5bW1ldHJpYy1rZXktYWxpYXMifQ.eyJpYXQiOjE3Njk3Mzk4MjMsImV4cCI6MTc2OTc0MDQyMywiaXNzIjoiaHR0cHM6Ly9zdGctaWQuc2luZ3Bhc3MuZ292LnNnL2ZhcGkiLCJzdWIiOiI3YzljNzJlYy01YmUyLTQ5NWEtYTc4ZS02MWU4MDlhMmEyMzYiLCJhdWQiOiJSc3JPeTJpQjBlZFI1M1RKU3VENVVMYWQxcEdtclZaTCIsImFtciI6WyJwd2QiXSwic3ViX2F0dHJpYnV0ZXMiOnsibmFtZSI6Ik5BTUUgT0YgUzU0MTA4MjhBIn0sInN1Yl90eXBlIjoidXNlciIsIm5vbmNlIjoiV2pxVU1NbU9ldllPWG13QzI3bWNBUVdzRkJuM083d3doYlJJdGwyRkprOCIsImFjciI6InVybjpzaW5ncGFzczphdXRoZW50aWNhdGlvbjpsb2E6MSJ9.pI0nhe0BLToMbuZ-9lpQiBNj2sj_ZWJwYFMT83u4yewZupTClPLUeYp08RR_sV2I70H6qpVmydRmoH8R9SipHQ ``` {% endcode %}

Sample decoded ID token payload

```json { "sub": "7c9c72ec-5be2-495a-a78e-61e809a2a236", "aud": "RsrOy2iB0edR53TJSuD5ULad1pGmrVZL", "acr": "urn:singpass:authentication:loa:1", "sub_type": "user", "sub_attributes": { "name": "NAME OF S5410828A" }, "amr": ["pwd"], "iss": "https:\/\/stg-id.singpass.gov.sg\/fapi", "exp": 1769740423, "iat": 1769739823, "nonce": "WjqUMMmOevYOXmwC27mcAQWsFBn3O7wwhbRItl2FJk8" } ```

## JWT Claims The decrypted JWT will have the following claims:

Claim	Description	Data Type
`sub`	The principal that is the subject of the JWT. Contains a globally unique identifier for the user.	String
`sub_type`	A property to describe what is the type of the subject of the JWT.	For Singpass, this is always the string `"user"`
`sub_attributes`	This contains some information related to the user's identifiers. This is only returned if the `user.identity` , `name`, `email`, or `mobileno` scope is requested.	Object containing key-value pairs. See the section below for full details.
`act`	An object describing actor acting on behalf of the `sub`. This is currently unused, but this may be used in the future for delegation (e.g. a child acting on behalf of their parent, or vice-versa). This object will contain a `sub` claim, which contains the UUID of the actor. If the `user.identity` , `name`, `email`, or `mobileno` scope is requested, it will also contain the respective data for the actor in the `sub_attributes` claim. If the `sub_attributes` claim is returned, the format of `sub_attributes` is described in the section below.	An object containing `sub` and `sub_attributes` (if requested).
`aud`	The client ID of your registered client, provided by Singpass during app onboarding.	A 32-character case-sensitive alphanumeric string.
`iss`	The issuer identifier of our authorization server.	String
`iat`	The unix timestamp, in seconds, at which we issued this JWT.	Number
`exp`	The unix timestamp, in seconds, on or after which this JWT must not be accepted for processing.	Number
`amr`	An array of authentication method references. This refers to the form factors used by the user to authenticate themselves. The array will contain all the form factors used for this authentication. For example, if the user authenticated themselves using their password and SMS OTP, then this array will contain both `pwd` and `otp-sms`.	Array of strings. The possible values are: `face` `pwd` `otp-sms` `face-alt` `swk` (software key) `hwk` (hardware key) Note that this list is non-exhaustive, and we reserve the right to introduce new values without prior notice to you.
`acr`	The authentication class reference value used for this transaction. This identifies the level of assurance that this authentication satisfied.	One of the following values: urn:singpass:authentication:loa:1 This indicates that only username and password was used for authentication. This will only happen in the staging environment. urn:singpass:authentication:loa:2 This indicates that 2-factor authentication was used for authentication. urn:singpass:authentication:loa:3 This indicates that 3-factor authentication, with face verification as a third factor, was used for authentication.
`nonce`	This is the same nonce that you used in your authorization request.	String

Sample ID token

```json { "aud": "gnY6Erichpb5t4NFRP9R4L7aEC9N0FQH", "iss": "https://id.singpass.gov.sg/fapi", "exp": 1727322545, "iat": 1727321945, "nonce": "L5nmQfcetDDIeincoqvCrFyGv+nHobkv4XocNYPCXaQ=", "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9", "sub_type": "user", "sub_attributes": { "account_type": "standard", "identity_number": "S1234567G", "identity_coi": "SG" } } ```

## The sub\_attributes Claim The `sub_attributes` claim is an object that will contain the following properties:

Property	Description	Data Type
`account_type`	The Singpass account type for this user. For Singpass Foreign Account (SFA) holders, this will be `"foreign"`. For all other Singpass accounts (i.e. those belonging to Singapore Citizens, Permanent Residents, or FIN holders), this will be `"standard"`.	A string, which is either `"foreign"` or `"standard"`. This is only present if the `user.identity` scope was requested.
`identity_number`	A string which contains a referencable identifier for the user. For Singapore Citizens and Permanent residents, this will be their NRIC. For FIN holders, this will be their FIN. For Singpass Foreign Account holders, this will be their foreign ID.	String. This is only present if the `user.identity` scope was requested.
`identity_coi`	The country code for the of issuance of the identity. For Singapore Citizens, Permanent Residents, and FIN holders, this will be `"SG"`. For Singpass Foreign Account holders, this will be the country code of the country which issued the user's foreign ID.	2-letter country code. This is only present if the `user.identity` scope was requested.
`name`	The user's principal name	Non-empty string. This will only be present if the `name` scope is requested.
`email`	The user's email address	String. This will only be present if the `email` scope is requested, and if the user has an email registered with Singpass.
`mobileno`	The user's mobile number. This will always be a Singapore mobile number, and it will not include the country code.	Numeric string. This will only be present if the `moibleno` scope is requested, and if the user has a mobile number registered with Singpass. For Singpass Foreign Account (SFA) users, this will always be absent.

Sample sub_attributes for Singapore Citizen, Permanent Resident, or FIN holder

```json "sub_attributes": { "account_type": "standard", "identity_number": "S1234567G", "identity_coi": "SG", "name": "John Doe", "email": "johndoe@gmail.com", "mobileno": "91231234", } ```

Sample sub_attributes for Singpass Foreign Account holder

```json "sub_attributes": { "account_type": "foreign", "identity_number": "K28394589", "identity_coi": "TK", "name": "Larry Doe", "email": "larrydoe@gmail.com", } ```

## Verification Checks {% hint style="info" %} If you are using a [certified OIDC Relying Party library](https://openid.net/developers/certified-openid-connect-implementations/), these checks will be automatically performed by the library, though you must pass the nonce to the library for it to perform the nonce check. {% endhint %} In order to ensure that the ID token is valid, you must perform the following checks: 1. Verify that the `iss` claim matches the issuer identifier of our authorization server, which you can obtain from the `issuer` field in the [OpenID configuration](https://docs.developer.singpass.gov.sg/docs/technical-specifications/technical-concepts/openid-connect-discovery) of our authorization server. 2. Verify that the `aud` claim matches your client ID. 3. Ensure that the current time is before the timestamp in the `exp` claim. 4. Ensure that the `nonce` claim is the same as the nonce that you had sent in the authorization request. If you are integrating with Singpass Login, then the flow ends here. If you are integrating with Myinfo (v5), then the next and final step would be to retrieve the user's information using the `/userinfo` endpoint.