--- title: Configuring the CIBA Authenticator for PingID SDK description: Create and configure a Client-Initiated Backchannel Authentication (CIBA) Authenticator for PingID SDK. component: pingid page_id: pingid:pingid_sdk:pid_configuring_ciba_authenticator_pid_sdk canonical_url: http://docs.pingidentity.com/pingid/pingid_sdk/pid_configuring_ciba_authenticator_pid_sdk.html revdate: June 7, 2024 section_ids: about-this-task: About this task steps: Steps choose-from: Choose from: choose-from-2: Choose from: choose-from-3: Choose from: --- # Configuring the CIBA Authenticator for PingID SDK Create and configure a Client-Initiated Backchannel Authentication (CIBA) Authenticator for PingID SDK. ## About this task This procedure describes the process of creating and configuring a Client Initiated Backchannel Authentication (CIBA) Authenticator for the purpose of authenticating users via an out-of-band authentication method. Prerequisites: * PingFederate 9.3+ * PingID SDK Package v1.10+ (comprising PingID SDK Integration Kit v1.7+ and PingID SDK Adapter for PingFederate v1.6+) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | - The PingID SDK CIBA Authenticator supports mobile devices only. - The PingID SDK CIBA Authenticator is part of the PingID SDK integration with PingFederate, but is not part of the PingID SDK Adapter for PingFederate. - The CIBA configuration for PingID SDK assumes that a user has at least one mobile device. - A push notification is sent to the user's primary device. If the user's primary device is not a mobile, the push notification is sent to their first enabled mobile device. - If an authenticating device is bypassed or pushless, that device is ignored. - The admin console UI menu labels presented in this topic are those used in PingFederate 9.3. These may differ slightly from other versions of PingFederate. | ## Steps 1. In the PingFederate admin console, select: **OAuth Server → CIBA → Authenticators**. ![juc1576769957520](_images/juc1576769957520.png) 2. Click **Create New Instance** to create a new authenticator, or click on an existing authenticator to edit it. 3. Enter the CIBA authenticator's initial instance definitions: 1. **INSTANCE NAME**: Enter a descriptive name for this authenticator. 2. **INSTANCE ID**: Enter a string which will be used as an ID for this authenticator. Spaces are not allowed. 3. **TYPE**: Select **PingID SDK CIBA Authenticator** from the dropdown options. 4. Click **NEXT**. The CIBA authenticator's **Type** step is displayed. ![til1576770214220](_images/til1576770214220.png) 5. Enter the fields in the authenticator's **Type** step: 1. **PINGID SDK PROPERTIES**: Upload the PingID SDK properties file from your PingOne admin console: * In the PingOne admin console, go to **Setup → PingID → CLIENT INTEGRATION → INTEGRATE WITH PINGID SDK → SETTINGS FILE**. * Click **Download**. You may want to provide the file with a more meaningful name. | | | | - | ------------------------------------------------------------------------------------ | | | The PingID SDK settings file should not be confused with the PingID properties file. | 1. **APPLICATION ID**: Enter the application ID that was generated by PingID SDK in your application configuration: * In the PingOne admin console, go to **Applications → PingID SDK Applications**, and copy the **Application ID**. 2. **HEARTBEAT TIMEOUT**: The duration in seconds that thePingID SDK CIBA Authenticator should wait for a heartbeat to verify PingID SDK services, before timing out (default 30 seconds). 6. Click **Show Advanced Fields**. The **Type** step's advanced fields are displayed. ![wri1576770917051](_images/wri1576770917051.png) 7. Enter the following advanced fields: 1. **MESSAGES FILE**: The prefix of the name of the PingID SDK messages file. * The default is `pingid-sdk-messages`. This default value is applied even if this field is left empty. * Templates are located at `/server/default/conf/language-packs.` * The file prefix (for example `pingid-sdk-messages`) may be changed, but the suffix for the locale must be in the format "`_.properties`", for example: `pingid-sdk-messages_en.properties`. * The following parameters are required for the default values of the push message's title and body texts in the **DYNAMIC PUSH MESSAGE** and **DYNAMIC CLIENT CONTEXT** fields: * `pingid.sdk.ciba.authentication.push.title`: populates the `pushMessageTitle` parameter. * `pingid.sdk.ciba.authentication.push.body.start`: The default **DYNAMIC PUSH MESSAGE** template uses this key. * `pingid.sdk.ciba.authentication.push.body.user.binding.msg`: The default **DYNAMIC CLIENT CONTEXT** template uses this key. These parameters may be replaced, or removed. 2. **DYNAMIC PUSH MESSAGE**: A velocity language template that PingID SDK uses to pass push authentication messages to the device. The template is used to populate the `pushMessageBody` parameter, using the following variables: * `OOBAuthRequestContext`: Refer to the PingFederate developer documentation . * `LanguagePackMessages`: Refer to the PingFederate developer documentation . 3. **DYNAMIC CLIENT CONTEXT**: A velocity language template that PingID SDK uses to pass push authentication messages to the device. The template is used to populate the `clientContext` parameter, using the following variables: * `OOBAuthRequestContext`: Refer to the PingFederate developer documentation . * `LanguagePackMessages`: Refer to the PingFederate developer documentation . * `SimpleTitle`: String. The push message's title. * `SimpleBody`: String. The push message's body text. * `JsonHelp`: Jose4j JSONValue class. Refer to . 8. Save the configuration. 9. **Optional:** Configure a dynamic notification push category or dynamic application ID. CIBA authenticators support dynamic notification push categories and dynamic application IDs, and their configurations are similar. * Dynamic notification push categories A CIBA authenticator can receive a notification push category as a dynamic attribute. This enables a single CIBA authenticator to work with multiple categories, and submit push notifications according to categories. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Dynamic notification push category** configuration requires the following software versions:- PingFederate 9.3+ - PingID SDK Package v1.13+ comprising: * PingID SDK Integration Kit v1.9+ * PingID SDK Adapter for PingFederate v1.8+ * PingID SDK CIBA Authenticator 1.1+ | * Dynamic application IDs A CIBA authenticator can receive an application ID as a dynamic attribute. This enables a single CIBA authenticator to work with multiple applications. The dynamic application ID overwrites the default application ID value (see APPLICATION ID configuration above). If the CIBA authenticator receives an invalid or non-existent application ID, an error is generated. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Dynamic application ID** configuration requires the following software versions:- PingFederate 9.3+ - PingID SDK Package v1.14.4+ comprising: * PingID SDK Integration Kit v1.11+ * PingID SDK Adapter for PingFederate v1.8.1+ * PingID SDK CIBA Authenticator 1.1.1+ | 10. In the PingFederate admin console, select: **OAuth Server → CIBA → Authenticators**. 11. In the authenticator's **Extended Contract** step, under **Extend the Contract**: ### Choose from: * To configure a dynamic notification push category, enter `pingIdSdkPushCategory` * To configure a dynamic application ID, enter `pingIdSdkApplicationId` Click **ADD**. 12. Click **SAVE**. 13. In the PingFederate admin console, select: **OAuth Server → CIBA Request Policies**. 14. Click **Add Policy**. For more information, see [Managing CIBA request policies](http://docs.pingidentity.com/pingfederate/12.3/administrators_reference_guide/help_cibapoliciesmanagementtasklet_cibapoliciesmanagementstate.html) and [Defining issuance criteria for identity hint contract](http://docs.pingidentity.com/pingfederate/12.3/administrators_reference_guide/help_requesthintcontractmappingtasklet_requesthintcontractissuancecriteriastate.html) in the PingFederate Administration Guide. 15. In the **Identity Hint Contract** step, under **Extend the Contract**: ### Choose from: * To configure a dynamic notification push category, enter `request.pingIdSdkPushCategory` * To configure a dynamic application ID, enter `request.pingIdSdkApplicationId` Click **ADD**. 16. Click **NEXT**. The CIBA policy's **Identity Hint Mapping** step is displayed. 17. Click **Manage Fulfillment**. 18. In the **Identity Hint Mapping** step: ### Choose from: * To configure a dynamic notification push category, select `Request` in the **Source** column of the `request.pingIdSdkPushCategory` contract. * To configure a dynamic application ID, select `Request` in the **Source** column of the `request.pingIdSdkApplicationId` contract. Click **ADD**. 19. Save the configuration.