---
title: Configuring a CIBA flow
description: PingOne supports client-initiated backchannel authentication (CIBA), enabling users to approve out-of-band authentication requests.
component: pingone
page_id: pingone:use_cases:p1_configure_ciba_flow
canonical_url: https://docs.pingidentity.com/pingone/use_cases/p1_configure_ciba_flow.html
revdate: April 20, 2026
section_ids:
  example-use-case: Example use case
  how-it-works: How it works
  goals: Goals
  what-youll-do: What you'll do
  before-you-begin: Before you begin
  tasks: Tasks
  creating-the-email-templates: Creating the email templates
  steps: Steps
  p1-ciba-davinci-flow: Configuring the DaVinci flow
  steps-2: Steps
  adding-an-application: Adding an application
  steps-3: Steps
  validation: Validation
  troubleshooting: Troubleshooting
---

# Configuring a CIBA flow

Client-initiated backchannel authentication (CIBA) is an OpenID Connect (OIDC) extension that enables an end user to use an application on one device and grant consent to the application request on another device. Learn more in the [OIDC CIBA specification](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html).

The following devices are involved:

* **A consumption device**: A device the end user interacts with that initiates a CIBA request, such as a point-of-sale system.

* **An authentication device**: The device used by the end user, such as their mobile phone, to grant or deny consent to authenticate with the OpenID Provider.

  To qualify as an authentication device, the user's device must meet requirements, including that the authorization server must recognize the device and must be able to map it to the identified user based on the `login_hint` parameter in the CIBA request. The `login_hint` parameter is a hint related to the end user being authenticated, such as their username or email address. Learn more about [CIBA requests](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) in the OIDC CIBA specification.

CIBA provides increased security and improves the user experience by allowing end users to seamlessly grant or deny authentication requests on their mobile device.

## Example use case

1. The user attempts to purchase $50 worth of gas into a gas station pump point-of-sale terminal (consumption device).

2. The point-of-sale system initiates a CIBA request to PingOne.

3. PingOne sends an email to the user's verified email address containing a magic link that prompts the user to grant or deny the authentication request.

4. The user grants the authentication request sent to their email address from their mobile phone (authentication device)

5. The point-of-sale system allows the user to get $50 worth of gas.

## How it works

The high-level process with PingOne as the OpenID provider is as follows:

