Embedding Singpass JS

We provide a core JavaScript library (Singpass JS) to enable seamless integration with the Singpass Digital Signing Service (DSS). It facilitates transaction signing workflows for Relying Party (RP) applications, covering steps 2.1 to 5.3 in the flow diagram.

Key Functionalities

• Initialisation: Singpass JS is initialised in the RP’s frontend to set up the transaction signing process.

• Session Management: Starts the signing session with transaction details (Step 2.1).

• QR Code Rendering: Generates and displays the QR code for the user to scan via SingPass Mobile App (Step 2.2).

• Status Handling: Tracks user actions, returning the CHALLENGED status when the QR code is scanned (Step 3.2).

• Success Confirmation: Confirms the signed challenge response and returns the success status with the sign code (Step 5.3).

RPs shall embed this Javascript in your front end application.

URLs

Environment	URL
Staging	https://static.staging.sign.singpass.gov.sg/static/ndi_txn_sign.js OR https://stg-id.singpass.gov.sg/static/ndi_txn_sign.js (Deprecated)
Production	https://static.app.sign.singpass.gov.sg/static/ndi_txn_sign.js OR https://id.singpass.gov.sg/static/ndi_txn_sign.js (Deprecated)

You must provide your frontend origin during onboarding to allow communication with us.

Content Security Policy (CSP) Requirements

This section is important if the RP’s website (where Singpass JS is embedded) uses a Content Security Policy (CSP) header. For Singpass JS to fully function, please ensure that the following CSP attributes are set/added:

• script-src https://*.singpass.gov.sg;

• connect-src https://*.singpass.gov.sg;

• style-src https://*.singpass.gov.sg;

• img-src https://*.singpass.gov.sg data:;

• font-src https://fonts.gstatic.com;

Sample CSP header:

content-security-policy: default-src 'self'; script-src 'self' https://*.singpass.gov.sg; connect-src'self' https://*.singpass.gov.sg; style-src 'self' https://*.singpass.gov.sg; img-src 'self' https://*.singpass.gov.sg data:; font-src https://fonts.gstatic.com;

It is not necessary to set/add any CSP attributes if the RP’s website does not use a CSP header or has less strict policies for all the attributes mentioned above.

UI dimensions

The HTML elements will be rendered in a rectangular area with a fixed size with these dimensions, depending on the mode specified via the additionalOptions parameter:

Mode	Dimensions (width by height)
Basic QR with no additional elements	298px by 367px
QR with download link	298px by 416px

The RP must allot a minimum space according to these dimensions for the transaction signing UI element to be rendered properly.

UI Reference

For RP’s reference, this section displays the screens that Singpass JS renders during the transaction signing process. RPs can refer to these screens to get a better idea of how integrating with Singpass JS will look like on their website.

The green border indicates the minimum expected size of the DOMElementID provided by the RP.

Description	Screen
Session initialisation success
User scanned the QR code using SPM
Session expired (Before QR code was scanned)
Session expired (After QR code was scanned)
Retryable error occurred Users are only allowed to retry up to 1 time. This is to prevent excessive retries on the Singpass server because automated retries are already in place for such API calls.
Unretryable error occurred Examples of possible scenarios: Error occurred when invoking transactionParamsSupplier Pre-flight checks have failed (ie. RP invoked .initTxnSigning() with invalid parameters) Retries exhausted Malformed response from Singpass server, which cannot be recovered by retrying Client side errors returned from Singpass server In the situation where a corresponding erroneous HTTP status code is received, it will be displayed in brackets.
Service unavailable. This screen will be displayed if transaction signing service is toggled off on Singpass.
Browser unsupported. This screen will be displayed if the end-user’s browser/user-agent is not supported by Singpass JS. Singpass JS supports recent versions of major browsers, including but not limited to Chrome, Firefox, Edge, Safari, SamsungBrowser and IE 11.
Transaction Cancelled. This screen will be displayed if RP invoked .cancelTxnSigningSession()