ID Token

The ID Token is a verifiable security token issued by Corppass after a successful authorization code exchange. It contains identity-related claims about the authenticated Entity and the Acting User.

The ID Token is returned as a JSON Web Encryption (JWE) object, encrypted using the client's public encryption key configured in their JWKS object / JWKS endpoint.

Inside the encrypted payload lies the Signed JWT (JWS), signed using Corppass' private signing key.

To securely access this information, you must process the token in three sequential steps:

1. Decrypt the outer JWE layer.

2. Verify the inner JWS signature.

3. Validate before using the JWT claims.

1. Outer Layer: JWE (Encryption)

The outer JWE layer protects the confidentiality of the token. The payload is encrypted using the Client's Public Encryption Key (retrieved by Corppass from the Client's JWKS).

It consists of five dot-separated Base64URL-encoded parts.

<protected header>.<encrypted key>.<initialisation vector>.<ciphertext>.<authentication tag>

Refer to the JWS and JWE section for more details.

JWE Protected Header

Field	Description
alg	Key Management Algorithm. The algorithm used to encrypt the key that encrypts the payload.
enc	Content encryption algorithm. The algorithm used to encrypt the payload.
typ	Token type. Always set to JWT.
kid	Key ID. Identifies which Public Encryption Key from the RP's JWKS was used by Corppass to encrypt this token.

Clients must use the kid field in the JWE header to identify which Private Encryption Key from their local keystore is required to decrypt the payload.

Sample JWE Header

{
  "alg": "ES256",
  "enc": "A256CGM",
  "typ": "JWT",
  "kid": "example-key-id"
}

Action: Decrypt

1. Read the kid from the JWE header.

2. Look up the corresponding Private Encryption Key in your local keystore.

3. Decrypt the token using that private key.

4. The decrypted payload is a Signed JWT (JWS).

2. Inner Layer: JWS (Signature)

After decrypting the JWE in Step 1, the resulting payload is a Signed JWT (JWS). This layer ensures the token was issued by Corppass and has not been tampered with.

Refer to the JWS and JWE section for more details.

JWT Header

Field	Description
alg	Signing Algorithm. The algorithm used by Corppass to sign the token.
typ	Token type. Always set to JWT.
kid	Key ID. Identifies the key used for signing.

Sample JWT Header

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "example-key-id"
}

Action: Verify Signature

1. Read the kid from the JWS header.

2. Retrieve the matching Corppass Public Key from the JWKS Endpoint.

3. Verify the signature of the JWS using that public key.

4. If the signature is valid, you can now trust the content. The payload is the JWT Claims Set.

3. JWT Claims (Payload)

The decoded JSON payload from Step 2 contains the identity data, organized into three logical sections: Metadata, Entity Identity, and Actor (Acting User) Identity.

Action: Validate

1. Validate the standard claims (iss, aud, exp, nonce) against your expected values.

   1. iss: Must match the issuer URL in Corppass' OpenID Discovery Endpoint.

   2. aud: Must match your assigned Client ID.

   3. exp: Must be after current time (not expired).

   4. nonce: Must match the nonce value sent in the initial Authorization Request.

2. Validate the at_hash to ensure the Access Token is bound to this ID Token.

   1. at_hash: Must match the hashed value of the Access Token.

Before using this data, you must validate the standard claims to ensure the token is meant for you and is still valid.

For clients using a certified OIDC Relying Party library, these checks will be automatically performed by the library, though clients must still pass the nonce to the library for it to perform the nonce check.

A. Token Metadata

Claim	Type	Description
iss	String	The issuer identifier of the Corppass authorization server. Validation Required: Must Match: The issuer URL in Corppass' OpenID Discovery Endpoint.
aud	String	Audience. The client ID of your client application as registered during onboarding. Validation Required: Must Match: Your assigned Client ID.
iat	Number	Issued at. The unix timestamp, in seconds, at which the token was issued.
exp	Number	Expiration time. The unix timestamp, in seconds, on or after which this token must not be accepted for processing. Validation Required: Must Check: Current time < exp.
nonce	String	Nonce. The string value used to associate a Client session with an ID Token, and to mitigate replay attacks. Matches the value sent in the authorization request. Validation Required: Must Match: The nonce value sent in the initial Authorization Request.
amr	String Array	Authentication methods references used during Singpass Login. Refer to Supported AMR Values section for list of supported values.
at_hash	String	Hash value of this access token. Refer to Section 3.1.3.6 of OIDC Core 1.0 for more details. Validation Required: Must Verify: Hash the Access Token and compare to this value. This validates the ID Token and Access Token's integrity, ensuring they have not been tampered with.

