1. Authorization Endpoint

NOTE: This section is only applicable for the Redirect Authentication Flow.

Upon user action (e.g. user clicks on a login button on the RP’s website), the RP should redirect the User Agent (browser) to Singpass's authorization endpoint with the request parameters documented below. See OpenID connect specs for more details.

Sample Request

NOTE: The actual GET request is made by the browser - RPs only need to construct the URL and redirect the browser to it.

$ http GET 'https://stg-id.singpass.gov.sg/auth?scope=openid&response_type=code&redirect_uri=https%3A%2F%2Fpartner.gov.sg%2Fredirect&nonce=bb5e1672-a460-4a9b-874e-c38d55ac3922&client_id=T5sM5a53Yaw3URyDEv2y9129CbElCN2F&state=dGVzdCBzdHJpbmcK&code_challenge=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&code_challenge_method=S256'

Sample Response

This will be a 302 response that redirects the browser to the Singpass login page.

Request Parameters

Parameter	Description
scope	Mandatory. A string value where openid is the minimum scope value. For /userinfo flows: Multiple scope values MAY be used by creating a space-delimited, case-sensitive list of ASCII scope values. For example, openid name uinfin. See OIDC Scope Values specifications for more details. The full list of supported scopes for Singpass can be found here.
response_type	The authorization processing flow to be used. Supported value is code for the Authorization Code Flow.
client_id	The clientId provided by Singpass during onboarding.
redirect_uri	The URL that Singpass will eventually redirect the user to after the user completes the login process using the Singpass App. The value will be validated against the list of redirect URIs that were pre-registered with Singpass during onboarding.
nonce	A session-based, unique, and non-guessable value that the RP should generate per auth session. This parameter should ideally be generated and set by the RP’s backend and passed to the frontend. As part of threat modelling, NDI is requesting for the nonce parameter so as to mitigate MITM replay attacks against the ASP Service’s Token Endpoint and its resulting ID Token. This parameter serves the same purpose as OIDC 1.0’s nonce parameter. Maximum of 255 characters. We recommend that you use a hex-encoded random number such as java.security.SecureRandom or UUIDv4.
state	A session-based, unique, and non-guessable value that the RP should generate per auth session. This parameter should ideally be generated and set by the RP’s backend and passed to the frontend. As part of threat modelling, NDI is requesting for the state parameter so as to mitigate replay attacks against the RP’s redirection endpoint (redirectUri). This parameter serves the same purpose as OAuth 2.0’s state parameter. Maximum of 255 characters. Must match regexp pattern of [A-Za-z0-9/+_\-=.]+
code_challenge	The hash of a code verifier generated using the hash method specified in code_challenge_method. This is to enable Proof Key for Code Exchange (PKCE). This is an extension to the authorization code flow to prevent CSRF and authorization code injection attacks. Refer here for more details about PKCE. Must match regexp pattern of [a-zA-Z0-9_\-]{43} (Mandatory)
code_challenge_method	The method used to generate the code_challenge from the code verifier. Only S256 is supported. (Mandatory)
ui_locale	(Optional) The language which the Singpass login page should be displayed in. Supported values are en, ms, ta, zh-SG.
redirect_uri_https_type	(Required if the redirect_uri uses is an app-claimed HTTPS URL) Supported values are app_claimed_https and standard_https (default). This value is ignored if the redirect_uri has a custom scheme.
app_launch_url	(Optional) Intended for iOS mobile apps or Android mobile apps using WebView which use QR authentication via redirect auth. This adds the possibility for the user to be redirected back to the provided App Link after they successfully authorize themselves on the Singpass App. The value passed here should be the App Link registered with Apple’s App Store and/or Google’s Play Store. The provided value will be validated according to the list of app launch URLs which the RP has pre-registered with NDI.
esrvc	(Special case internal use only.) eService ID value for multi-tenant RPs / Singpass OIDC bridge. The value will be validated against registered eServices or registered RP’s client_external_id.
acr_values	(Special case internal use only.) Authentication Context Class Reference passed by the Singpass Portal kickoff endpoint. Will be forwarded to Singpass OIDC authorize endpoint if provided.

Refer to this table to determine whether to include the app_launch_url param:

Authenticating From	app_launch_url Param
Relying Party website	Do not include
Relying Party website on a mobile browser	Do not include
Relying Party mobile app	Can include

Error Response

Singpass generally follows OIDC error response specifications. For more information, please refer to Authorization Error Response specifications.