ID Token Structure

An ID Token is a signed and encrypted JWT (JWE) issued by Corppass in the OpenID Connect Authorization Code Flow. It contains identity-related claims about the authenticated user and their associated entity, and is returned in the token response after successful authentication.

Format

The ID token is a JWE — a JSON Web Encryption object — that encapsulates a signed JWT (JWS) inside an encrypted payload. It consists of five dot-separated Base64URL-encoded parts:

<protected header>.<encrypted key>.<IV>.<ciphertext>.<authentication tag>

The inner payload is a signed JWT (JWS), encrypted using the client’s public key found at their JWKS.

Decrypting the ID token

To process the ID token, clients must:

  1. Use their private encryption key to decrypt the JWE.

  2. Extract and validate the inner signed JWT (JWS).

  3. Validate its claims and signature using Corppass’s public signing key from the JWKS endpoint.

  4. Validate claims: iss, aud, exp, iat, and nonce.

JWE

JWE Protected Header Example

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

alg

Key management algorithm — asymmetric ECDH-ES with AES key wrapping

enc

Content encryption algorithm — AES GCM

typ

Token type (always JWT)

kid

Key ID — matches the encryption public key in the client's JWKS

Clients must use the kid field in the JWE header to identify the key Corppass used for encryption. Refer to RFC 7515 Section 4 for more information about the JWE structure.

JWS

JWS Header Example (inner token after decryption)

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

alg

Signing algorithm used by Corppass (e.g., ES256)

typ

JWT token type

kid

Key ID — matches a public key in Corppass’s JWKS for signature validation

Clients must use the kid (Key ID) field in the JWS header to identify which public key from Corppass’s JWKS was used to sign the token. Refer to RFC 7515 – JSON Web Signature (JWS) for more information on the JWS structure.

JWS Payload (Claims) Examples

A user with a SC/PR identification, representing on behalf of a local company
For EXPLICIT authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "ACME Corporation",
    },
    "act": {
       "sub_account": {
         "account_type": "SC/PR",
         "uinfin": "S1234567P"
         "name": "John Grisham",
         "email": "[email protected]",
         "email_verified": true,
       },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
}
For THIRD-PARTY authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "Loreum Corporation",
    },
    "act": {
       "sub": "9222759M",
       "sub_account": {
         "account_type": "entity",
         "entity_name": "ACME Corporation",
       },
       "act": {
         "sub_account": {
           "account_type": "SC/PR",
           "uinfin": "S1234567P"
           "name": "John Grisham",
           "email": "[email protected]",
           "email_verified": true,
        },
      },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
}

A user with a SC/PR identification, representing on behalf of a foreign company
For EXPLICIT authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "ACME Corporation",
      "non_uen_country": "Malaysia",
      "non_uen_reg_no": "1234567890123", 
    },
    "act": {
       "sub_account": {
         "account_type": "SC/PR",
         "uinfin": "S1234567P"
         "name": "John Grisham",
         "email": "[email protected]",
         "email_verified": true,
       },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=", 
}
For THIRD-PARTY authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "Loreum Corporation",
    },
    "act": {
       "sub": "9222759M",
       "sub_account": {
         "account_type": "entity",
         "entity_name": "ACME Corporation",
         "non_uen_country": "Malaysia",
         "non_uen_reg_no": "1234567890123",
       },
       "act": {
         "sub_account": {
           "account_type": "SC/PR",
           "uinfin": "S1234567P"
           "name": "John Grisham",
           "email": "[email protected]",
           "email_verified": true,
        },
      },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=", 
}

