This procedure describes the process of creating and configuring a PingID SDK adapter for the purpose of providing pairing and authentication solutions integrated with PingFederate.

Prerequisites:

  • PingFederate 8.2+
  • If your installation should support integration with the PingFederate Authentication API, the following minimum software versions are required:
    • PingFederate 9.3+
    • PingFederate PingID SDK IDP Adapter 1.7+
Note:

The admin console UI menu labels in this document are those used in PingFederate 9.0. These may differ slightly from earlier versions of PingFederate.

The creation and configuration of an adapter comprises three mandatory steps:

The following optional enhancements improve the user authentication experience:

  1. Create and configure a selector or tracked HTTP parameter:
    Create an instance of the PingID SDK Payload Handling Selector, which is required as a preprocessor to an authentication policy that uses the PingID SDK adapter.
    Important:
    1. In the PingFederate admin console, select: Identity Provider > AUTHENTICATION POLICIES > Selectors.
      The Manage Authentication Selector Instances screen is displayed.
    2. Click Create New Instance to create a new selector, or click on an existing selector to edit it.

      The selector’s Type step is displayed.

    3. All fields in the Type step are mandatory:
      INSTANCE NAME
      Enter a descriptive name for this selector.
      INSTANCE ID
      Enter a string which will be used as an ID for this selector. Spaces are not allowed.
      TYPE
      Select PingID SDK Payload Handling Selector from the dropdown options.
    4. Click NEXT.
    5. Click NEXT in the Authentication Selector screen.
    6. Click DONE in the Summary screen, to return to the Manage Authentication Selector Instances screen.
    7. Click SAVE to persist changes.
  2. Create and configure an adapter:
    1. In the PingFederate admin console, select: Identity Provider > APPLICATION INTEGRATION > Adapters.

      The Manage IdP Adapter Instances screen is displayed.

    2. Click Create New Instance to create a new adapter, or click on an existing adapter to edit it.

      The adapter’s Type step is displayed.

    3. Enter the following fields in the Type step:

      INSTANCE NAME
      Enter a descriptive name for this adapter.
      INSTANCE ID
      Enter a string which will be used as an ID for this adapter. Spaces are not allowed.
      TYPE
      Select PID SDK Adapter from the dropdown options.
      PARENT INSTANCE
      Leave this field with the default value: None.
    4. Click NEXT to continue to the IdP Adapter step.

    5. Configure the following fields:
      PINGID SDK PROPERTIES
      • Mandatory.
      • 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.
        • If you use a proxy, note that the deprecated configuration of the pingidsdk_proxy_url entry in the PingID SDK properties file is still supported.

          Configuration of an entry in the PingFederate run.properties file (see Configure proxy settings), is the preferred configuration.

          Note: If entries are defined in both the PingFederate run.properties and the PingID SDK properties files, the definition in the PingID SDK properties file will take precedence.
        Important: The PingID SDK settings file should not be confused with the PingID properties file.
      APPLICATION ID
      • Mandatory.
      • 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.
      Note:
      • From PingFederate 8.4 and PingFederate PingID SDK IDP Adapter 1.2, multiple applications can be linked to a single PingID SDK adapter for PingFederate. This is achieved with dynamic parameters overriding the value of Application ID. Refer to Dynamic parameters support in the PingID SDK developers guide for further details.
      • In earlier versions of PingFederate and the PingID SDK Adapter, each application requires its own separate PingID SDK adapter for PingFederate.
      DEVICE PAIRING
      • Choose how users will pair their first device when it's a mobile device:
        • Automatic (default).

          Once authorization of the adapter completes successfully, the automatic pairing process begins.

        • Manual.

          Once authorization of the adapter completes, the pairing process is not initiated. The pairing process is initiated separately. Depending on the UNPAIRED USERS - MANUAL PAIRINGBypass field configuration, the user will be allowed into the application or denied access.

      refer to User device pairing in the PingID SDK developer's documentation.
      UNPAIRED USERS - MANUAL PAIRING
      • Relevant only when Manual pairing is selected:
      • Choose whether to allow users without a paired device to Bypass Authentication (default), or Block User - Require Pairing a device before continuing.
      UNPAIRED USERS - WEB LOGIN
      Choose whether to allow users without a paired device to Bypass Authentication (default), or Block User - Require Pairing a device before continuing, when signing in from a web platform.
      ADDITIONAL TRUSTED DEVICES
      When a user who already has a paired device, is pairing an additional device, choose whether to allow the user to approve pairing of the new device using a device in their existing trusted devices network and Verify New Devices with Primary Device (default), or to Pair Each Device Individually, without primary device verification.
      MFA TIMEOUT
      The duration of the PingID SDK MFA session with the adapter in minutes, before it times out and users need to authenticate again. (Default: 10 minutes, maximum 30 minutes.)
      USER VERIFICATION
      When the application setting VERIFY DEVICES USING APPLE/ANDROID PUSH SERVICE is enabled (in the PingOne admin console: Applications > PingID SDK Applications > [Application] > Configuration) and there is no approval for a silent push sent for extra verification, choose whether to Regard as Success or Regard as Failure.
      Note: This configuration is relevant only to logins from mobile devices, and will be applied to pushless device scenarios, and events when the network is not accessible.
      AUTHENTICATION DURING ERRORS
      If there are network problems or the PingID SDK service is unreachable, choose whether to Bypass users (default) or Block users who attempt to authenticate.
      HEARTBEAT TIMEOUT
      The duration in seconds that the PingID SDK adapter should wait for a heartbeat to verify PingID SDK services, before timing out (default 30 seconds).
    6. Click Advanced fields.
      The advanced fields are displayed.