Developer Docs for Singpass

Understanding the Basics

This guide demonstrates how to integrate with Singpass and display user profile information after the authentication and authorization process.

Check out our demo app to experience the login flow for yourself or refer to the interactive demo below for the outcome of this integration guide.

Singpass Endpoints

Singpass uses two endpoints for the authentication and authorization process.

Discovery Endpoint

This endpoint provides information about Singpass's endpoints and other configuration details.

Authorization Endpoint

This is the only endpoint where Singpass will interact with the users and get their authorization. Singpass will then return the authorization code in response via this endpoint.

Token Endpoint

This is the endpoint where Singpass will exchange the code received from the authorization endpoint for an ID Token and access token. Singpass only supports confidential clients, hence every application is required to authenticate at the token endpoint using a client ID and JWT Assertion.

Information Exchanged during Federated Authentication Flow

This section provides a high-level overview of the attributes and details that are exchanged during the federated authentication flow. This section aims to highlight the key attributes/information exchange during Singpass authentication. Details for each request parameter will be explained later in each integration step.

EndpointsRequest ParametersResponse Parameters

Authorization Endpoint

  • client_id

  • redirect_uri

  • response_type

  • state

  • nonce

  • scope

  • code: A 60-digit random string known as authorization code that is to be exchanged when calling token endpoint

  • state: Same state parameter sent in the request parameter will be returned back

Token Endpoint

  • authorization code

  • redirect_uri

  • response_type

  • client_id

  • JWT Assertion

  • access_token:A non-usable random string known as access token

  • id_token:A signed and encrypted JWT containing user’s identity and other standard claims explained in the next section

Singpass ID Token Claims

Claims are name/value pairs that contain information about a user, as well as meta-information about the OIDC service. The following are the details of the set of Claims (the JWT Claims Set) returned in the ID Token sent by Singpass.

The format and structure of the issued ID Token from the Token Endpoint will vary depending on whether the client’s profile required is UUID only or both NRIC and UUID

Client Profile Types

In OpenID Connect (OIDC), a client profile refers to the configuration and settings associated with a particular client application that interacts with an OIDC provider. Depending on the client profile, the details of the claim content returned by the token endpoint will differ.

Client ProfileSub Claim Content

direct

UUID Only Example: u=32af8b7d-ad1d-4c25-8dc7-0a981b533000

direct_pii_allowed

NRIC and UUID Example: s=S1234567A,u=32af8b7d-ad1d-4c25-8dc7-0a981b533000

Details of ID token claims are shown below:

ClaimDescription

sub

The principal that is the subject of the JWT. Contains a key value mapping that identifies that user of the token. For clients with profile direct, the expected format is u=userId. For other clients, the expected format is s=NRIC,u=userId. Ref.

aud

The client_id of the relying party. Ref.

iss

The principal that issued the JWT. Ref.

iat

The time at which the JWT was issued. Ref.

exp

The expiration time on or after which the JWT MUST NOT be accepted for processing. Defaults to 10 minutes since "iat". Ref.

nonce

A string that uniquely identifies the authentication.

amr

Authentication Methods References RFC 8176. JSON array of strings that are identifiers for authentication methods used in the authentication. This will allow the agencies to know if the user has used 1-factor or 2-factors when authenticating.

Authentication Types

Singpass provides three authentication types, however, each authentication type is granted according to your company profile.

Client ProfileDescriptions

QR Authentication

This method allow users to scan a QR code displayed on the Singpass login page using the Singpass Mobile App on for authentication. It provides a convenient and secure way to log in without needing to enter a username or password directly on the device.

1FA Authentication

This method requires users to provide their Singpass ID and password when requested on the Singpass login page for authentication.

2FA Authentication

2FA adds an additional layer of security beyond just a Singpass ID and password. It typically involves combining two different types of authentication factors. After providing Singpass ID and password, users can select Face Verification or enter a One-Time Password sent via SMS to complete the 2FA authentication.

Next steps

PreviousOnboarding ChecklistNextDiscovery Endpoint