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 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 containing an id, email or username, or a id_login_hint / login_hint_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

RequestResponse

Copy

Copied

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

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=openid&login_hint=user1&binding_message=request123

Copy

Copied

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 you 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

RequestResponseResponse

Copy

Copied

POST https://id.aritma.io/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

Copy

Copied

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
}

Copy

Copied

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.