Singpass Developer Docs
Developer Docs for Singpass
Developer Docs for Singpass
  • INTRODUCTION
    • Overview of Singpass
    • Understanding the basics of OIDC
  • Products
    • Login
      • Introduction
      • Key Principles
      • User Journey
      • Logo Download and Brand Guidelines
      • Singpass Button Guidelines (For developers and designers)
    • FAQ
      • Login
      • Myinfo
    • Myinfo
      • Introduction
      • Key Principles
      • User Journey
      • Logo Download and Brand Guidelines
      • Data Display Guidelines
      • Scheduled Downtimes
  • GETTING STARTED
    • Onboarding Checklist
    • User Journey
    • Create Singpass Application
    • Start Integration - Demo App
  • Technical Specifications
    • Singpass Authentication API
      • Overview of Singpass Flow
      • 1. Authorization Endpoint
        • Redirection on success
        • For Mobile Developers
      • 2. Token Endpoint
        • Authorization Code Grant
        • Client JWK Requirements
      • 3. Userinfo Endpoint
        • Requesting Userinfo
        • Validating the payload
      • .well-known Endpoints
        • OpenID Discovery Endpoint
        • JWKS Endpoint
      • Error Response
      • Frame busting for web views
    • Staging and Production URLs
  • Singpass Developer Portal (SDP)
    • User Guide
      • Obtain Access to SDP
      • Login to SDP
      • Toggle Staging vs Production
      • Create Staging App
      • Edit Staging App
      • Create Staging Test Account
      • Create Production App
      • Edit Production App
      • Consent to Singpass Service Agreement
      • View Singpass Service Agreement
      • Updating Billing Contact Information
      • Deactivate Production App
      • Activate Production App
      • How to View Production App Transactions
    • Understanding the App Config Fields
      • App Name
      • App Description
      • Site URL
      • Support Emails
      • Allowed Scopes
      • Redirect URL
      • Token-based Authentication
  • Data Catalog (Myinfo)
    • Understanding the Data
      • Local Registered Birth Records and Sponsored Child Records
      • CPF Contribution History (up to 15 months)
      • Notice of Assessment (Basic)
      • Notice of Assessment (Detailed)
    • Catalog
      • Personal
      • Finance
      • Education and Employment
      • Family
      • Vehicle and Driving Licence
      • Property
      • Government Scheme
  • TESTING
    • Testing with Singpass App
    • Myinfo Test Personas
  • MORE INFORMATION
    • Contact
Powered by GitBook
On this page
  • Sample Request
  • Sample Response
  • Request Parameters
  • Error Response

Was this helpful?

  1. Technical Specifications
  2. Singpass Authentication API

1. Authorization Endpoint

PreviousOverview of Singpass FlowNextRedirection on success

Last updated 3 months ago

Was this helpful?

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 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

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

Maximum of 255 characters. We recommend that you use a hex-encoded random number such as java.security.SecureRandom or UUIDv4.

state

Maximum of 255 characters. Must match regexp pattern of [A-Za-z0-9/+_\-=.]+

code_challenge

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)

redirect_uri_https_type

app_launch_url

(Optional) Intended for iOS mobile apps or Android mobile apps 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

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 for more details. The full list of supported scopes for Singpass can be found .

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 .

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 .

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 for more details about PKCE.

(Required if the redirect_uri uses is an ) Supported values are app_claimed_https and standard_https (default). This value is ignored if the redirect_uri has a custom scheme.

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

OpenID connect specs
Authorization Error Response specifications
OIDC Scope Values specifications
here
OIDC 1.0’s nonce parameter
OAuth 2.0’s state parameter
here
app-claimed HTTPS URL