ID Token

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.

Parsing the ID token

Overview

The ID token is a JSON Web Encryption object (JWE), and the inner encrypted payload is a signed JWT (JWS).

The JWE is encrypted using the RP's public encryption key as configured in their JWKS object / JWKS endpoint, while the JWS is signed using Corppass private signing key.

High Level Steps

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).

    1. Validate the signature using Corppass’s public signing key from the JWKS endpoint.

    2. Validate the following claims: iss, aud, exp, iat, and nonce.

Structure

JWE

A JWE consists of five dot-separated Base64URL-encoded parts:

Read the Key Concepts - JWS and JWE page to find out more about JWEs and how to handle them.

JWE Header

Example of a protected header:

Fields present in the JWE header:

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.

Signed JWT

After decrypting the ID token (JWE), the payload retrieved will be a signed JWT. RPs must validate the signature.

Read the Key Concepts > JWS and JWE page to find out more about JWSs and how to handle them.

JWT Header

Example of the JWT header:

Fields present in the JWT header:

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.

JWT Claims

The decrypted JWT will have the following claims:

Claim
Type
Description

aud

String

Audience. The client ID of your client application as registered during onboarding.

iss

String

The issuer identifier of the Corppass authorization server.

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.

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.

amr

String Array

Authentication methods references used during Singpass Login. See amr for list of possible values.

at_hash

String

Hash value of this access token. Refer to Section 3.1.3.6 of OIDC Core 1.0.

sub

String

Subject identifier. 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.

Value: "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 the sub_attributes (Primary Subject: Entity) section for more details.

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 the act (Actor Subject: User) section for more details.

sub_attributes (Primary Subject: Entity)

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.entity_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.identity

sub_attributes - Sample Payload

Sample sub_attributes claim for a Singapore-registered Entity
Sample sub_attributes claim for a Foreign Entity

act (Actor Subject: User)

Represents the Authorised User acting on behalf of the Entity.

This object is present in the ID token to identify the individual user performing the transaction.

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 the act.sub_attributes (Actor Subject: User) section for more details.

act.sub_attributes (Actor Subject: User)

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

act - Sample Payload

Sample act and act.sub_attributes claims for an SC/PR / FIN user
Sample act and act.sub_attributes claims for an SFA user

amr

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

Some possible values are:

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)

ID Token Sample Payload

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

Verification Steps

Standard Claims Verification

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.

In order to ensure that the ID token is valid, clients 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 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.

at_hash Claim Verification

We also strongly encourage clients 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.

PreviousToken EndpointNextAccess Token

Last updated