ciba

Implementing the CIBA Flow

CIBA (Client-Initiated Backchannel Authentication), also known as Transactional Authentication, is a modern OAuth 2.0 authentication flow that enables secure, device-to-device authentication. It allows users to authenticate on one device (like their mobile phone) while logging into an application on a completely different device (like a Smart TV, kiosk, or terminal).

This flow is ideal for scenarios where users need to authenticate on devices with limited input capabilities or where enhanced security is required. CIBA enables transaction-based authentication where each authentication is a secure transaction between devices.

How it works?

Before we step into the mechanics of working lets us understand some useful parameters.

Parameter Name	Description
client_id	client which represents the business-App in cidaas, where the Resource Owner wants to have access
scope	scope which the user asks for. E.g. openid profile email gives access to user profile and email data
login_hint	User identifier (email, phone number, or username) to identify the user for authentication
binding_message	Optional message displayed to the user during authentication to provide context
requested_expiry	Optional requested expiration time in seconds for the authentication request
grant_type	urn:openid:params:grant-type:ciba needs to be mentioned in token request to get a token
auth_req_id	Unique transaction identifier returned from the CIBA initiation request, used to poll for tokens

Let's take up the scenario of a user who wants to get access to the business app on a Smart TV.

Step 1: The requesting device (Smart TV) initiates authentication by making a POST call to /authz-srv/ciba with user identification and client credentials. The endpoint expects parameters like client_id, scope, login_hint, and optionally binding_message and requested_expiry.

Step 2: cidaas validates the request and creates a unique auth_req_id (transaction ID). The system sends a push notification to the user's registered mobile device (cidaas Authenticator app) showing the authentication request with details like application name, binding message, and device/location information.

Step 3: The user receives a push notification on their mobile device and reviews the authentication request.

Step 4: The user reviews and approves the authentication request on their mobile device using biometrics (Face ID, Touch ID, fingerprint) or PIN.

Step 5: The requesting device (Smart TV) polls the token endpoint using the requestId at the recommended interval. The application makes a POST call to /token-srv/token with grant_type=urn:openid:params:grant-type:ciba and the requestId.

Step 6: Once the user has approved the request, cidaas returns the access tokens to the requesting device. The application will receive a response with access_token, id_token, refresh_token (optional), token_type, and expires_in.

Step 7: The business app can use the access_token via the authorization header to get a resource.

Step 8: Resource server checks for the authorization token with

• A: Introspect call to cidaas.

The introspect call is a request made by the resource server to validate the token's authenticity and obtain information about the associated user or client

• B: Offline check: Valid signature, Expired-Time in the Future.

Step 9: If valid, the resource server responds with the resource.

Note

CIBA requires users to have the cidaas Authenticator app installed and registered with at least one authentication method (biometrics, PIN, or pattern). The application must have the CIBA grant type (urn:openid:params:grant-type:ciba) enabled in its settings.

Technical integration

API	Description	Link to API
Initiate CIBA Authentication	This call initiates the CIBA authentication flow and returns an auth_req_id for polling	Link to API
Poll for Tokens	This API must be called at the recommended interval using the auth_req_id to retrieve access tokens	Link to API

Example Request

Initiate CIBA Authentication:

curl --location '{{domain}}/authz-srv/ciba' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic OTVkZWFmYzktYjE2OS00YWI0LWEzMzYtNDI2YWEyOTEwM2UxOlBEUXFWakQyNTEzZ1hzeWh4VjdTdkRMcUlXMG5oeW5Wd0RvcE1lemN0Ym55Tw==' \
--data '{
    "client_id": "your_client_id",
    "scope": "openid profile email",
    "login_hint": "[email protected]",
    "binding_message": "Login to Smart TV",
    "requested_expiry": 300
}'

Response:

{
  "auth_req_id": "abc123def456",
  "expires_in": 300,
  "interval": 5
}

Poll for Tokens:

curl --location '{{domain}}/token-srv/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic OTVkZWFmYzktYjE2OS00YWI0LWEzMzYtNDI2YWEyOTEwM2UxOlBEUXFWakQyNTEzZ1hzeWh4VjdTdkRMcUlXMG5oeW5Wd0RvcE1lemN0Ym55Tw==' \
--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' \
--data-urlencode 'auth_req_id=abc123def456' \
--data-urlencode 'client_id=your_client_id'

Response (when pending):

{
  "error": "authorization_pending",
  "error_description": "The authorization request is still pending"
}

Response (when approved):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Need Support?

Please contact us directly on our support page