Client Initiated Backchannel Authentication (CIBA) Flow

Overview of the CIBA Flow

The Client Initiated Backchannel Authentication (CIBA) defines a protocol to support initiating authentication without user interaction from a Consumer Device. Authentication is performed via an Authentication Device by the user who also consents (if required) to the request. CIBA is also referred to as a decoupled flow. You can learn more about these concepts in the article Client Initiated Backchannel Authentication .

This article describes the messages in the Poll mode as specified by CIBA and aims to help developers understand and implement the specification.

1. The flow starts with an Authentication Request to the Backchannel Authentication Endpoint. The Authorization Server immediately returns an Authentication Request Acknowledgement with a transaction identifier, the auth_req_id.
2. The user authenticates through an out-of-band mechanism, a mobile device in this example.
3. Meanwhile, the client polls the Authorization Server regularly, checking for a token. The Authorization Server returns a Token Response with either an error indicating that the authentication is pending, or the tokens if available.

Metadata

Authentication Request

To initiate the Backchannel Authentication, the client sends an authentication request to the Authorization Server's Backchannel Authentication Endpoint using HTTP POST with Content-Type header set to application/x-www-form-urlencoded. The client needs to authenticate to the Authorization Server as part of the authentication request. Any client authentication method defined by OpenID or extensions may be used.

In the example below, the client uses mutual TLS, a client authentication method recommended by CIBA. When using mutual TLS for client authentication, the client must include its client_id in the requests. The line breaks were added for display purposes.

POST /oauth/v2/oauth-authorize HTTP/1.1
Host: idsvr.example.com
Content-Type: application/x-www-form-urlencoded

client_id=consumer_device&
scope=openid%20email%20phone&
binding_message=2X56&
requested_expiry=90&
acr_values=urn%3Ase%3Acurity%3Aauthentication%3Abankid&
login_hint_token=eyJhbGciOiJFUzI1NiJ9.eyJzdWJfaWQiOnsiZm9ybWF0IjoiZW1ha
    WwiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20ifX0.t5DsqWOhDH-Spbcx1TCy
    tXjMq19C1QGgIXVk_ih-v3072yq673mpEBYhsISADwzrIe_0k-Si-PAcwJlONxhb2Q

Authentication Response

The Authorization Server authenticates the client and verifies the authentication request. It checks, for example, if the hint is valid and identifies a known user. In case of an error, an authentication error response is returned. Otherwise, the Authorization Server responds with a successful authentication request acknowledgment.

Successful Authentication Request Acknowledgement

The authentication request acknowledgment includes parameters that are of importance for upcoming requests.

Study the following non-normative example of an authentication request acknowledgment:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "auth_req_id": "bspuw6ea-scst-u5hn-p3nt-37khzwY4g",
  "expires_in": 900,
  "interval": 5
}

Authentication Error Response

If the authentication request raises an error, the Authorization Server will return an authentication error response using HTTP status codes and descriptive error codes in the body of the response. Just as with token error responses, the body is formatted as application/json.

The following parameters appear in an error response:

The non-normative example below demonstrates an authentication error response as a result of the example authentication request listed above:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "unknown_user_id",
  "error_description": "Cannot identify the subject from the login_hint_token."
}

The Authorization Server may return one of the following errors. Please note that this list is not complete by any means. Refer to the specification for a complete list of error codes.

Token Request

In Poll mode, after having received the authentication request acknowledgment with auth_req_id, the client polls the token endpoint at a reasonable interval. The client must not poll more frequently than the interval specified by the Authorization Server as part of the authentication acknowledgment.

The Authorization Server may use long polling and not respond before an authentication result is available or a timeout has occurred. Therefore, the CIBA specification recommends waiting for at least 30 seconds between two polling requests, which is the value recommended by RFC6202, Best Practices for Long Polling. When using long polling, the Authorization Server may take more time to respond than the specified interval. In this case, the client must not send two overlapping requests with the same auth_req_id but wait for a response.

For the token request, the client forms a message using the application/x-www-form-urlencoded format and sends it via HTTP POST to the token endpoint. The client must also authenticate as part of the request. The body of the token request contains at least the following parameters:

The token request may look similar to this example. Note that the client uses mutual TLS for client authentication and must provide the client_id.

