CIBA Endpoint

Overview

The CIBA Endpoint allows a client to initiate an authentication request without redirecting the user’s browser. Instead, authentication is performed out-of-band on a separate device or channel (e.g., a mobile app, push notification, or secure device).

CIBA is particularly suited for:

  • Decoupled authentication flows
  • Devices without browsers (e.g., smart devices, kiosks)
  • High-assurance or step-up authentication scenarios

Read more here.

CIBA Modes

Mode Supported Description
Poll Yes Client polls the Token Endpoint until authentication completes. Do not poll more often than indicated in the response for the CIBA request.
Ping No Authway notifies client when authentication is complete. The standard still allows the client to also Poll, but it is better to wait for the notification.
Push No Tokens are pushed directly to the client.

Endpoint

The endpoint is advertised in the backchannel_authentication_endpoint in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/ciba

Parameters

Parameter Required Description
client_id Yes The client identifier registered with the IdP.
scope Yes Space-delimited list of scopes. Must include openid.
acr_values No Space seperated string with special requests from the client. See below.
login_hint Conditional Hint identifying the end user (unique identifier, username, email, social security number). If it is not the unique identifier it is recommended to also pass the tenant or the authentication might fail.
login_hint_token Conditional JWT issued by the client according to login hint token documentation.
id_token_hint Conditional Previously issued ID Token identifying the user.
binding_message No Message displayed to the user during authentication for request correlation.
requested_expiry No Desired lifetime (in seconds) of the authentication request. Can only shorten the lifetime configured on the client or in Authway.
request No Instead of providing all parameters as individual parameters, it is possible to provide a subset or all them as a JWT.
request_uri No URL of a pre-packaged JWT containing request parameters.
ui_locales No End-User’s preferred languages, represented as a space-separated list of language tag values, ordered by preference. For instance, the value “sv-SE en” represents a preference for Swedish as spoken in Sweden, then English (without a region designation).

Note Exactly one of login_hint, login_hint_token, or id_token_hint must be provided to identify the user.

acr_values parameters

The acr_values parameters are passed as “parameter:value” and if multiple parameters are passed they should be seperated with a space. For example:

tenant:priv idp:bankid
Parameter Description
idp The unique identifier of the sign-in method to use. See Control authentication method from the client.
tenant The unique identifier of an owner (tenant) that the user must belong to. See Only allow users from specific tenant

Usage

  1. Client Initiates Backchannel Authentication:
    The client builds a CIBA request and post it to the IdP:
https://[BASE_URL]/connect/ciba?
   scope=openid%20profile%20email&
   login_hint=e3b62a93-df39-4f8d-a6b4-f7a4a769fec4&
   binding_message=The%20company%20wants%20to%20identify%20you%20in%20your%20current%20phone%20call

The response from Authway is immediate and indicates how the client should proceed.

{
  "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
  "expires_in": 120,
  "interval": 5
}
  1. Authway Triggers Out-of-Band Authentication

The user is notified or instructed somehow what to do. Excatly how this is done can vary depending on scenario and mechanism for authenticating the user. User will approve or deny the request.

  1. Client Retrieves Result (Token Endpoint) The client polls (or is notified depending on mode) and exchanges auth_req_id at the Token Endpoint:
HTTP POST /connect/token
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic base64(client_id:client_secret)
 grant_type=urn:openid:params:grant-type:ciba&
 auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1

There are more details in the Token Endpoint documentation.

Security Considerations

  • binding_message helps users detect phishing or unsolicited requests.
  • Authentication requests are short-lived and one-time use.
  • Rate-limit polling to respect the interval value.