--- title: Configuring an adapter instance description: To get started with the integration, deploy the PingOne Protect Integration Kit files to your PingFederate directory. component: pingone page_id: pingone:pingone_protect_integration_kit:pf_p1_protect_ik_configuring_an_adapter_instance canonical_url: https://docs.pingidentity.com/integrations/pingone/pingone_protect_integration_kit/pf_p1_protect_ik_configuring_an_adapter_instance.html revdate: June 28, 2024 page_aliases: ["pf_p1_protect_ik_p1_protect_idp_adapter_settings_reference.adoc"] section_ids: steps: Steps example: Example: direct-changes-to-javascript-files: Direct changes to Javascript files idp-adapter-settings-reference: IdP Adapter settings reference --- # Configuring an adapter instance To get started with the integration, deploy the PingOne Protect Integration Kit files to your PingFederate directory. ## Steps 1. In the PingFederate administrative console, go to **Authentication > Integration > IdP Adapters**. Click **Create New Instance**. 2. On the **Type** tab, set the basic adapter instance attributes: 1. In the **Instance Name** field, enter a name for the adapter instance. 2. In the **Instance ID** field, enter a unique identifier for the adapter instance. 3. In the **Type** list, select **PingOne Protect IdP Adapter**. Click **Next**. 3. **Optional:** On the **IdP Adapter** tab, in the **Additional User Attributes (optional)** section, you can configure additional attributes to send to PingOne Protect. 4. **Optional:** On the **IdP Adapter** tab, use the **Browser-based location** option to instruct the Signals SDK to include the browser-based location if the user consents to the inclusion of this information. Select **Get location - consent window shown by Protect Adapter** if you want PingFederate to trigger the consent window. Select **Get location - consent window shown separately** if you want one of your own pages to trigger the consent window. 5. **Optional:** On the **IdP Adapter** tab, in the **Additional Risk Predictors (optional)** section, you can configure custom risk predictors to send to PingOne Protect, beyond the predictor types provided out-of-the-box. 1. Click **Add a new row to 'Additional Risk Predictors (optional)'**. 2. In the **Incoming Attribute Name** field, enter the name of an attribute from any authentication source that appears earlier in your PingFederate authentication policy than the PingOne Protect IdP Adapter. 3. In the **PingOne Protect Attribute** list, select the PingOne attribute that you want to populate. 4. In the **Action** column, click **Update**. 5. To add more attributes, repeat steps a - d. 6. **Optional:** On the **IdP Adapter** tab, in the **PingOne Protect API Response Mappings** section, map the attributes from PingOne Protect Evaluation API response to the attribute contract. These attributes will become available in your PingFederate authentication policy. 1. Click **Add a new row to 'PingOne Protect API Response Mappings'**. 2. In the **Local Attribute** field, enter a name of your choosing for an attribute. 3. In the **PingOne Protect API Attribute Mapping** field, enter the JSON Pointer syntax for the source PingOne attribute. ### Example: For example, the JSON pointer `/details/ipAddressReputation/level` will return the IP address repuation level, such as `LOW`. 4. In the **Action** column, click **Update**. 5. To add more attributes, repeat steps a - d. | | | | - | ------------------------------------------------------------------------------------------------------ | | | If you skip performing a fraud evaluation in the adapter, the response mappings might not be returned. | 7. On the **IdP Adapter** tab, configure the adapter instance using the settings listed in [IdP Adapter settings reference](#idp-adapter-settings-reference). Click **Next**. 8. On the **Actions** tab, test your connection to PingOne Protect. Resolve any issues that are reported, and then click **Next**. 9. On the **Extended Contract** tab, add any attributes that you included in the **PingOne Protect API Response Mappings** section of the **IdP Adapter** tab. Click **Next**. 10. On the **Adapter Attributes** tab, set pseudonym and masking options as shown in [Set pseudonym and masking options](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_setting_pseudonym_masking_options.html) in the PingFederate documentation. Click **Next**. 11. On the **Adapter Contract Mapping** tab, configure the contract fulfillment details for the adapter as shown in [Define the IdP adapter contract](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/help_authnadapterinstancetasklet_plugincontractstate.html) in the PingFederate documentation. Click **Next**. 12. On the **Summary** tab, check and save your configuration. Click **Save**. ## Direct changes to Javascript files In addition to the configuration in the PingFederate administrative console, you must make the following change directly to the relevant Javascript file if you want the device data in the SDK payload to be provided as a signed JWT. * Open the file `\server\default\conf\template\assets\scripts\pingone-protect-device-profiling.js`. * Add this line: `universalDeviceIdentification: true` | | | | - | ---------------------------------------------------------------------------------------- | | | The option of using a signed JWT was introduced in version 1.0.4 of the integration kit. | ## IdP Adapter settings reference Field descriptions for the PingOne Protect IdP Adapter configuration screen. **Standard fields** | Field | Value | Description | | ----------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PingOne Environment** | *\* | Your PingOne Environment. Create connections in **System > External Systems > PingOne Connections**.This field is blank by default. | | **PingOne Risk Policy** | *\* | The risk policy used by PingOne for the risk evaluation. Overrides the environment and global default policy selections. This list is populated when you select a PingOne Environment. | **Advanced fields** | Field | Value | Description | | ---------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Include Dynamic Device Profile** | * **Enabled** * **Disabled** | When enabled, PingFederate will include a device profile in the risk evaluation. | | **Device Profiling Timeout** | `5000` (default) | The amount of time in milliseconds that PingFederate waits for the device profiling script to collect device details. Applies only if **Device Profiling Method** is set to **Captured by this adapter**. | | **Device Profile Cookie Name** | `pingone.protect.device.profile` (default) | The name of the cookie that indicates whether the device profile has been captured. | | **Failure Mode** | - **Continue with fallback policy decision** - **Fail** (default) | When PingOne Protect is unavailable or an error occurs, this setting determines whether the user's sign-on attempt should fail or continue with a pre-determined policy decision. | | **Fallback Policy Decision Value** | * `LOW` * `MEDIUM` (default) * `HIGH` * `unknown` | The fallback fraud evaluation level to use in the authentication policy when the PingOne Protect service is unavailable or an error occurs, and **Failure Mode** is set to **Continue with fallback policy decision**. | | **API Request Timeout** | `2000` (default) | The amount of time in milliseconds that PingFederate allows when establishing a connection with PingOne Protect or waiting for a response to a request. A value of `0` disables the timeout. | | **Proxy Settings** | - **No Proxy** - **System Defaults** (default) - **Custom** | Defines proxy settings for outbound HTTP requests. | | **Custom Proxy Host** | *\* | The proxy server host name to use when **Proxy Settings** is set to **Custom**.This field is blank by default. | | **Custom Proxy Port** | *\* | The proxy server port to use when **Proxy Settings** is set to **Custom**.This field is blank by default. | | **Custom Connection Pool** | `50` (default) | The number of connections to PingOne Protect. Can be between `25` and `200`. Recommended that the number be left at the default value. |