POST /oauth/v2/oauth-token HTTP/1.1
Host: idsvr.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&
auth_req_id=bspuw6ea-scst-u5hn-p3nt-37khzwY4g&
client_id=consumer_device

Successful Token Response

If the token request is valid, and if the user has been authenticated and has authorized the request, the Authorization Server will return a successful response just as with any other OpenID flow.

Consider the non-normative example below. Line breaks are added for readability.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
  "access_token": "5ca69968-00ca-4535-82e3-c7badf90b51b",
  "refresh_token": "0f8ed1e3-9542-45a0-84ce-4ae3ba61a60e",
  "scope": "openid email phone",
  "id_token": "eyJraWQiOiI2OTI0NjA1NjkiLCJ4NXQiOiJlYXM0bVVrOWpzMXRCZWVld
      zFtR3FkUW1RZHciLCJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2MTkwNzk2MzIsIm5iZ
      iI6MTYxOTA3NjAzMiwianRpIjoiYWQ2ZGZkNDYtZmZlMC00YmUyLTgzMDgtMGQ5ND
      gwODQ0NDkzIiwiaXNzIjoiaHR0cHM6Ly9pZHN2ci5leGFtcGxlLmNvbS9vYXV0aC9
      2Mi9vYXV0aC1hbm9ueW1vdXMiLCJhdWQiOiJjb25zdW1lcl9kZXZpY2UiLCJzdWIi
      OiJqYW5lZG9lIiwiYXV0aF90aW1lIjoxNjE5MDc2MDMxLCJpYXQiOjE2MTkwNzYwM
      zIsInB1cnBvc2UiOiJpZCIsImF0X2hhc2giOiJ6QVNBWFQzdjVQUGh1TVRIdnF3QW
      9RIiwiZGVsZWdhdGlvbl9pZCI6ImFlNmIzZTIyLTcwMzAtNGJmYS05YWU2LWMxODI
      wYWI4NGE3MCIsImFjciI6InVybjpzZTpjdXJpdHk6YXV0aGVudGljYXRpb246YmFu
      a2lkIiwic19oYXNoIjoiSTNtZ3VmV3JKb0JBdnJTNUJ4ZllKdyIsImF6cCI6ImNvb
      nN1bWVyX2RldmljZSIsImFtciI6InVybjpzZTpjdXJpdHk6YXV0aGVudGljYXRpb2
      46YmFua2lkIiwicGhvbmVfbnVtYmVyIjoiKzEgKDMxMCkgMTIzLTQ1NjciLCJub25
      jZSI6IjE2MTkwNzUyNzkxODctNklwIiwiZW1haWwiOiJqYW5lZG9lQGV4YW1wbGUu
      Y29tIiwic2lkIjoiSFJuVUtiY0szdjJ2MlcyZyJ9.U6gLsy7kPgIh5U9EFjdE-zpr
      ExfTwb5XY7sA95T0rvjfPWp7aF_Pzj7CNUAhhM50LSOVfVa0V0JHhfELuc5uh2D48
      vAVcRQtivAjMdq_Fmz5X46wZN87LpcrZsEENXWdR5Sh7CHorLcJrGoJStu4nMNRjU
      VS9KrQn5mKIj3s49y11BXhdAksxREEVDDvoI8TWSpT9_C1_6AuCWl-FGQZ6V5gAD8
      Q-qovqxmmbpn6UCOn0doJ05jC0JTOEd0fzdpchLSbRnhFxgp3aTgXwh80JKyNn5It
      g4KUPnHjPCELz-xsoktpPcoasepgrkxHnswwGEG0RCBbRkhIPOkXt31G9Q",
  "token_type": "bearer",
  "expires_in": 300
}

Token Error Response

As with any other flow in OpenID Connect, the token request in CIBA may result in an error. In addition to the error codes defined as part of the OAuth 2.0 specification, CIBA considers the following as applicable as well:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-cache, no-store

{
  "error": "authorization_pending"
}

The specification extends the meaning of some error codes as follows:

Resources and Further Information

• OpenID Connect Client Initiated Backchannel Authentication Flow
• Error Response in OAuth 2.0
• Error Response in OAuth 2.0 Device Authorization Grant
• RFC6202 - Best Practices for Long Polling

Published: 2021-04-30

Judith Kahrer

Product Marketing Engineer at Curity