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+)
Note:
  • 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.
  1. In the PingFederate admin console, select: OAuth Server > CIBA > Authenticators.

  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.

  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.
      Important: The PingID SDK settings file should not be confused with the PingID properties file.
    2. 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.
    3. 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.

  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 “_<locale>.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:
    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:
  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.
    Note:
    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.
    Note:
    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:
    • 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 and Defining issuance criteria for identity hint contract in the PingFederate Administration Guide.
  15. In the Identity Hint Contract step, under Extend the Contract:
    • 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:
    • 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.