Supported AMR Values

The list is non-exhaustive. Singpass reserves the right to introduce new values without prior notice.

Value	Description
pwd	Password
otp-sms	SMS OTP
face	Face verification
face-alt	Alternative form of face verification.
swk	Software-secured key (i.e. QR/shortcut login via Singpass app)
hwk	Hardware-secured key (i.e. QR/shortcut login via Singpass app)

B. Entity Identity (sub, sub_attributes)

These claims identify the Entity that the user is representing. In Corppass, the primary sub of the token is always the Entity.

Claim	Type	Description
sub	String	Subject identifier - the unique identifier of the entity. Represents the principal entity that is the subject of the JWT. For UEN entity type, this is the UEN. For Non-UEN entity type, this is the Corppass Entity ID.
sub_type	String	Subject type. Defines the type of the primary subject. Always set to entity.
sub_attributes	JSON	Primary subject information. Contains profile information related to the subject (entity) identified by the sub claim. Optional. Returned only if primary subject (entity) attributes are present - depending on the requested scopes. Refer to sub_attributes Fields section below for more details.

sub_attributes Fields

Contains information related to the Subject (Entity) identified by the sub claim.

This claim is only returned if it contains data (i.e., non-empty).

The presence of specific fields depends on the scopes requested (e.g., entity.identity).

Claim	Type	Description
entity_type	String	The entity type. Available values: UEN NON-UEN GSTN Required scope: entity.identity
entity_reg_number	String	Entity registration number. Required scope: entity.identity
entity_coi	String	Country of incorporation. Two-letter country code (e.g., SG, MY). Required scope: entity.identity
entity_name	String	The name of the registered entity. Required scope: entity.basic_profile.name
entity_uen_status	String	The UEN entity status. Returned only if the represented entity is of type UEN. Available values: Registered Deregistered Withdrawn Required scope: entity.basic_profile.uen_status

Sample Entity Claims

Sample claims for a Singapore-registered Entity

{
  ...
  "sub": "T09LL0001B",
  "sub_type": "entity",
  "sub_attributes": {
    "entity_type": "UEN",
    "entity_reg_number": "T09LL0001B",
    "entity_coi": "SG",
    "entity_name": "My Example Company",
    "entity_uen_status": "Registered"
  }
}

Sample claims for a Foreign Entity

{
  ...
  "sub": "C19001125A",
  "sub_type": "entity",
  "sub_attributes": {
    "entity_type": "NON-UEN",
    "entity_reg_number": "202219428Z",
    "entity_coi": "MY",
    "entity_name": "My Example Malaysian Company"
  }
}

C. Actor Identity (act.sub, act.sub_attributes)

These claims identify the Acting User performing the transaction on behalf of the Entity.

Claim	Type	Description
act	JSON	Represents the actor acting on behalf of the primary subject identified by the sub claim. In this case, this refers to the acting user performing the transaction on behalf of the entity. Refer to act Fields section below for more details.

act Fields

Claim	Type	Description
sub	String	Subject identifier. Represents the actor, which is the user acting on behalf of the primary entity subject. This is the unique identifier of the user.
sub_type	String	Subject type. Defines the type of the actor subject. Value: "user".
sub_attributes	JSON	Actor subject information. Contains profile information related to the subject (user) identified by the act.sub claim. Optional. Returned only if actor subject (user) attributes are present - depending on the requested scopes. Refer to act.sub_attributes Fields section below for more details.

act.sub_attributes Fields

Contains information related to the Subject (User) identified by the act.sub claim.

