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.

Singpass Endpoints

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.

Endpoints	Request Parameters	Response 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 Profile	Sub 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:

Claim	Description
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 Methods Value 1FA [“pwd”] 2FA SMS OTP [“pwd”,”sms”] 2FA HW Token [“pwd”,”hwk”] 2FA Soft Token (Push) [“pwd”,”swk”] QR Code [“pwd”,”swk”]

Authentication Types

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

Client Profile	Descriptions
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

• Understand the prerequisite for integrating with Singpass.
• If you already have it, proceed to setup your application with Singpass.