CIBA Authentication 

The term CIBA is used as a shorter and more reader-friendly label for OpenID Connect Client-Initiated Backchannel Authentication.

CIBA is a backchannel authentication flow initiated by the Relying Party backend, while the user reviews and approves the request through the iD Wallet application on a trusted device.

This section helps answer the following questions:

  • When should the Relying Party use CIBA Authentication?
  • How does the Relying Party initiate a backchannel authentication request?
  • How is the request associated with a known user?
  • How is the request delivered to the iD Wallet application?
  • How does the user approve, reject, or ignore the request?
  • How does the Relying Party retrieve or receive the authentication result?
  • What changes depending on the configured CIBA mode: poll, ping, or push?
  • How should rejection, timeout, and technical failure be handled?

CIBA Authentication can be used for scenarios such as:

  • transaction confirmation,
  • second factor authentication,
  • assisted or helpdesk-driven authentication,
  • shared-device scenarios.

During the flow, the Relying Party sends a backchannel authentication request to the Digital Credential Platform for a known user. The platform identifies the target iD Wallet application, delivers the request to the user's device, and manages authentication separately from the original interaction channel.

Within the iD Wallet application, the user reviews the request details, decides whether to approve or reject the request, and completes authentication on the mobile device.

Once the process reaches a final outcome, the result is conveyed back to the Relying Party through backchannel communication.

CIBA Integration Steps 

This section describes the configuration and integration steps that must be completed by the Relying Party to use CIBA Authentication with the Digital Credential Platform.

As a Relying Party, you need to:

  1. register or obtain your Relying Party client configuration with CIBA support,
  2. retrieve OpenID Connect metadata,
  3. prepare a test Digital Credential for authentication testing,
  4. send a CIBA backchannel authentication request,
  5. receive the CIBA response,
  6. handle user approval in the iD Wallet application,
  7. retrieve the authentication result,
  8. request tokens from the token endpoint,
  9. validate tokens and consume the shared attributes.

Step 1 — Request client registration with CIBA support through your partner manager 

Online Authentication is a pre-release feature. Client registration is not self-service.

Contact your IDEMIA partner manager to request access. Before reaching out, prepare the parameters listed in the Relying Party Integration Guide — specifically the CIBA-specific registration checklist.

After registration, you will receive:

  • client_id,
  • client credentials or key reference, depending on the configured token endpoint authentication method,
  • the platform endpoint base URL for your environment.

The selected CIBA delivery mode determines how the Relying Party receives or retrieves the authentication result. Ping mode is the preferred delivery mode and should be requested unless otherwise agreed with your partner manager.

Step 2 — Retrieve OpenID Connect Configuration 

Before initiating CIBA authentication, the Relying Party should retrieve the OpenID Connect configuration from the discovery endpoint: /.well-known/openid-configuration

The discovery response provides metadata required to configure the Relying Party client, including:

  • backchannel authentication endpoint,
  • token endpoint,
  • JWKS URI,
  • supported scopes,
  • supported claims,
  • supported grant types,
  • supported CIBA delivery modes,
  • supported token endpoint authentication methods.

The Relying Party should use the metadata returned by the discovery endpoint instead of hard-coding endpoint URLs where possible.

Step 3 — Prepare a test credential 

Before testing, ensure the test user has a Digital Credential available in the iD Wallet application.

See Setting up a test credential in the Relying Party Integration Guide.

In CIBA, the authentication request is initiated by the Relying Party backend. Therefore, the Relying Party must also be able to identify the test user upfront, for example by using a supported login_hint or id_token_hint.

Step 4 — Send the CIBA Backchannel Authentication Request 

The Relying Party backend starts the flow by sending a backchannel authentication request to the /bc-authorize endpoint exposed by the Digital Credential Platform.

The request must include client authentication according to the method configured during client registration.

