PingID Administration Guide

Configuring the PingID SDK adapter for PingFederate

About this task

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+

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:

  • [optConfigProxy] (requires PingFederate PingID SDK IDP Adapter 1.4+)

  • [optHtmlFormQRbutton]

  • [optCancelButton]

    • QR code based authentication requires PingFederate 9.2+ and PingFederate PingID SDK IDP Adapter 1.2+.

    • QR code based authentication is not supported for the PF Authentication API.

Steps

  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.

    1. In the PingFederate admin console, select: Identity Provider → AUTHENTICATION POLICIES → Selectors.

      ygg1564020794131

      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.

      mbs1564020795095

      The selector’s Type step is displayed.

    3. All fields in the Type step are mandatory:

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

      wsb1564020797025

      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.

      npn1564020798000

      The adapter’s Type step is displayed.

    3. Enter the following fields in the Type step:

      cto1564020798953

      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 Adapterfrom the dropdown options.

      PARENT INSTANCE

      Leave this field with the default value: None.

    4. Click NEXT to continue to the IdP Adapter step.

      uqz1564020799948

    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 [optConfigProxy]), is the preferred configuration.

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

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

        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.

      tki1569390722952

    7. Configure the following fields:

      HTML TEMPLATE
      This field is relevant only when the PF Authentication API is not used.

      • The name of the HTML template file whose screens are displayed to the user during the adapter authorization flow.

      • The default is pingid.sdk.login.template.html. This default value is applied even if this field is left empty.

      • Templates are located at /server/default/conf/template.

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

      CHANGE DEVICE
      This field is relevant only when the PF Authentication API is not used.

      • Choose whether the CHANGE DEVICE flow is allowed or denied.

        • Allow (default): Users will see the CHANGE DEVICE button on all relevant screens.

        • Deny: Users will not see the CHANGE DEVICE button, and will not have this option as part of their authentication flow.

      SUCCESS SCREENS
      This field is relevant only when the PF Authentication API is not used.

      • Choose whether to present the SUCCESS SCREENS as part of the authentication flow.

      • Default: Show to Users.

      ERROR SCREENS
      This field is relevant only when the PF Authentication API is not used.

      • Choose whether to present the ERROR screens as part of the authentication flow.

      • Default: Show to Users.

      TIMEOUT SCREENS
      This field is relevant only when the PF Authentication API is not used.

      • Choose whether to present the TIMEOUT screens as part of the authentication flow.

      • Default: Show to Users.

      QR CODE BASED AUTHENTICATION
      QR code based authentication is not supported for the PF Authentication API.

      Choose whether to use QR code based authentication, and in which cases:

      • Disable (default).

      • Conditionally enable: The QR code is displayed only when the user is unknown.

      • Always enable: Allows QR code based authentication, whether the user is known or not.

      • Default: QR code based authentication is the default authentication method, and the QR code is presented by default to the user.

        • The Default setting overrides the DEVICES SELECTION setting in the PingID SDK Applications Configuration in the PingOne admin web portal.

        • QR code based authentication is supported from PingFederate 9.0. Note that PingFederate PingID SDK IDP Adapter 1.2 will work on versions earlier than 9.0 only when QR CODE BASED AUTHENTICATION is set to Disable. Attempting to save QR CODE BASED AUTHENTICATION using a setting other than Disable on versions of PingFederate earlier than 9.0 will result in the error message.
      ROOTED/JAILBROKEN DEVICE

      • When an authentication device is identified as rooted or jailbroken:

        • Allow: Allow the authentication flow to continue.

        • Block (default): Deny the authentication request.

    8. Click NEXT to continue to the Extended Contractstep.

      The contract fields are displayed. In addition to the username attribute, the Core Contract also displays the following attributes:

      • pingid.sdk.status holds information about the level of authentication through which the user was authenticated. For further information about this attribute, refer to PingFederate access token - pingid.sdk.status attribute in the PingID SDK developer guide.From PingFederate PingID SDK IDP Adapter 1.5, the following Core Contract attributes provide information about devices that are rooted or jailbroken:

      • pingid.sdk.status.reason: Possible value is "device_rooted_or_jailbroken", which will appear only when the pingid.sdk.status has the value "pairing_error" and the device is rooted.

      • authenticating.device.rooted: True or false.

      • accessing.device.rooted: True or false.You can add more attributes to the contract under Extend the Contract, per the example below.

        wgo1569393938969

    9. Click NEXT to continue to the Adapter Attributes step.

      grt1564020803131

      Check the Pseudonym checkbox for the username attribute.

    10. Click NEXT through each of the subsequent steps.

    11. Click DONE in the Summary step to return to the Manage IdP Adapter Instances screen.

    12. Click SAVE to persist changes.

      *Adapter session considerations*

      + It is important to update the <pf_install>/pingfederate/server/default/conf/size-limits.conf file to adjust the session configuration to ensure that the PingID SDK adapter functions correctly.

      + Note that the settings in size-limits.conf are global, affecting all adapters.

  3. Create and configure a policy:

    Create a policy in PingFederate, for the purpose of determining the authentication flow.

    The flexibility of PingFederate permits implementation of different policy models, and may vary according to organizational or application requirements.

    The following example describes a basic policy configuration for the PingID SDK adapter, highlighting mandatory settings. The example defines a 1st factor authentication method before the SDK adapter, from which the username must then be mapped to the SDK adapter.

    1. In the PingFederate administrative console, select: Identity Provider → AUTHENTICATION POLICIES → Policies.

      dvm1564020805121

    The Manage Authentication Policies screen is displayed.

    1. Enter the following fields:

      osp1564020806585

      1. Check the ENABLE IDP AUTHENTICATION POLICIES checkbox.

      2. The SDK selector or Tracked HTTP Parameter:

        • PingFederate 9.1.x and below: The first ACTION in the policy chain must be mapped to the SDK selector created earlier:

          • Open the ACTION dropdown.

          • Click IdP Adapters.

          • Select the SDK selector.

          • The SDK selector has only one return status: Success.

            For the policy’s following action, select HTML Adapter (or any other 1st factor adapter) from the ACTION dropdown.

        • PingFederate 9.2+: If the "payload" parameter has been added to PingFederate’s Tracked HTTP Parameters (see https://support.pingidentity.com/s/document-item?bundleId=pingfederate-92&topicId=adminGuide/pf_t_defineAuthenticationPolicies.html):

          • Open the ACTION dropdown.

          • Click HTML Adapter (or any other 1st factor adapter).

          • Select the HTML Adapter.

      3. The HTML Adapter has two resulting states:

        • Fail:

          The action following Fail will be Done, meaning the policy flow ends at this point.

        • Success:

          Select the SDK Adapter for the action following Success.

      4. Map the username from the HTML Adapter (or any other 1st factor adapter) step in the policy flow to the SDK Adapter:

        • Click on Options below the SDK Adapter.

          The Incoming User ID screen opens.

          syn1564020807632

          • Source: Select HTML Adapter.

          • Attribute: Select username.

        • Click Done to return to the Manage Authentication Policies screen.

          ebq1564020808512

      5. An Authentication Policy Contract should then be mapped into the target application (SP Connection, OAuth Grant Mapping, etc.) for which you want to provide SSO services.

        For example:

        cvp1564020810028

      6. Click Save.

  4. (Optional) Configure proxy settings:

    Define an entry in the PingFederate run.properties file, as described in the PingFederate admin guide (see https://documentation.pingidentity.com/pingfederate/pf/index.shtml#adminGuide/pf_t_configureForwardProxyServerSettings.html).

    The native PingFederate method for defining a proxy is the preferred option. The following deprecated method is still supported:

    1. Manually add a pingidsdk_proxy_url entry to your PingID SDK properties file:

      pingidsdk_proxy_url=<your proxy address>

    2. Do not change the pingidsdk_url entry.

    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.

  5. (Optional) HTML Form Adapter QR code button - passwordless login:

    • QR code based authentication requires PingFederate 9.2+ and PingFederate PingID SDK IDP Adapter 1.2+.

    • QR code based authentication is not supported for the PF Authentication API.

    QR code based authentication is an alternative method, which offers secure, passwordless authentication. QR code based authentication can effectively eliminate the need for first factor authentication. This method combines the strength of a strong secure authentication measure, with a streamlined user experience.

    The following image presents the user HTML Form Adapter access screen. Once configured, the user can either use the traditional username and password sign on at the left, or select the Sign on with QR code button on the right. Sign on with QR code generates a QR code image which the user can scan with a trusted mobile device, thus achieving rapid secure passwordless authentication.

    qof1564020811460

    1. Refer to the Enable third-party identity providers without registration topic in the PingFederate documentation, specifically the following steps:

      1. Make a note of which authentication policy contract is currently being used in your policy.

      2. Create a local identity profile.

        When creating the local identity profile, you must add "QR Code" as an Authentication Source.

        + piu1564020812124

        +

      3. Configure the HTML Form Adapter instance for customer identities.

    2. Navigate to Identity Provider → Authentication Policies → Policies.

      dvm1564020805121

    3. In the Authentication Policies page, edit your PingID SDK authentication policy.

    4. Below the HTML Form Adapter, expand the policy tree and select Rules.

      qww1564020812711

    5. In the Rules popup, fill in the following values:

      Field Value

      Attribute Name

      policy.action

      Condition

      equal to

      Value

      QR Code

      Result

      QR Code

      tcu1564020813241

    6. Click Done.

    7. Below the HTML Form Adapter branch, the QR CODE policy result is displayed, in addition to the FAIL and SUCCESS branches.

      hbj1564020813988

    8. In the QR Code result, select the SDK Adapter, and finish building the flow according to the steps in the [createConfigurePolicy] section.

      The final result should appear similar to the following image:

      vaq1564020814649

  6. (Optional) Add a CANCEL button to the QR code based authentication flows:

    • QR code based authentication requires PingFederate 9.2+ and PingFederate PingID SDK IDP Adapter 1.2+.

    • QR code based authentication is not supported for the PF Authentication API.

    There may be scenarios where an organization wants to allow users of QR code based authentication to cancel an authentication request. This can be achieved by configuring a CANCEL button in the QR based authentication flow, and defining its functionality in the authentication policy. By default, the CANCEL button is not enabled.

    1. Configure a CANCEL Button in the HTML template:

      1. Open the HTML template file <PingFederate installation folder>/pingfederate-<version>/pingfederate/server/default/conf/template/pingid.sdk.login.template.htmlin a text editor.

      2. Scroll down to the QR Code section. You’ll see the following commented out lines, where you can add a CANCEL button in the QR image page, deep link page and loading page:

        <!-- uncomment the following line if you "cancel" is supported -->
<!-- <a class="button" onclick="cancelQRCode(this)"href="javascript:void(0);">$messages.getMessage("pingid.sdk.authenticating.button.qrcode.cancel")</a>-->

      3. To add a CANCEL button to the page, uncomment the second line (containing the <a> tags).

    2. Add a CANCEL function in the authentication policy:

      1. In the PingFederate admin console, navigate to Identity Provider → Authentication Policies → Policies.

    dvm1564020805121

    1. In the Authentication Policies page, edit your PingID SDK authentication policy.

    2. Below the SDK Adapter, expand the policy tree and select Rules.

      qgr1564020815242

    3. In the Rules popup, fill in the following values:

      Field Value

      Attribute Name

      policy.action

      Condition

      equal to

      Value

      canceled

      Result

      Fallback (You may choose a different name.)

      gut1564020815785

    4. Click Done.

    5. Below the SDK Adapter branch, the FALLBACK policy result is displayed, in addition to the FAIL and SUCCESS branches.

      psm1564020816420

    6. To configure it as a restart flow action, select Restart.

      You can also choose different actions. For example, redirect the user to a different adapter.

    7. Click Done.

    8. Click Save.

    9. (Optional): If you want to change the action’s default value ("canceled") to a different value:

      • Go to the following line in the HTML template:

        <form id="cancelQRCodeForm" name="cancelQRCodeForm"
          action="$resumePath?cancel=1&action=canceled" method="post">
          <input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken"
          encode="false"/>
</form>

      • Change &action=canceled to &action=<your value>. Make sure that this new value is identical to the "Value" field in the Authentication Policies → Rules popup.

      • Click Done.

      • Click Save.