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.
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 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_MESSAGEHTTP/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. |
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 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_IDHTTP/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/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. |