A typical request contains the following parameters:

  • client_id
    Identifies the registered Relying Party client. Depending on the configured client authentication method, the client identifier may be provided as part of client authentication rather than as a separate request parameter.

  • client_notification_token
    A bearer token provided by the Relying Party and used by the OpenID Provider to authenticate the callback request sent to the client's notification endpoint.
    This parameter is required when the client is registered to use ping or push delivery mode.

  • scope
    Defines the requested OpenID Connect scopes. The openid scope is required.
    Requested scopes determine which credential attributes may be shared.
    For details, see Scope and claims handling.

  • login_hint or id_token_hint
    User hint used by the OpenID Provider to identify the user for whom the CIBA authentication request should be initiated.

    In CIBA, the Relying Party must be able to identify the user upfront in order to start the authentication process.

    The Relying Party must provide one of the supported user hint parameters:

    • login_hint — identifies the user by a known user identifier, such as a login or another agreed identifier.
    • id_token_hint — identifies the user based on a previously issued ID Token.

    Exactly one user hint parameter must be provided. Requests containing neither login_hint nor id_token_hint, or containing both parameters, are rejected.

  • acr_values
    Indicates the requested authentication context.
    For details, see Authentication Context Reference.

  • binding_message
    A human-readable message displayed to the user in the iD Wallet application. It helps the user recognize and verify the authentication request.

For clients registered with ping mode, which is the recommended delivery mode, the authorization server sends a notification to the registered backchannel_client_notification_endpoint after the user completes the authentication in the iD Wallet application.

The Relying Party can then call the token endpoint to retrieve the authentication result.

Example request:

HTTP
1POST /oxauth/restv1/bc-authorize HTTP/1.1
2Host: sample.host.com
3Authorization: Basic RkZGRkZGRkYtNzI3My02RDc0LTAwMDQtMDAwMDAwMDAwMDAxOlRlc3R0ZXN0MTIzIQ==
4Content-Type: application/x-www-form-urlencoded
5

6login_hint=63791797-1721-4c04-8c9b-ea272744fbe&
7acr_values=mid&
8binding_message=BINDING-MESSAGE&
9scope=openid+id_names&
10client_notification_token=8d67dc78-7faa-4d41-aabd-67707b374255

Step 5 — Receive the CIBA Response 

If the request is accepted, the Digital Credential Platform returns a response containing a request identifier.

The Relying Party uses this request identifier to correlate the CIBA request with the subsequent authentication result.

In ping mode, the same identifier is later returned in the ping callback and used by the Relying Party to request tokens from the /token endpoint.

The response may include:

  • auth_req_id,
  • expires_in,
  • interval.

The auth_req_id identifies the CIBA request. It is a unique identifier of the authentication request made by the Relying Party and must be stored by the Relying Party to correlate the flow and retrieve the token response later.

The expires_in value defines how long the request remains valid. It is a positive integer value indicating the lifetime of the auth_req_id in seconds, counted from the time the authentication request was received.

The interval value indicates the minimum amount of time, in seconds, that the Relying Party must wait before calling the /token endpoint.

In poll mode, it defines the minimum polling interval between token requests.

In ping mode, it can also be returned and should be respected if the Relying Party calls the /token endpoint after receiving the ping callback.

If no value is provided, the default value is 5 seconds.

Example response:

JSON
1{
2  "auth_req_id": "928437a27282877da1d45c6b0aa6462694520aacc29cbb22",
3  "interval": 2,
4  "expires_in": 120
5}

Step 6 — User Approval in the iD Wallet Application 

After the request is accepted, the Digital Credential Platform pairs the request with the user's iD Wallet application.

The user receives a push notification and can open the request card.

Inside the iD Wallet application, the user reviews:

  • the Relying Party requesting authentication,
  • the transaction,
  • any information displayed for confirmation,
  • the requested attributes.

The user may approve or reject the request.

If the user approves, authentication is performed on the trusted device.

If the user rejects the request or does not respond before the session expires, the Relying Party receives the corresponding unsuccessful result.

In a test scenario, the tester should approve sharing the requested attributes in the iD Wallet application and wait for the authentication result.

