Authorization Basics

Client-Initiated Backchannel Authentication Flow (CIBA)

Learn what the Client-Initiated Backchannel Authentication Flow is and how it works in Cloudentity. Get familiar with three flow types (modes) of CIBA: PING, POLL, and PUSH.

CIBA in a Nutshell

Client-initiated Backchannel Authentication is an OpenID Connect decoupled flow. In CIBA, the client application that is responsible for making requests to Cloudentity APIs and resource server APIs is decoupled from the authentication device which the end-user uses to authenticate themselves and to confirm their consent. It means that, with CIBA, a client application can be outside of the end user control. The client and the authentication device can be physically separated.

Cloudentity CIBA simplified

CIBA flow is unlike the other OAuth and OIDC flows categorized as redirect flows. As the flow is decoupled, it gives the client application (a consumption device in CIBA) the possibility to act without the presence of the end-user. The flow may be initiated by a different person, for example, a customer service operator. In CIBA, there is no redirection of the end user, as they authenticate and give their consent through the use of the authentication device, for example, their mobile phone and an application installed on it.

CIBA Use Case Example

John is an online customer service operator for a popular web application and he needs to perform some actions on behalf of the application’s end-user, Mark. The client application is registered within Cloudentity and configured to use the CIBA flow. John uses their internal client application to access Mark’s users data. Such action requires Mark’s consent. Cloudentity receives the request and communicates with the authentication device that Mark uses. Mark opens an external authenticator application installed on his mobile phone to authenticate himself and to give his consent. He agrees that the client application John uses is authorized to access his personal data. Now, the client application is able to receive an access token from Cloudentity (by making a request to the token endpoint). to make requests to APIs stored on the resource server. In other words, with an access token, the client application is able to request Mark’s personal data, and, later on, provide it to John enabling him to solve Mark’s issues.

[mermaid-begin]
sequenceDiagram participant A as John participant B as Client Application participant C as Cloudentity participant D as Authentication device participant E as Mark A->>B: Access B->>C: Request authorization C->>D: Delegate authorization D->>E: Display consent E->>D: Give consent D->>C: Pass result of consent C->>B: Backchannel response B->>C: Request token C->>B: Token

CIBA Modes

The OpenID Connect Client-Initiated Backchannel Authentication Flow specification allows client applications to get results of its authentication using two ways:

  • POLL mode - where a client application sends continuous polling requests to Cloudentity up to the point it receives a response with a success

  • PING mode - where Cloudentity posts a notification (after the process on the authentication device is finished) to a client notification endpoint configured for this client application.

POLL Mode

In the POLL mode, after a client application receives a response from the Cloudentity’s backchannel authentication endpoint, the client repeats multiple token requests (hence the name, polling) to the Cloudentity’s token endpoint.

[mermaid-begin]
sequenceDiagram participant A as Client Application participant B as Cloudentity participant C as Authentication device participant D as End-user A->>B: Request to the backchannel authentication endpoint B->>A: Backchannel authentication response B->>C: Delegate authorization A->>B: Token request (repeat) B->>A: authorization_pending or slow_down response (repeat) C->>D: Display consent D->>C: Give consent C->>B: Provide authentication result A->>B: Token request B->>A: Issue access token or token response

When a clients waits for the result of the authentication, it repeats token requests. Until the authentication process is not finished, Cloudentity responds with the authorization_pending response or with the slow_down response if there are too many requests coming.

Continuous requests are sent until the client receives a token in the response or the response contains an error different from authorization_pending or slow_down.

PING Mode

The PING mode differs from the POLL mode, as there are no repeated requests to the token endpoint. Instead, once Cloudentity receives an authentication result from the authentication device, it notifies the client application using the client notification endpoint configured for this application. After the client receives such a notification with a successful authentication result, it may request a token.

[mermaid-begin]
sequenceDiagram participant A as Client Application participant B as Cloudentity participant C as Authentication device participant D as End-user A->>B: Request to the backchannel authentication endpoint B->>A: Backchannel authentication response B->>C: Delegate authorization C->>D: Display consent D->>C: Give consent C->>B: Provide authentication result B->>A: Notification A->>B: Token request B->>A: Issue access token or token response

The client notification endpoint must be set for a client application during its registration. It must be a HTTPs URL and it must utlize the Transport Layer Security (TLS).

Token Requests

Both in the POLL and in the PING mode a client application receives an access token as a result of a request to the token endpoint. Such a request must contain the following CIBA-specific parameters:

Parameter Description
grant_type This parameter provides information to Cloudentity which grant type is used. Both for the PING and the POLL modes, the value must be set to urn:openid:params:grant-type:ciba.
auth_req_id Authentication request ID that is issued from the backchannel authentication endpoint.

Client Authentication

In all CIBA modes, the following client authentication methods are allowed:

none client authentication cannot be used in the CIBA grant flow as only confidential clients are able to use CIBA securely.