Singpass Developer Docs
CIBA
CIBA
  • Step-up Authentication using Push Notifications
    • Backchannel Authentication Endpoint
    • Token Endpoint
    • .well-known Endpoints
  • Staging and Production Endpoints
  • Error Response
Powered by GitBook
On this page
  • Client Authentication
  • Backchannel Authentication Request and Response
  • Curl request
  • Form parameters
  • HTTP request
  • HTTP response
  • HTTPie request
  • Request body
  • Response body
  • Response fields
  • Error Responses

Was this helpful?

  1. Step-up Authentication using Push Notifications

Backchannel Authentication Endpoint

PreviousStep-up Authentication using Push NotificationsNextToken Endpoint

Last updated 2 months ago

Was this helpful?

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 section below.

Client Authentication

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

Refer to 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.

Request Parameters
this section