Step 7 — Retrieve the Authentication Result 

In the recommended ping mode, the Digital Credential Platform notifies the Relying Party when the authentication process has been completed in the iD Wallet application.

The notification is sent to the backchannel_client_notification_endpoint registered for the client.

The notification does not contain the authentication result itself. Instead, it contains the Authentication Request ID (auth_req_id) that allows the Relying Party to retrieve the result from the /token endpoint.

After receiving the ping notification, the Relying Party should:

  1. validate the callback request, including the bearer token provided in the Authorization header,
  2. correlate the received auth_req_id with the previously initiated CIBA request,
  3. call the /token endpoint using the auth_req_id and CIBA grant type,
  4. process the token response returned by the Digital Credential Platform.

Example ping callback:

HTTP
1POST /ciba/notify HTTP/1.1
2Host: client.example.org
3Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255
4Content-Type: application/json
5

6{
7  "auth_req_id": "928437a27282877da1d45c6b0aa6462694520aacc29cbb22"
8}

The value in the Authorization header corresponds to the client_notification_token provided by the Relying Party in the backchannel authentication request.

After the callback is validated, the Relying Party requests the token response from the /token endpoint by providing the received auth_req_id.

Other CIBA delivery modes may be supported depending on client registration:

  • In poll mode, the Relying Party periodically calls the /token endpoint until the authentication request reaches a final state.
  • In push mode, the authentication result is sent directly to the Relying Party callback endpoint.

However, ping mode is the recommended delivery mode.

Step 8 — Request Tokens from the Token Endpoint 

After receiving and validating the ping callback, the Relying Party requests tokens from the /token endpoint.

The Relying Party sends the auth_req_id received in the ping notification together with the CIBA grant type:

Text
1urn:openid:params:grant-type:ciba

The client must authenticate to the token endpoint using the authentication method configured during client registration.

Example token request:

HTTP
1POST /oxauth/restv1/token HTTP/1.1
2Host: sample.host.com
3Authorization: Basic RkZGRkZGRkYtNzI3My02RDc0LTAwMDQtMDAwMDAwMDAwMDAxOlRlc3R0ZXN0MTIzIQ==
4Content-Type: application/x-www-form-urlencoded
5

6grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&
7auth_req_id=928437a27282877da1d45c6b0aa6462694520aacc29cbb22

If the authentication has been completed successfully, the Digital Credential Platform returns a token response associated with the completed CIBA request.

The response contains an access token and may also contain an ID Token, depending on the client configuration, requested scopes, and approved attributes.

Example successful token response:

JSON
1{
2  "access_token": "eyJhbGciOiJSUzI1NiIs...",
3  "token_type": "Bearer",
4  "expires_in": 300,
5  "id_token": "eyJraWQiOiI5..."
6}

Step 9 — Validate Tokens and Complete the User Session 

After successful authentication, the Relying Party receives a token response from the /token endpoint.

The response typically contains an access token and may also contain an ID Token, depending on the requested scopes, claims, and client configuration.

The ID Token contains the identity claims approved by the user and requested through OpenID Connect scopes.

The shared attributes requested by the Relying Party are returned as claims in the ID Token.

The Relying Party should validate the received tokens before using them or completing the user session.

The validation should include:

  • token signature,
  • issuer (iss),
  • audience (aud),
  • expiration time (exp),
  • issued-at time (iat),
  • authentication context (acr), if required by the use case,
  • Authentication Request ID (auth_req_id) correlation,
  • requested claims and scopes,
  • required claims for the business use case.

If identity attributes are returned in the ID Token, the Relying Party should use them only after successful token validation.

For transaction confirmation use cases, a successful token response may indicate that the user has confirmed the requested transaction. The Relying Party can then continue or complete the business process.

Example ID Token

The ID Token is returned as a signed JWT. It consists of three Base64URL-encoded parts:

Text
1<header>.<payload>.<signature>

Example encoded ID Token:

