Backchannel Authentication Endpoint

As mentioned previously, the Step-up Authentication (Push Notifications) flow is implemented over the CIBA Poll mode flow.

This endpoint allows RPs to make an authentication request to begin a CIBA session with Singpass for a given user identifier. When initiation is successful, the RP will receive an auth session identifier which should be used for the subsequent CIBA steps.

Details about the user identifier is detailed in the login_hint field under the Request Parameters section below.

Client Authentication

To initiate the CIBA flow, RPs must authenticate itself with Singpass using client assertion JWT.

Refer to this section for the structure of assertion JWT.

Backchannel Authentication Request and Response

Curl request

$ curl 'https://stg-id.singpass.gov.sg/bc-auth' -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1' \
    -d 'client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJzdWIiOiJjbGllbnRJZCJ9.9STntUMUIaSSqe9fSET28n5szfM7VjD98ElfpVQtEhl5S8bnwKm2GpCsvMGhhzCifEP8uJyyjylFGhXOra2EderNpp3yrVHePlhIiB1nhVcXPYL1wng0iWJ85kk-PcZb&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&scope=openid&login_hint=178478de-fed7-4c03-a75e-e68c44d0d5f0'

Form parameters

Parameter	Description
client_assertion	The jwt used for authorization
client_assertion_type	The type of grant being requested. This MUST be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer
login_hint	A hint to the OpenID Provider regarding the end-user for whom authentication is being requested. Must be in upper case NRIC format or lower case UUID format.
scope	Supported value is openid.

HTTP request

POST /bc-auth HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: stg-id.singpass.gov.sg
Content-Length: 355

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJzdWIiOiJjbGllbnRJZCJ9.9STntUMUIaSSqe9fSET28n5szfM7VjD98ElfpVQtEhl5S8bnwKm2GpCsvMGhhzCifEP8uJyyjylFGhXOra2EderNpp3yrVHePlhIiB1nhVcXPYL1wng0iWJ85kk-PcZb&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&scope=openid&login_hint=178478de-fed7-4c03-a75e-e68c44d0d5f0

HTTP response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
X-XSS-Protection: 0
X-Frame-Options: DENY
Date: Fri, 14 Feb 2025 01:38:24 GMT
Connection: keep-alive
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
Transfer-Encoding: chunked
Content-Type: application/json
Content-Length: 82

{
  "auth_req_id" : "a167061f-1dfc-47a4-9537-eb7a4247619e",
  "expires_in" : 300
}

HTTPie request

$ http --form POST 'https://stg-id.singpass.gov.sg/bc-auth' \
    'client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJzdWIiOiJjbGllbnRJZCJ9.9STntUMUIaSSqe9fSET28n5szfM7VjD98ElfpVQtEhl5S8bnwKm2GpCsvMGhhzCifEP8uJyyjylFGhXOra2EderNpp3yrVHePlhIiB1nhVcXPYL1wng0iWJ85kk-PcZb' \
    'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
    'scope=openid' \
    'login_hint=178478de-fed7-4c03-a75e-e68c44d0d5f0'

Request body

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJzdWIiOiJjbGllbnRJZCJ9.9STntUMUIaSSqe9fSET28n5szfM7VjD98ElfpVQtEhl5S8bnwKm2GpCsvMGhhzCifEP8uJyyjylFGhXOra2EderNpp3yrVHePlhIiB1nhVcXPYL1wng0iWJ85kk-PcZb&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&scope=openid&login_hint=178478de-fed7-4c03-a75e-e68c44d0d5f0

Response body

{
  "auth_req_id" : "a167061f-1dfc-47a4-9537-eb7a4247619e",
  "expires_in" : 300
}

Response fields

Path	Type	Description
auth_req_id	String	ID given in the start of the OIDC CIBA flow that should be used to reference this authentication session.
expires_in	Number	A JSON number with a positive integer value indicating the expiration time of the "auth_req_id" in seconds since the authentication request was received.

Error Responses

The table below shows the list of common error codes that may be returned for this endpoint.

Error Code	Description
unknown_user_id	No active valid Singpass App (mobile) user available for given login_hint.
access_denied	End-user is an SFA user and is not authorised to authenticate into this RP.
invalid_client	RP failed client assertion authentication.
invalid_request	Invalid request parameters.
invalid_scope	The scope requested is not valid.