This claim is only returned if it contains data (i.e., non-empty).

The presence of specific fields depends on the scopes requested (e.g., user.identity).

Claim	Type	Description
account_type	String	The acting user's Singpass account type. Available values: standard - Singpass account holder (Singapore Citizen, PR, FIN holder) foreign - Singpass Foreign Account holder Required scope: user.identity
identity_number	String	The acting user's identity number. account_type="standard" - NRIC or FIN number. account_type="foreign" - Foreign ID number (e.g., Passport or National ID) Required scope: user.identity
identity_coi	String	Country of issuance of the acting user's identity. Two-letter country code (e.g., SG, MY). Required scope: user.identity
name	String	The acting user's full name. Required scope: user.name
corppass_email	String	Corppass registered email address. Required scope: user.corppass.email
corppass_email_verified	Boolean	Indicates if the Corppass registered email has been verified. Required scope: user.corppass.email

Sample Acting User Claims

Sample claims for an SC/PR / FIN user

{
  ...
  "act": {
    "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9",
    "sub_type": "user",
    "sub_attributes": {
      "account_type": "standard", 
      "identity_number": "S1234567P", // NRIC / FIN
      "identity_coi": "SG",
      "name": "John Grisham"
    }
  }
}

Sample claims for an SFA user

{
  ...
  "act": {
    "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9",
    "sub_type": "user",
    "sub_account": {
      "account_type": "foreign",
      "identity_number": "K28394589", // Foreign ID
      "identity_coi": "MY",
      "name": "John Grisham"
    },
  }
}

Sample Full JWT Payload

An SC/PR user, acting on behalf of a Singapore-registered company

{
  "iss": "https://stg-id.corppass.gov.sg",
  "aud": "vOIljWVrGyBMK6f31QYq",
  "iat": 1623162109,
  "exp": 1623165709,
  "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
  "amr": ["pwd", "sms"],
  "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
  "sub": "T09LL0001B",
  "sub_type": "entity",
  "sub_attributes": {
    "entity_type": "UEN",
    "entity_reg_number": "T09LL0001B",
    "entity_coi": "SG",
    "entity_name": "My Example Company",
    "entity_uen_status": "Registered"
  },
  "act": {
    "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9",
    "sub_type": "user",
    "sub_attributes": {
      "account_type": "standard", 
      "identity_number": "S1234567P",
      "identity_coi": "SG",
      "name": "John Grisham"
    }
  }
}

An SC/PR user, acting on behalf of a foreign company

{
  "iss": "https://stg-id.corppass.gov.sg",
  "aud": "vOIljWVrGyBMK6f31QYq",
  "iat": 1623162109,
  "exp": 1623165709,
  "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
  "amr": ["pwd", "sms"],
  "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
  "sub": "C19001125A",
  "sub_type": "entity",
  "sub_attributes": {
    "entity_type": "NON-UEN",
    "entity_reg_number": "202219428Z",
    "entity_coi": "MY",
    "entity_name": "My Example Malaysia Company"
  },
  "act": {
    "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9",
    "sub_type": "user",
    "sub_attributes": {
      "account_type": "standard", 
      "identity_number": "S1234567P",
      "identity_coi": "SG",
      "name": "John Grisham"
    }
  }
}

An SFA user, acting on behalf of a Singapore-registered company

{
  "iss": "https://stg-id.corppass.gov.sg",
  "aud": "vOIljWVrGyBMK6f31QYq",
  "iat": 1623162109,
  "exp": 1623165709,
  "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
  "amr": ["pwd", "sms"],
  "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
  "sub": "T09LL0001B",
  "sub_type": "entity",
  "sub_attributes": {
    "entity_type": "UEN",
    "entity_reg_number": "T09LL0001B",
    "entity_coi": "SG",
    "entity_name": "My Example Company",
    "entity_uen_status": "Registered"
  },
  "act": {
    "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9",
    "sub_type": "user",
    "sub_attributes": {
      "account_type": "foreign", 
      "identity_number": "K28394589",
      "identity_coi": "MY",
      "name": "John Grisham"
    }
  }
}