Jwt
1eyJraWQiOiI5MGQ1Mjg5OS01OGIzLTRhYTEtYWQ4Ni1mMzQ5OTYzYzA2M2Jfc2lnX3JzMjU2IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoiai16Wnk2WlhNTHhDMzlTc2pFZ0IyZyIsInN1YiI6IjVmMDUwYTNlLTJhNGMtNDZjYi05NWQ3LWRmYzMxYzYxZjU0OCIsImNvZGUiOiJlMjlkMjJjZS04MWIwLTQ4YjMtOGQ1OS1jZjUxNmViODNiY2QiLCJ1cm46b3BlbmlkOnBhcmFtczpqd3Q6Y2xhaW06cnRfaGFzaCI6Ikg5aEtaUWpHcTdSQTEzWDRfc0Jnd3ciLCJhbXIiOlsiNjAiXSwiaXNzIjoiaHR0cHM6Ly9kYy1hcGkuYXBwLmRldi5pZGVudGl0eS1kZXYuaWRlbWlhLmlvIiwiZ2l2ZW5fbmFtZSI6IkpPRSBNSURETEUiLCJveE9wZW5JRENvbm5lY3RWZXJzaW9uIjoib3BlbmlkY29ubmVjdC0xLjAiLCJtaWRfdGVuYW50IjoiaWRlbWlhX2RjZGV2X2V1Y2VudHJhbDE0aXFocG51bG4iLCJhdWQiOiJGRkZGRkZGRi03MjczLTZENzQtMDAwNC0wMDAwMDAwMDAwMDEiLCJhY3IiOiJtaWQiLCJmdWxsX25hbWUiOiJKT0UgTUlERExFIE1BQ1NBTVBMRSIsInVybjpvcGVuaWQ6cGFyYW1zOmp3dDpjbGFpbTphdXRoX3JlcV9pZCI6IjkyODQzN2EyNzI4Mjg3N2RhMWQ0NWM2YjBhYTY0NjI2OTQ1MjBhYWNjMjljYmIyMiIsImNvcnJlbGF0aW9uSUQiOiI5YmQ2MGQ5ZS00ZTFhLTQyMzQtODI1OS0zNjJkOTkyOGY1MTMiLCJleHAiOjE3ODA0NzkxMDksImdyYW50IjoidXJuOm9wZW5pZDpwYXJhbXM6Z3JhbnQtdHlwZTpjaWJhIiwiaWF0IjoxNzgwNDc1NTA5LCJmYW1pbHlfbmFtZSI6Ik1BQ1NBTVBMRSJ9.SFBfJfjoTTFs_YHYbJdmIQgicvkcaKgDdA_EDFnwBa75syQ8WVfHm2HKj8_5uSPWytvNer6BiNBLwwkGaJGD7tE-dhqYL30SCPuYW-IOLMEFO2Tl4ixwIeZJPJ9aaW9VHpXVsrJvt2rRQgpXQFelMnCm7cw2smwDNT5GrmMKPSqGpa8Krpx7XjneHa19bDb2sesS5FOgsPVDIpCPBQVjsfMuhkpIjEE6VyjVI3EmnVU2tyB536OR6juFsrDYsF0y-CRqdd6MEWDVgWs67d4aGuqZSpeOVoYrUmsFL3kLL4OXLL_yfHNNqEq0uGotU-RNCP12Mr81b_SvbL_GZh3sFw

Example decoded ID Token header:

JSON
1{
2  "kid": "90d52899-58b3-4aa1-ad86-f349963c063b_sig_rs256",
3  "typ": "JWT",
4  "alg": "RS256"
5}

Example decoded ID Token payload:

