# 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](#form-parameters) section below.

## Client Authentication <a href="#client_authentication" id="client_authentication"></a>

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

Refer to [this section](https://docs.developer.singpass.gov.sg/docs/client-initiated-backchannel-authentication-ciba/token-endpoint#client-authentication-client-assertion-jwt) for the structure of assertion JWT.

## Backchannel Authentication Request and Response <a href="#backchannel_authentication_request_and_response" id="backchannel_authentication_request_and_response"></a>

### **Curl request**

```bash
$ 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**

```http
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
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**

```bash
$ 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**

```x-www-form-urlencoded
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**

```json
{
  "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.                                           |