![A diagram of the high-level CIBA process using PingOne and DaVinci."](_images/p1-ciba-diagram.png)

1. 1 The user interacts with the consumption device, and the application on the consumption device sends a backchannel request (`/cibaAuthorization` endpoint) to PingOne as the OpenID provider.

   A CIBA request contains the following parameters in the request body:

   | Parameter                    | Description                                                                                                                                                                                                                                                                                                                  |
   | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `client_id`                  | The application's client ID. Required when the application's **Token Endpoint Authentication Method** is set to **Client Secret Post**. Learn more about the [CIBA Authorize endpoint](https://developer.pingidentity.com/pingone-api/auth/openid-connect-oauth-2/authorize-ciba.html) in the PingOne API documentation.     |
   | `client_secret`              | The application's client secret. Required when the application's **Token Endpoint Authentication Method** is set to **Client Secret Post**. Learn more about the [CIBA Authorize endpoint](https://developer.pingidentity.com/pingone-api/auth/openid-connect-oauth-2/authorize-ciba.html) in the PingOne API documentation. |
   | `scope`                      | The `openid` scope value is required. You can optionally include the `offline_access` scope value to request a refresh token if the application has the refresh token grant type enabled.                                                                                                                                    |
   | `binding_message` (optional) | The message displayed to the end user on the consumption device and authentication device, matching the authentication request to the transaction and ensuring the user knows what they're approving.                                                                                                                        |

   A CIBA request must also include one of the following three parameters for the application on the consumption device to identify the target end user:

   | Parameter          | Description                                                                                                     |
   | ------------------ | --------------------------------------------------------------------------------------------------------------- |
   | `login_hint`       | A string PingOne uses to map to a user, such as username or email address.                                      |
   | `id_token_hint`    | An ID token issued by PingOne representing a previous authentication for the target end user.                   |
   | `login_hint_token` | A JSON Web Token (JWT) created by the application on the consumption device, containing the user ID as a claim. |

   Learn more about [CIBA request parameters](https://developer.pingidentity.com/pingone-api/auth/openid-connect-oauth-2/ciba-intro.html) in the PingOne API documentation.

2. 2 PingOne returns a CIBA response to the application on the consumption device.

   For example:

   ```json
   {
       "auth_req_id": "003d2608-adeb-49af-8e8d-ec22f2a6198d",
       "expires_in": 120,
       "interval": 2
   }
   ```

3. 3 PingOne invokes the PingOne DaVinci CIBA flow to launch the out-of-band authentication request.

4. 4 The DaVinci CIBA flow locates the user based on the information from the CIBA request and sends an email to the user's email address on record containing a magic link.

5. 5 The application on the consumption device receives the CIBA response and begins polling PingOne for tokens, waiting for the user's authentication response. Learn more about poll mode in the [OpenID CIBA Flow specification](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#token_request).

   1. If the user hasn't responded to the out-of-band authentication request, PingOne returns the following token response:

      ```json
      {
          "error": "authorization_pending",
          "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request is still pending. (Correlation ID: <id>)"
      }
      ```

   2. If the application on the consumption device sends token requests too frequently, PingOne returns the following token response:

      ```json
      {
          "error": "slow_down",
          "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request is still pending. Please slow down the poll requests. (Correlation ID: <id>)"
      }
      ```

   3. If the user declines the authentication request, PingOne returns the following token response:

      ```json
      {
          "error": "access_denied",
          "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request has been denied. (Correlation ID: <id>)"
      }
      ```

   4. If the CIBA request has expired, PingOne returns the following token response:

      ```json
      {
          "error": "expired_token",
          "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request for the provided auth_req_id has expired. (Correlation ID: <id>)"
      }
      ```

6. 6 The user opens the email sent to their authentication device and decides whether to grant or deny the out-of-band authentication request.

7. 7 The consumption device sends another poll request to PingOne, and if the user grants the authentication request, PingOne returns an access token and ID token.

## Goals

After completing this use case, you'll know how to:

* Configure a CIBA flow using PingOne and DaVinci.

* Send email notifications for out-of-band authentication requests to your users.

* Enable your users to grant or deny authentication requests initiated from a consumption device.

## What you'll do

1. Create notification templates for CIBA authorization email requests to the end user.

2. Configure a DaVinci CIBA sample flow to orchestrate the user experience and send email notifications to the end user.

3. Add an OIDC application to launch the DaVinci flow.

## Before you begin

* Ensure you have a PingOne organization and environment with the PingOne SSO, PingOne MFA, and DaVinci services added. Learn more in [Starting a PingOne trial](../getting_started_with_pingone/p1_start_a_p1_trial.html).

* Download the [PingOne CIBA sample flow](https://marketplace.pingone.com/item/pingone-ciba) from the Ping Identity Marketplace and extract the contents of the `.zip` archive to a folder on your computer.

* Create a notification policy in PingOne to set notification limits that can be sent to users per day. Learn more in [Notification Policies](../user_experience/p1_creating_a_notification_policy.html).

## Tasks

### Creating the email templates

Create two notification templates for the authentication request emails sent to the end user:

* Email with an authorization binding message, matching the authentication request to the transaction

* Generic email without a binding message requesting the user's approval

#### Steps

1. In the PingOne admin console, go to **User Experience > Notification Templates**.

2. Create an email template for the authorization binding message:

   1. Click **[icon: plus, set=fa]**to create the first of the two email templates.

   2. In the **Add Notification** modal, do the following:

      1. In the **Type** list, select **General**.

      2. Enter a name for the template, such as `CIBA with binding message`.

      3. Click **Create**.

   3. In the **Email** section, click the **Pencil** icon ([icon: pencil, set=fa]) next to the **Subject** field and define the subject of the email, such as `Authentication request from ${appName}`.

   4. Click the **Checkmark** icon ([icon: check, set=fa]) to save the subject.

   5. Click [icon: pencil, set=fa]in the **New Email** field to configure the email message.

      For example:

      ```html
      ${appName} wants to access your account.
      <p>
      Open this link in your browser to review the request: ${magicLink}
      <p>
      The authorization binding message for this request is ${bindingMessage}
      <p>
      If you do not recognize this request, ignore this email.
      <p>
      Request ID: ${authReqId}
      ```

   6. Click [icon: check, set=fa]to save the message.

      ![A screen capture of the CIBA email notification template with binding message.](_images/p1-ciba-notification-template-binding-message.png)

3. Create an email template for the generic message without the authorization binding:

   1. Click **[icon: plus, set=fa]**to create the second email template.

   2. In the **Add Notification** modal, do the following:

      1. In the **Type** list, select **General**.

      2. Enter a name for the template, such as `CIBA without binding message`.

      3. Click **Create**.

   3. In the **Email** section, click [icon: pencil, set=fa]in the **Subject** field to define the subject, such as `Authentication request from ${appName}`.

   4. Click [icon: check, set=fa]to save the subject.

   5. Click [icon: pencil, set=fa]in the **New Email** field to define the message.

      For example:

      ```html
      ${appName} wants to access your account.
      <p>
      Open this link in your browser to review the request: ${magicLink}
      <p>
      If you do not recognize this request, ignore this email.
      <p>
      Request ID: ${authReqId}
      ```

   6. Click [icon: check, set=fa]to save the email message.

      ![A screen capture of the CIBA email notification template without binding message.](_images/p1-ciba-notification-template-without-binding.png)

4. Go to **User Experience > Notification Policies** and click the **Copy to clipboard** icon ([icon: copy, set=fa]) for the notification policy ID you plan to use for sending notifications. You'll add the notification policy ID to the DaVinci flow.

### Configuring the DaVinci flow

Add the notification template IDs in your DaVinci flow so that DaVinci can send notifications to your end users requesting their authentication response.

#### Steps

1. In DaVinci, on the **Flows** tab, click **[icon: plus, set=fa]Add Flow** and select **Import Flow**.

2. Upload the `ciba-flow.json` file from the sample flow `.zip` file and click **Import**.

3. Enable the required flow settings:

   1. Click the **More Options** (⋮) icon and then click **Flow Settings** to open the flow settings panel.

   2. Click to enable the **PingOne Flow** toggle.

   3. Enable the **CIBA Flow** toggle.

   4. Click **Save**.

      ![A screen capture of the DaVinci flow settings requirements.](_images/p1-ciba-davinci-flow-settings.png)

4. In the flow, configure the **Binding message check node False** and **True** paths.

   ![A screen capture of the DaVinci CIBA flow with the Binding message nodes highlighted.](_images/p1-davinci-ciba-flow-binding-message.png)

   * False path

     1. Locate the **Binding message check** node.

     2. From the **False** path, click the **Sends email notification** node.

     3. In the configuration settings panel, click the **Gear** icon ([icon: gear, set=fa]) at the top. In the **PingOne Notification Details** modal, paste the notification policy ID you copied from PingOne into the **Notification Policy ID** field.

        ![A screen capture of the DaVinci CIBA flow PingOne Notification Details modal.](_images/p1-davinci-ciba-flow-notification-details.png)

     4. Click **Apply** and then click **Close**.

     5. In the configuration settings panel, for **Notification Name**, select the email template with the binding message.

     6. Click **Apply** and then click **Close**.

   * True path

     1. From the **True** path, click the **Sends email notification** node.

     2. In the configuration settings panel, for **Notification Name**, select the email template without the binding message.

     3. Click **Apply** and then click **Close**.

5. Save and deploy the flow.

6. Add a DaVinci flow policy for the CIBA flow:

   1. Go to the **Applications** tab and click **[icon: plus, set=fa]Add Application**.

   2. In the **Name** field, enter a name for the application and click **Create**.

   3. To edit the application, select the application in the **Applications** list.

   4. On the **Flow Policy** tab, click **[icon: plus, set=fa]Add Flow Policy**.

   5. In the **Policy Name** field, enter a name for the flow policy.

   6. Select **PingOne Flow Policy** to enable flows in the policy to be launched directly through PingOne.

   7. Click **Next**.

   8. In the flow list, select the **Show only CIBA Flows** checkmark to filter the results to only CIBA flows.

   9. Click the CIBA sample flow you imported and select either **Latest Version** or the most recent version of it.

      ![A screen capture of the DaVinci CIBA flow policy version selection.](_images/p1-davinci-ciba-flow-policy-version.png)

   10. Click **Next**.

   11. (Optional) Add weight distribution, such as `100` for 100 percent, and analytics information for each flow and flow version. Learn more in [Configuring a flow policy](https://docs.pingidentity.com/davinci/applications/davinci_configuring_a_flow_policy.html) in the DaVinci documentation.

   12. Click **Create Flow Policy**.

### Adding an application

Create an OIDC application in PingOne and add the DaVinci flow policy so that PingOne can launch the CIBA flow.

#### Steps

1. In the PingOne admin console, go to **Applications > Applications**.

2. Click the **[icon: plus, set=fa]**icon.

3. Create the application profile by entering the following:

   1. **Application Name**: Enter a unique identifier for the application, such as `CIBA app`.

   2. **Description** (optional): A brief description of the application.

   3. **Icon** (optional): A graphic representation of the application. Use a file up to 1 MB in JPG, JPEG, GIF, or PNG format.

   4. **Application Type**: Click **OIDC Web App**.

   5. Click **Save**.

4. Edit the application configuration as follows:

   1. On the **Configuration** tab:

      1. Select **CIBA** for **Grant Type** and clear other pre-selected grant types and response types.

      2. In the **Token Endpoint Authentication Method** list, select any authentication method except **None**. The default is **Client Secret Basic**.

      3. Click **Save**.

   2. On the **Policies** tab:

      1. Click **[icon: plus, set=fa]Add Policies**.

      2. On the **DaVinci Policies** tab, select the DaVinci CIBA flow policy you created in [Configuring the DaVinci flow](#p1-ciba-davinci-flow).

      3. Click **Save**.

## Validation

Now that you've configured a CIBA flow, validate the flow works:

1. Deploy and test the flow and verify the end-user paths function as expected.

2. Check the PingOne audit log for the **CIBA Authentication Succeeded** event, which applies to when the user approves or declines the request:

   1. Go to **Monitoring > Audit** and enter the report parameters to filter the results to include your flow test.

   2. Click **Run**.

   3. Verify that a **CIBA Authentication Succeeded** event type displays in the results.

## Troubleshooting

To troubleshoot issues when configuring the CIBA flow, check the PingOne audit log for the **CIBA Authentication Failed** event:

1. Go to **Monitoring > Audit** and enter the report parameters to limit the results to the show your flow testing.

2. Click **Run**.

3. Look for a **CIBA Authentication Failed** event type in the results.

4. Click **View** in the **Details** column for any **CIBA Authentication Failed** event types and review the event details to determine what issues caused the flow to fail.