JSON
1{
2  "at_hash": "j-zZy6ZXMLxC39SsjEgB2g",
3  "sub": "5f050a3e-2a4c-46cb-95d7-dfc31c61f548",
4  "code": "e29d22ce-81b0-48b3-8d59-cf516eb83bcd",
5  "urn:openid:params:jwt:claim:rt_hash": "H9hKZQjGq7RA13X4_sBgww",
6  "amr": ["60"],
7  "iss": "https://dc-api.app.dev.identity-dev.idemia.io",
8  "given_name": "JOE MIDDLE",
9  "mid_tenant": "idemia_dcdev_eucentral14iqhpnuln",
10  "aud": "FFFFFFFF-7273-6D74-0004-000000000001",
11  "acr": "mid",
12  "full_name": "JOE MIDDLE MACSAMPLE",
13  "urn:openid:params:jwt:claim:auth_req_id": "928437a27282877da1d45c6b0aa6462694520aacc29cbb22",
14  "correlationID": "9bd60d9e-4e1a-4234-8259-362d9928f513",
15  "exp": 1780479109,
16  "grant": "urn:openid:params:grant-type:ciba",
17  "iat": 1780475509,
18  "family_name": "MACSAMPLE"
19}

CIBA Error Handling 

The Relying Party must be prepared to handle unsuccessful CIBA outcomes.

Possible outcomes include:

  • user rejection,
  • session timeout,
  • expired request,
  • access denied,
  • authentication pending,
  • invalid request,
  • technical error.

A user rejection means that the user explicitly declined the CIBA request in the iD Wallet application.

A timeout or expired request means that the authentication was not completed within the allowed time. This may happen if the user did not respond to the notification or did not make a decision in the iD Wallet application.

An authentication pending response means that the request has not reached a final state yet. In ping mode, this should normally be handled by waiting for the ping callback before calling the /token endpoint.

A technical error indicates that the flow could not be completed due to a backend or platform-level issue.

The Relying Party should handle each outcome explicitly and provide an appropriate user or service response.

If authentication does not complete successfully, the Relying Party must not complete the user session or continue the protected business process.

The Relying Party should not treat the auth_req_id, ping callback, or access token alone as proof of authentication. Authentication is complete only after the token response has been retrieved and the returned tokens have been successfully validated.

CIBA flow overview 

CIBA separates backend request handling from user interaction.

The Relying Party communicates with the Digital Credential Platform server-to-server, while the user reviews and responds to the request in the iD Wallet application.

Unlike Online Authentication, the CIBA flow is initiated by the Relying Party backend. Therefore, the Relying Party must be able to identify the user upfront, for example by providing login_hint or id_token_hint.

At a high level, the flow works as follows:

  1. The Relying Party backend sends a CIBA backchannel authentication request to the /bc-authorize endpoint exposed by the Digital Credential Platform.
  2. The Digital Credential Platform validates the request, including client authentication, requested scopes, authentication context, and the provided user hint.
  3. If the request is valid, the platform returns a CIBA authentication response containing the Authentication Request ID (auth_req_id).
  4. The platform identifies the user based on the provided login_hint or id_token_hint and associates the CIBA request with the user's iD Wallet application.
  5. The user receives a push notification in the iD Wallet application with the authentication request.
  6. The user reviews the request details, including the relying party and requested data.
  7. The user approves or rejects the request in the iD Wallet application.
  8. If the user approves the request, the Digital Credential Platform completes the authentication process and associates the result with the corresponding auth_req_id.
  9. In the recommended ping mode, the Digital Credential Platform notifies the Relying Party's registered backchannel_client_notification_endpoint that the authentication result is ready.
  10. The Relying Party validates the ping callback and calls the /token endpoint with the received auth_req_id and the CIBA grant type (urn:openid:params:grant-type:ciba).
  11. The Digital Credential Platform returns a token response containing an access token and an ID Token associated with the completed CIBA authentication request.
  12. The Relying Party validates the returned tokens and uses the authentication result or identity information according to the configured business use case.

The flow connects a backend-initiated authentication request with a user decision made separately in the iD Wallet application. In ping mode, the callback only notifies the Relying Party that the result is ready; the actual authentication result is retrieved from the /token endpoint.

CIBA detailed flow 

Detailed OIDC CIBA flow
The following figure illustrates a sample Client Initiated Backchannel Authentication flow in details