1. Authorization Request
The first step in the Singpass authentication flow involves redirecting users to the Singpass login page. As Singpass requires the use of Pushed Authorization Requests (as defined in RFC 9126), you will need to perform two steps to do this:
Send a POST request to the
pushed_authorization_request_endpointdefined in our authorization server's OpenID configuration.Construct the authorization URL, and redirect the user to this URL.
More details about these steps are provided below.
1. Sending the pushed authorization request
The pushed authorization request is a HTTP POST request that is sent to the pushed authorization request endpoint.
Your request should contain a request body in the application/x-www-form-urlencoded format. The request body supports a lot of parameters, which can be divided into several groups: parameters specified by basic OIDC, parameters for PKCE, parameters for DPoP, and Singpass-specific parameters.
Basic OIDC Parameters
These are parameters that are specified as part of the original OIDC specifications. More information about them can be viewed in the official specifications.
response_type
The authorization processing flow to be used.
Only the value code is supported, as mandated by FAPI2.0 specifications.
scope
A space-delimited string, representing a list of scopes that you are requesting.
The scopes that you request will determine the data that is returned in the ID token and in the userinfo endpoint.
For Login apps, the only supported scopes are openid and sub_account.
A space-delimited string representing a list of scopes. See our Data Catalog for the allowed values.
The openid scope must be specified, as per the OIDC specifications.
In addition to the scopes listed in the Data Catalog, the sub_account scope is also supported. See <link to ID token parsing> for more details.
state
A session-based, unique, and non-guessable value that you should generate per auth session. This is used to mitigate Cross-Site Request Forgery (CSRF) attacks.
This parameter should be uniquely generated for each request and set by your backend. The generated value should be persisted in the backend and associated with your user's session, as it will be needed later. This string must be generated in a cryptographically secure way, and should ideally be at least 30 characters long. We recommend using a version 4 UUID for this purpose.
A string with a maximum length of 255 characters. It must match the regular expression pattern [A-Za-z0-9/+_-=.]+.
nonce
A session-based, unique, and non-guessable value that you should generate per auth session. This is used to mitigate replay attacks.
Just like the state parameter, this parameter should be uniquely generated for each request and set by your backend. The generated value should be persisted in the backend and associated with your user's session, as it will be needed later.
This string must be generated in a cryptographically secure way, and should ideally be at least 30 characters long. We recommend using a version 4 UUID for this purpose.
A string with a maximum length of 255 characters.
We recommend using a randomly-generated version 4 UUID for this purpose.
client_id
The client ID of your registered client, provided by Singpass during app onboarding.
A 32-character case-sensitive alphanumeric string.
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 URLs that were pre-registered with Singpass during onboarding.
URL
acr_values
A string indicating your preference on the level of assurance required for this authentication. Multiple values, in descending order of preference, may be provided as a space-delimited string. Should multiple values be provided, we will use the first available level of assurance for the authentication.
Optional. The possible values will be provided in the final version of this specification.
PKCE Parameters
These are parameters used for Proof of Key Code Exchange (PKCE), which is an additional security measure put in place to protect the authorization code against misuse by malicious actors.
code_challenge
The base64url encoded SHA256 hash of a code_verifier.
The code_verifier should be a session-based, unique, and non-guessable value that you generate. It must be an string containing only alphanumeric characters, dashes, and underscores, between 43-128 characters long.
The code_verifier should uniquely generated for each request and be persisted in the backend and associated with your user's session, as it will be needed later.
A base64url-encoded string.(note: base64url encoding is not the same as base64 encoding)
code_challenge_method
The method used to generate the code_challenge from the code_verifier
Only the value S256 is supported, as mandated by FAPI 2.0 specifications
DPoP Parameters
These are parameters used to perform authorization code binding to your DPoP key, which is a further security measure to protect the authorization code against misuse by malicious actors.
dpop_jkt
The JWK Thumbprint of your proof-of-possession public key.
String
Note that dpop_jkt is only required if your request does not contain the DPoP header (which contains the DPoP Proof JWT.
For simplicity, we recommend sending the DPoP header in the request rather than using the dpop_jkt request parameter, as you will also need to implement DPoP header generation in later steps.
You can read more about how to generate a DPoP proof JWT in this article.
Singpass-Specific Parameters
These are parameters which are not part of any standard, but are instead specific to Singpass.
transaction_category
A value selected from a predefined list describing the type of transaction that your user is performing the authentication for. This will be used for anti-fraud purposes.
Mandatory for Login apps, and not allowed for Myinfo (v5) apps.
The possible values will be provided in the final version of this specification.
auth_context_message
A string value providing context on what users are performing authentication for. This will be displayed to users when they are performing authentication.
String. Optional, and allowed only for Login apps.
redirect_uri_https_type
This value describes the type of redirect that you intend to perform. You should specify this as app_claimed_https if you are performing a redirection to a mobile app via an App-claimed https URL.
Either app_claimed_https or standard_https.
This field is optional; it defaults to standard_https if not provided.
app_launch_url
This value is only required if your authentication journey starts and ends for an iOS mobile app. This should be an iOS App Link which will bring the user back to your application after they complete authentication on the Singpass app.
Optional. This should be an iOS App Link.
Response
After you send the request, you will receive a response in JSON format which contains the following parameters:
request_uri
This is a reference to the payload that you have sent in this request. This will be needed in the next step
String
expires_in
This is a number, in seconds, representing the lifetime of the request_uri
Number. Maximum allowed value is 600
2. Redirecting the user to the authorization URL
After you complete the pushed authorization request, the next step is to redirect the user to open the authorization URL in their browser.
The base URL for the authorization URL can be located as the authorization_endpoint field in the authorization server metadata. You will only need to attach two query parameters to the authorization endpoint to form the authorization URL:
client_id
The client ID of your registered client, provided by Singpass during app onboarding. This must be the same client ID that you passed in the request body of the pushed authorization request.
request_uri
The request_uri returned by the pushed authorization request.
Once you have redirected the user to the authorization URL, the next step would be to wait for the user to complete authentication. Once they complete authentication, they will be redirected back to the redirect_uri that you specified. View the next page to understand how to handle the redirect.
Last updated
Was this helpful?