A user with a foreign country identification, representing on behalf of a local company
For EXPLICIT authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "ACME Corporation",
    },
    "act": {
       "sub_account": {
         "account_type": "SFA",
         "foreign_id": "K28394589",
         "foreign_id_coi": "MY"
         "name": "John Grisham",
         "email": "[email protected]",
         "email_verified": true,
       },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
    "non_uen_country": "",
    "non_uen_reg_no": "",  
}
For THIRD-PARTY authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "Loreum Corporation",
    },
    "act": {
       "sub": "9222759M",
       "sub_account": {
         "account_type": "entity",
         "entity_name": "ACME Corporation",
       },
       "act": {
         "sub_account": {
           "account_type": "SFA",
           "foreign_id": "K28394589",
           "foreign_id_coi": "MY",
           "name": "John Grisham",
           "email": "[email protected]",
           "email_verified": true,
        },
      },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=", 
}

A user with a foreign country identification, representing on behalf of a foreign company
For EXPLICIT authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "ACME Corporation",
      "non_uen_country": "Malaysia",
      "non_uen_reg_no": "1234567890123",
    },
    "act": {
       "sub_account": {
         "account_type": "SFA",
         "name": "John Grisham",
         "foreign_id": "K28394589",
         "foreign_id_coi": "MY"
         "email": "[email protected]",
         "email_verified": true,
       },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
}
For THIRD-PARTY authorization
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "82532759L",
    "sub_account": {
      "account_type": "entity",
      "entity_name": "Loreum Corporation",
    },
    "act": {
       "sub": "9222759M",
       "sub_account": {
         "account_type": "entity",
         "entity_name": "ACME Corporation",
         "non_uen_country": "Malaysia",
         "non_uen_reg_no": "1234567890123",
       },
       "act": {
         "sub_account": {
           "account_type": "SFA",
           "foreign_id": "K28394589",
           "foreign_id_coi": "MY",
           "name": "John Grisham",
           "email": "[email protected]",
           "email_verified": true,
        },
      },
    },
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=", 
}

Claims Overview

The ID Token contains both standard OIDC claims and Corppass-specific custom claims.

Optional claims are ONLY included if the corresponding scope is requested at the Authorization Endpoint and the client is authorized to request.

Explicit Delegation — Claim Reference Table

Claim
Type
Required
Description

sub

String

Y

The subject identifier. Represents the UEN of the entity being accessed on behalf of.

sub_account

Object

Y

The current entity being represented.

sub_account.account_type

String

Y

Should always be "entity" for business delegation.

sub_account.entity_name

String

Y

The registered name of the represented entity.

sub_account.non_uen_country

String

N

The registered company of the entity. Present only if the represented entity is a foreign company.

sub_account.non_uen_reg_no

String

N

Company registration number in the foreign jurisdiction. Required when non_uen_country is present. Present only if the represented entity is a foreign company.

act

Object

Y

Represents the actor (the user performing the action).

act.sub

String

Y

Identifier of the actor

act.sub_account

Object

Y

Account context of the actor

act.sub_account.account_type

String

Y

The type of account that the user has

Account
Values

Singaporeans/PRs

SC/PR

Singpass Foreign Account

SFA

act.sub_account.uinfin

String

N

NRIC/FIN of the user. Present only if the user's account type is SC/PR.

act.sub_account.foreign_id

String

N

Foreign identifier (e.g., passport or local ID). Only provided if sfa was included in the scope during the /authorize request and the client is authorized to access this data.

act.sub_account.foreign_id_coi

String

N

Country of issuance for the foreign identifier. Only provided if sfa was included in the scope during the /authorize request and the client is authorized to access this data.

act.sub_account.name

String

Y

Full name of the user performing the action.

act.sub_account.email

String

N

Email address of the acting user. Only provided if business_profile.email was included in the scope during the /authorize request and the client is authorized to access this data.

act.sub_account.email_verified

Boolean

Y

Whether the actor’s email has been verified. Only provided if business_profile.email was included in the scope during the /authorize request and the client is authorized to access this data.

aud

String

Y

The client ID of the Relying Party. Refer to Section 4.1.3 of RFC 7519.

iss

String

Y

The issuer of the token. Refer to Section 4.1.1 of RFC 7519.

iat

Number

Y

The time the token was issued, expressed as a UNIX timestamp. Refer to Section 4.1.6 of RFC 7519.

exp

Number

Y

