Client-Initiated Backchannel Authentication

Suggest Edits

Client-Initiated Backchannel Authentication grant type

The Client-Initiated Backchannel Authentication (CIBA) grant type enables a client to authenticate end users through out-of-band mechanisms without participating in the authentication process. This is unlike other flows, where the client is generally responsible to redirect or guide the user to the authentication flow. As a consequence, the authentication mechanisms would typically be one of the following:

  • Push-based authentication using, for example, the IBM Security Verify authenticator app on mobile phones
  • Link sent via SMS to a mobile phone or other communication channels. This link may lead the user through an authentication, authorization and consent process that may be hosted or directed by the OIDC Provider itself.

The CIBA specification is here.

Typical flow

Initiation

The CIBA flow is started when an initial request is received at the /oauth2/ciba endpoint. At the minimum, the request contains client authentication credentials (such as a client_id and secret or a private key signed JWT, etc.), scope to indicate requested permissions and user data, and a hint that identifies the user uniquely. The hint may be provided as a login_hint, login_hint_token, or id_token_hint parameter.

The OIDC Provider responds with auth_req_id. The client uses this in subsequent requests to the /oauth2/token endpoint to obtain the requested tokens.

There are three modes by which the client can obtain the tokens or retrieve any errors that might have occurred:

  • Poll mode: The client polls for the status by calling into the /oauth2/token endpoint periodically.
  • Ping mode: The client registers a client notification endpoint (backchannel_client_notification_endpoint) with the OIDC Provider as part of its configuration. The OIDC Provider invokes this URL when the tokens are ready to be issued or an error has occurred in the flow. The client then calls into the /oauth2/token endpoint to retrieve the tokens/error information.
  • Push mode: The client registers a client notification endpoint (backchannel_client_notification_endpoint) with the OIDC Provider as part of its configuration. The OIDC Provider sends tokens/errors to this endpoint when the user completes backchannel authentication and the Provider generates the tokens/errors.
2247

📘

Note

The push mode is not recommended. This is primarily because the tokens are pushed to the client notification endpoint without
any form of client authentication. IBM Security Verify Access OIDC Provider does not support this mode.

User authentication and authorization

The OIDC Provider identifies the user using the hint provided and starts the authentication process. The specification is open-ended on how the user is authenticated.

IBM Security Verify Access OIDC Provider differentiates the scenarios for user authentication into the following categories:

  • internal authenticator indicates that the OIDC Provider will notify the user through a configurable communication mechanism, such as SMS, with a link to complete the flow. The notification message contains a URL in the form of /oauth2/ciba_user_authorize/{transactionID}. When the user launches this URL, the user taken through the typical authentication, authorization and consent process via a browser.

  • external authenticator indicates that the authentication mechanism is managed outside the OIDC Provider. The authentication engine can be the Verify Access Advanced Access Control. There are two modes of operation here:

    • The external authenticator has the ability to notify the OIDC Provider that the user authentication has been completed (successfully or not). The authenticator calls into an endpoint hosted on the OIDC Provider with a prescribed status payload: /oauth2/ciba_status_update/{transactionID}.

    • The external authenticator requires the OIDC Provider to check for completion through a polling mechanism. Here the authentication engine must provide an API that is pre-registered along with an authorization token. Example: https://<external_authenticator_host>/authentication_status/{transactionID}.

The relying party (client) calls into the /oauth2/token endpoint with client credentials, the grant type urn:openid:params:grant-type:ciba and the auth_req_id. The OIDC Provider responds with a specific error code if the authentication flow has not been completed.

📘

Note

When a client registers a notification endpoint (backchannel_client_notification_endpoint) and uses ping mode, the OIDC Provider does not
call into the registered external endpoint (second external pattern) to check for the transaction status. Only poll mode is supported.

1978

Updated 16 days ago