--- title: Configuring the PingID SDK adapter for PingFederate description: 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. component: pingid page_id: pingid:pingid_sdk:pid_configuring_sdk_adapter_for_pf canonical_url: http://docs.pingidentity.com/pingid/pingid_sdk/pid_configuring_sdk_adapter_for_pf.html revdate: June 7, 2024 section_ids: about-this-task: About this task steps: Steps --- # 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: * [\[createConfigureSelector\]](#createConfigureSelector) * [\[createConfigureAdapter\]](#createConfigureAdapter) * [\[createConfigurePolicy\]](#createConfigurePolicy) The following optional enhancements improve the user authentication experience: * [\[optConfigProxy\]](#optConfigProxy) (requires PingFederate PingID SDK IDP Adapter 1.4+) * [\[optHtmlFormQRbutton\]](#optHtmlFormQRbutton) * [\[optCancelButton\]](#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. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * **PingFederate 9.1.x and below**: Creation of a PingID SDK Payload Handling Selector is mandatory. * **PingFederate 9.2+**: Creation of a PingID SDK Payload Handling Selector is not required, only if the "`payload`" parameter has been added to PingFederate's Tracked HTTP Parameters (see ): ``` *Identity Provider → AUTHENTICATION POLICIES → Policies → Tracked HTTP Parameters → Add*: [.codeph]``payload`` ``` | 1. In the PingFederate admin console, select: **Identity Provider → AUTHENTICATION POLICIES → Selectors**. ![ygg1564020794131](_images/ygg1564020794131.png) 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](_images/mbs1564020795095.png) The selector's **Type** step is displayed. 3. All fields in the **Type** step are mandatory: ![dif1564020796179](_images/dif1564020796179.png) * 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](_images/wsb1564020797025.png) 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](_images/npn1564020798000.png) The adapter's **Type** step is displayed. 3. Enter the following fields in the **Type** step: ![cto1564020798953](_images/cto1564020798953.png) * 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. ![uqz1564020799948](_images/uqz1564020799948.png) 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\]](#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](https://apidocs.pingidentity.com/pingid-sdk/guide/pf-adapter/pid_c_SDKforPFdynamicParameters/) 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 PAIRING**Bypass field configuration, the user will be allowed into the application or denied access. Refer to [User device pairing](https://apidocs.pingidentity.com/pingid-sdk/guide/overview/pid_c_SDKpairFirstDevice/) 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](_images/tki1569390722952.png) 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 "`_.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 Contract**step. 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](https://apidocs.pingidentity.com/pingid-sdk/guide/pf-adapter/pid_c_SDKforPFpingidSdkStatus) 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](_images/wgo1569393938969.png) 9. Click **NEXT** to continue to the **Adapter Attributes** step. ![grt1564020803131](_images/grt1564020803131.png) 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 `/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. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * The SDK selector or Tracked HTTP Parameter: * **PingFederate 9.1.x and below**: The PingID SDK Payload Handling Selector that was created earlier must be the first action in a policy actions chain. * **PingFederate 9.2+**: The PingID SDK Payload Handling Selector is not required, only if the "`payload`" parameter has been added to PingFederate's Tracked HTTP Parameters (see ). * The SDK adapter created earlier must participate in the policy flow. | 1. In the PingFederate administrative console, select: **Identity Provider → AUTHENTICATION POLICIES → Policies**. ![dvm1564020805121](_images/dvm1564020805121.png) The **Manage Authentication Policies** screen is displayed. 1. Enter the following fields: ![osp1564020806585](_images/osp1564020806585.png) 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 ): * 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](_images/syn1564020807632.png) * **Source**: Select **HTML Adapter**. * **Attribute**: Select **username**. * Click **Done** to return to the **Manage Authentication Policies** screen. ![ebq1564020808512](_images/ebq1564020808512.png) 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](_images/cvp1564020810028.png) 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 [Configuring forward proxy server settings](http://docs.pingidentity.com/pingfederate/12.3/administrators_reference_guide/pf_configure_forward_proxy_server_settings.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= ``` 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](_images/qof1564020811460.png) 1. Refer to [Enabling third-party identity providers without registration](http://docs.pingidentity.com/pingfederate/12.3/administrators_reference_guide/pf_enabling_thirdparty_identity_providers_without_registration.html) 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](_images/piu1564020812124.png)+ | 3. Configure the HTML Form Adapter instance for customer identities. 2. Navigate to **Identity Provider → Authentication Policies → Policies**. ![dvm1564020805121](_images/dvm1564020805121.png) 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](_images/qww1564020812711.png) 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](_images/tcu1564020813241.png) 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](_images/hbj1564020813988.png) 8. In the **QR Code** result, select the **SDK Adapter**, and finish building the flow according to the steps in the [\[createConfigurePolicy\]](#createConfigurePolicy) section. The final result should appear similar to the following image: ![vaq1564020814649](_images/vaq1564020814649.png) 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-/pingfederate/server/default/conf/template/pingid.sdk.login.template.html`in 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: ``` ``` 3. To add a CANCEL button to the page, uncomment the second line (containing the \ tags). 2. **Add a CANCEL function in the authentication policy**: 1. In the PingFederate admin console, navigate to **Identity Provider → Authentication Policies → Policies**. ![dvm1564020805121](_images/dvm1564020805121.png) 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](_images/qgr1564020815242.png) 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](_images/gut1564020815785.png) 4. Click **Done**. 5. Below the **SDK Adapter** branch, the **FALLBACK** policy result is displayed, in addition to the FAIL and SUCCESS branches. ![psm1564020816420](_images/psm1564020816420.png) 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: ```
``` * Change `&action=canceled` to `&action=`. Make sure that this new value is identical to the "`Value`" field in the **Authentication Policies → Rules** popup. * Click **Done**. * Click **Save**.