The expiration time of the token, expressed as a UNIX timestamp. The default validity is 10 minutes from iat. Refer to Section 4.1.6 of RFC 7519.

nonce

String

Y

A unique string to associate the ID Token with the authorization request to prevent replay attacks.

amr

Array

Y

Authentication methods used during Singpass Login. Possible authentication methods are:

Methods
Values

1FA

["pwd"]

2FA SMS OTP

["pwd","sms"]

QR Code

["pwd","swk"]

Facial Biometrics

["pwd","fv"]

at_hash

String

Y

A hash of the Access Token issued alongside the ID Token.

Third-Party Delegation — Claim Reference Table

Claim
Type
Required
Description

sub

String

Y

The subject identifier — the intermediary entity acting on behalf of another company.

sub_account

Object

Y

Account context for the sub

sub_account.account_type

String

Y

Should be "entity" for business delegation.

sub_account.entity_name

String

Y

The registered name of the intermediary entity.

act

Object

Y

Represents the company that the intermediary is acting on behalf of.

act.sub

String

Y

Identifier of the company being represented.

act.sub_account

Object

Y

Account context of the company being represented (e.g. foreign company).

act.sub_account.account_type

String

Y

Should always be "entity" for business delegation.

act.sub_account.entity_name

String

Y

The registered name of the represented entity.

act.sub_account.non_uen_country

String

N

The registered company of the entity. Present only if the represented entity is a foreign company.

act.sub_account.non_uen_reg_no

String

N

Company registration number in the foreign jurisdiction. Present only if the represented entity is a foreign company.

act.act

Object

Y

Represents the actor (the user performing the action).

act.act.sub

String

Y

Identifier of the actor

act.act.sub_account

Object

Y

Account context of the actor

act.act.sub_account.account_type

String

Y

The type of account that the user has

Account
Values

Singaporeans/PRs

SC/PR

Singpass Foreign Account

SFA

act.act.sub_account.uinfin

Sring

N

NRIC/FIN of the user. Present only if the user's account type is SC/PR.

act.act.sub_account.foreign_id

String

N

Foreign identifier (e.g., passport or local ID). Only provided if sfa was included in the scope during the /authorize request and the client is authorized to access this data.

act.act.sub_account.foreign_id_coi

String

N

Country of issuance for the foreign identifier. Only provided if sfa was included in the scope during the /authorize request and the client is authorized to access this data.

act.act.sub_account.name

String

Y

Full name of the user performing the action.

act.act.sub_account.email

String

Y

Email address of the acting user. Only provided if business_profile.email was included in the scope during the /authorize request and the client is authorized to access this data.

act.act.sub_account.email_verified

Boolean

Y

Whether the actor’s email has been verified. Only provided if business_profile.email was included in the scope during the /authorize request and the client is authorized to access this data.

aud

String

Y

The client ID of the Relying Party. Refer to Section 4.1.3 of RFC 7519.

iss

String

Y

The issuer of the token. Refer to Section 4.1.1 of RFC 7519.

iat

Number

Y

The time the token was issued, expressed as a UNIX timestamp. Refer to Section 4.1.6 of RFC 7519.

exp

Number

Y

The expiration time of the token, expressed as a UNIX timestamp. The default validity is 10 minutes from iat. Refer to Section 4.1.6 of RFC 7519.

nonce

String

Y

A unique string to associate the ID Token with the authorization request to prevent replay attacks.

amr

Array

Y

Authentication methods used during Singpass Login. Possible authentication methods are:

Methods
Values

1FA

["pwd"]

2FA SMS OTP

["pwd","sms"]

QR Code

["pwd","swk"]

Facial Biometrics

["pwd","fv"]

at_hash

String

N

A hash of the Access Token issued alongside the ID Token.

Implementation Notes for Relying Parties

  1. at_hash Verification

We strongly encourage Relying Parties (RPs) to use at_hash claim to validate the Access Token's integrity, ensuring it has not been tampered with. For more details on at_hash claim, refer to Section 2 of the OIDC Core Specification.

Last updated