# Client Initiated Backchannel Authentication (CIBA) Flow

Client Initiated Backchannel Authentication (also known as CIBA) enables users to
authorize access on a different device than the device initiating the request.
After sending a CIBA request to identity server, the user gets sent a notification
with a link to a page for authorizing the request. The client then polls for a token
using the issued authentication request id until an access token is received or the
request is denied or expired.

The CIBA response supplies an `expires_in` and an `interval` for how often
and how long you should poll for the token. An `auth_req_id` is also provided and
must be included when polling the token.

## CIBA request

Initiating a CIBA flow is done with a `POST /connect/ciba` request. You provide your `client_id`,
the required `scope` together with a either a `login_hint` (string) containing an id, email or username, or a `id_login_hint` / `login_hint_token`
(JWT token) containing a sub or an email claim that identifies the user. Use `binding_message` to explain or
identify the request for the user. A `requested_expiry` can be supplied to request a custom `expire_in`
value for the request, must be a positiv integer.

### POST /connect/ciba


```HTTP
POST https://id.aritma.io/{tenant}/connect/ciba HTTP/1.1
Content-Type: application/x-www-form-urlencoded

  client_id=YOUR_CLIENT_ID&
  client_secret=YOUR_CLIENT_SECRET&

  scope=SCOPE&
  login_hint=USER_ID_OR_EMAIL
  binding_message=YOUR_MESSAGE
```


```HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "auth_req_id": "9611FA9872...9341A325-1",
  "expires_in": 300,
  "interval": 5
}
```

| Parameter | Description |
|  --- | --- |
| `scope` (required) | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OpenID Connect (OIDC) scopes about users, such as profile and email, or any scopes supported by the target API (for example, banking.ais.read). Include offline_access to get a Refresh Token. |
| `client_id` (required) | Your application's Client ID. |
| `client_secret` (recommended) | Your application's Client Secret |
| `login_hint` | An email or username identifying the user. |
| `id_token_hint` | A jwt id token with a sub or an email claim identifying the user. |
| `login_hint_token` | A jwt token with a sub or an email claim identifying the user. |
| `binding_message` (recommended) | The message displayed to the user for this request. |
| `requested_expiry` | A positive integer for when the request should expire, defaults to 5m if not defined. |


## Poll token

Once you have received your `auth_req_id` it's time to poll until you recieve an usable access token, or the request expires.
This is done using the `/connect/token` endpoint. In short you send a token request with
`grant_type=urn:openid:params:grant-type:ciba` together with the supplied `auth_req_id` and your `client_id`.

### POST /connect/token


```HTTP
POST https://id.aritma.io/{tenant}/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

  grant_type=urn:openid:params:grant-type:ciba&
  client_id=YOUR_CLIENT_ID&
  auth_req_id=AUTH_REQ_ID
```


```HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}
```


```HTTP Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error":"authorization_pending",
}
```

| Parameter | Description |
|  --- | --- |
| `grant_type` (required) | Denotes the flow you are using. For Client Initiated Backchannel Authentication (CIBA) use `urn:openid:params:grant-type:ciba` |
| `client_id` (required) | Your application's Client ID. |
| `auth_req_id` (required) | The Authorization request id received from the initial `/connect/ciba` call. |


| Error | Description |
|  --- | --- |
| `authorization_pending` | The authorization request is still pending. (keep polling) |
| `slow_down` | A variant of `authorization_pending`, the authorization request is still pending, but the interval MUST be increased by atleast 5 seconds. |
| `expired_token` | The `auth_req_id` has expired, the client must create a new authorization request. |
| `access_denied` | The user denied the authorization request. |