Singpass Login API Integration-part 2

5 min readDec 31, 2021

Following sections provides overview of Singpass and details for quick integration with web application. For general OIDC overview refer part1 of this series in order to get the complete background.

Singpass Overview

Singpass is an OIDC provider which client can integrate with their applications for onboarding Singapore residents holding NRIC (National Registration ID Card for Singapore users) with greater assurance.
Integrating Singpass with client applications provides a great experience to the users for accessing applications with their Singpass app without going through long registration process or remembering usernames/passwords for logging in to client applications.

Terminology

Client Assertions:

Client Assertions are used for client Authentication in Singpass OIDC flow which is a JWT which has predefined set of claims signed using signing private key.

2. JWKS Endpoint:

JWKS is JSON web key set used in OIDC protocol to represent public key. JWKS endpoint is used by relying party and Singpass to host their public signing and encryption keys which will be used in Singpass OIDC flow.
Two types of keys used by relying party are described below:
1. Signing key: Client Assertions are signed by relying party’s signing private key and verified by Singpass by fetching public key from relying party’s signing public key.
2. Encryption key: Encryption keys are used by Singpass for payload encryption. Payload is encrypted by Singpass and decrypted by relying party.
Relying party’s JWKS endpoint contains public key of signing and encryption keys while Singpass JWKS endpoint contains only public key of signing key.

3. Token Endpoint:

Singpass’s token endpoint is used by relying party to exchange authorization code with access token and id token after authenticating themselves with client id and client assertions

Singpass OIDC Flow

Above figure shows Singpass Login OIDC flow which is described in detail below:

1(a)Using Singpass JavaScript library’s initAuthSession function QR code is rendered inside given DOM Element on relying party’s web app.
1(b)This step includes a request to be sent to Singpass OP (OIDC Provider) with client ID, scope as openid and redirect URI (done by JavaScript library).
Singpass OP authenticates the user when user scans the Singpass QR code with Singpass app and logs-in.
3(a)After successful authentication Singpass OP creates an authorization code.
3(b) This authorization code and relying party’s same state value is sent to relying party’s backend server through user agent.
4 (a)On relying party backend client assertion is created for client authentication. Using this authentication code, client id and client assertion, token id is fetched from Singpass token endpoint.
4(b)Singpass fetches relying party’s signing and encryption keys from relying party’s JWKS endpoint. Also relying party fetches Singpass signing public key to be used later for signature verification.
5(a)Singpass validates client assertion and authorization code and creates an access token (random string currently not used in OIDC flow), id token containing claims i.e. encrypted UUID and NRIC number. These claims are encrypted with relying party’s encryption public keys obtained from JWKS endpoint.
5(b)Relying party then decrypts the id token to obtain NRIC and UUID from claims and optionally relying party can also verify signature of ID token by using Singpass’s public key obtained in previous step from JWKS endpoint.

Singpass Integration

Singpass Integration Pre-requisites
Before integrating Singpass with client applications below pre-requisites are required to be completed.

1. Setting up JWKS endpoint:
Each relying party is required to setup its JWKS endpoint to host its encryption and signing public keys. Relying party must create EC type signing key and encryption key using openssl and should verify JWKS response using Singpass JWKS Verifier tool .

2. NDI (National Digital Identity) Onboarding Process:
To integrate Singpass, business entity must submit a linkup request on NDI portal with following details

Once linkup request is submitted to Singpass, domain names will be whitelisted and test accounts will be created against registered Singapore mobile numbers by Singpass. Also staging version of Singpass app will be shared through App Center with registered email ID.

Singpass Integration with web application

Following sections provides a quick step by step overview of steps to be performed by relying party’s frontend and backend server for Singpass integration.

Singpass Login API Integration with Frontend:

1. For web applications import below JavaScript NDI library which will provide initAuthSession and cancelAuthSession functions for initiating/cancelling Singpass authentication OIDC flow.

2. Whitelist Singpass domain as a part of Content Security Policy by including below meta tag in index.html file.

3. To initialize Singpass OIDC flow call below function in frontend login component where QR code needs to be displayed.
initAuthSession(DOMElementID, authParams, authParamsSupplier, onError) returns String

initAuthSession function parameters are described below

Table: initAuthSession function parameters

Relying party backend for Singpass Login API Integration:

After successful authentication Singpass will redirect to relying party’s backend server with authentication code and state, thus relying party must implement this redirect URI authentication endpoint controller and must perform following token REST API call to Singpass OP with client assertion and other parameters.

1. Authentication Endpoint: After successful authentication, Singpass will return an authorization code and state back to Relying Party as shown below.

2. Client Assertion: Before calling token endpoint relying party must create JWT to identify itself with Singpass OP. As support to client secret is discontinued so relying party must use client assertion. Client Assertion should have below structure. The header must include alg[ES256,ES384,ES512] (algorithm should correspond to signing key algorithm with which EC signing key was created) and typ(JWT).

3. Token Endpoint: After receiving code and state relying party should invoke Singpass token endpoint with following parameters.

Table: Request parameters for token endpoint

Sample token endpoint response is provided below from which id_token should be decrypted to get NRIC and UUID (Regular NRIC holders). After decryption, payload obtained is a map containing NRIC and UUID (eg. [s=S1234567A,u=32af8b7d-ad1d-4c25–8dc7–0a981b533000] where key s refers to test account’s NRIC number and key u refers to test account’s UUID)

Sample relying party frontend and backend server code can be found here https://github.com/vineetaparodkar/singpass_relying_party.git