PingOne

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. 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.

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."

  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 must provide one of the following three parameters as a way 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.

    Example with binding message

    The following is an example of a CIBA request with a binding message and a login_hint.

    …/as/cibaAuthorization?client_id=<clientId>&client_secret=<clientSecret>&scope=openid
&login_hint=<username>&binding_message=<bindingMessage>

    Example without binding message

    The following is an example without a binding message but with a login_hint:

    …/as/cibaAuthorization?client_id=<clientId>&client_secret=<clientSecret>&scope=openid
&login_hint=<username>

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

    For example:

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

  3. 3 PingOne invokes the 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.

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

      {
    "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:

      {
    "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:

      {
    "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:

      {
    "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.

  • Download the PingOne CIBA sample flow 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.

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 and ensuring the user knows what they are approving

  • 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 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 () next in the Subject field and define the subject of the email, such as Authentication request from ${appName}.

    4. Click the Checkmark icon () to save the subject.

    5. Click the Pencil icon () in the New Email field to configure the email message.

      For example:

      ${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 the Checkmark icon () to save the message.

      A screen capture of the CIBA email notification template with binding message.

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

    1. Click to create the second email template.

    2. In the Add Notification window, 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 the Pencil icon () in the Subject field to define the subject, such as Authentication request from ${appName}.

    4. Click the Checkmark icon () to save the subject.

    5. Click in the New Email field to define the message.

      For example:

      ${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 to save the email message.

      A screen capture of the CIBA email notification template without binding message.

  4. Go to User Experience > Notification Policies and click the Copy to clipboard icon () 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 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 > 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.

  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.
    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 () 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.

    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 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 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.

    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 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.

  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 Add Policies.

      2. On the DaVinci Policies tab, select the DaVinci CIBA flow policy you created in Configuring the 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.