# SDK + PingFederate Integration Guide
## SDK + PingFederate Integration Guide
### Introduction
Use this guide to add Twosense MFA to your PingFederate SSO authentication flow.
### Requirements
* For Twosense to work properly, service providers must be configured to receive SAML responses as POST, not GET.
### Add Twosense Assets
Your Twosense contact will provide an integration package as a zip file. In this package there is a directory named `template`. Copy the **contents** of this directory to the `/server/default/conf/template` directory of your PingFederate installation.
After copying, the directory structure should look like this:
```
📁 server/
└── 📁 default/
└── 📁 conf/
└── 📁 template/
├── 📄 html.form.twosense.mfa.embedded.html
|-- 📄 html.form.twosense.session.embedded.html
├── 📄 html.form.twosense.challenge.html
└── 📁 assets/
└── 📁 scripts/
├── 📄 twosense-sw.js
└── 📄 twosense-client.js
```
### Install PingFederate Adapter
The integration package will also contain a file named `pf-twosense-adapter.jar`. Copy this file to your PingFederate installation's `/server/default/deploy/` directory, then restart PingFederate to load the adapter.
### Allow Twosense Resources
You will need to make some additional changes to your Ping configuration to allow the Twosense-related resources to load properly.
#### Allow Service Worker
The Twosense integration utilizes a service worker to perform MFA. To ensure it works properly, you must add the following lines to your PingFederate config's `/server/default/data/config-store/response-header-runtime-config.xml` file, inside of the `` element:
```xml
/
*.js
```
Once this change is made, the Ping service must be restarted for it to take effect.
#### Update Content Security Policy
If you have a custom content security policy, ensure that these directives are allowed:
* `img-src data:`
* `style-src 'self' 'unsafe-inline' *.googleapis.com`
* `worker-src 'self'`
* `connect-src 'self' http://127.0.0.1:27367 *.twosense.ai *.mixpanel.com`
* `script-src 'self' 'unsafe-inline' data:`
* `child-src 'self' data:`
* `font-src 'self' fonts.gstatic.com`
For example, here is a policy which will allow all the resources necessary for the Twosense SDK to work:
{% code overflow="wrap" %}
```
default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline' *.googleapis.com; script-src 'self' 'unsafe-inline' data:; child-src 'self' data:; connect-src 'self' http://127.0.0.1:27367 *.twosense.ai *.mixpanel.com; font-src 'self' fonts.gstatic.com
```
{% endcode %}
Note that your CSP may look different based on your situation; this is a minimal example.
If you are experiencing any additional CSP-related errors after these changes, please reach out to Twosense support.
#### Allow Local Network Access
{% hint style="warning" %}
If you use other Chromium-based browsers (such as Microsoft Edge) in your organization, you will need to repeat these steps for those browsers.
{% endhint %}
The Twosense SDK uses local requests to communicate with the Windows agent, and starting with Chrome version 142 this is automatically blocked unless explicitly allowed by the user or via Group Policy. In order to allow this behavior, you will need to add a policy exception for your PingFederate domain.
Use the [`LocalNetworkAccessAllowedForUrls`](https://chromeenterprise.google/policies/#LocalNetworkAccessAllowedForUrls) policy to grant the Twosense SDK service worker local network access. For example, if your PingFederate instance is hosted at `https://auth.example.com:9031`, you would add the following to the list of allowed URLs:
```
https://auth.example.com:9031/assets/scripts/twosense-sw.js
```
## Twosense MFA Adapter Configuration
### Create Twosense IdP Adapter
1. Navigate to **AUTHENTICATION** and select **IdP Adapters**.
2. Click **Create New Instance**.
3. In the **Type** tab, set the following:
* *Instance Name*: **Twosense MFA**
* *Instance ID*: **TwosenseMfaForm**
* *Type*: **Twosense IdP Adapter**
* Click **Next**.
4. In the fields labeled **Twosense IKEY** and **Twosense SKEY**, enter the values provided by your Twosense contact. If you do not have these values, please reach out to Twosense support.
5. If you require additional configuration options, such as proxy settings, press **Show Advanced Fields** and configure as needed.
6. Click **Next**.
7. Press **Test Connection** to verify connectivity to the Twosense service, then click **Next**.
8. In the **Extended Contract** tab, click **Next**.
9. In the **Adapter Attributes** tab, check the **Pseudonym** checkbox for the **result** attribute, and click **Next**.
10. In the **Adapter Contract Mapping** tab, click **Next**.
11. Review the **Summary** tab, and click **Save**.
### Modify the primary authentication adapter to return the userSid
The Twosense MFA adapter requires the user's `objectSid` attribute. In order to do this, we need to extend the contract of the primary login form IdP adapter.
1. Navigate to **AUTHENTICATION** and select **IdP Adapters**.
2. Click on the IdP adapter of your primary login HTML form.
3. In the **Summary** tab, click **Extend Contract**.
1. Under **Extend the Contract**, add the **objectSid** attribute.
2. Navigate back to the **Summary** tab.
4. In the **Summary** tab, click **Attribute Sources & User Lookup**.
1. In the **Attribute Source & User Lookup** tab, click **Add Attribute Source**.
1. In the **Data Store** tab, set the following:
* *ATTRIBUTE SOURCE ID*: **ActiveDirectory** (or another descriptive name)
* *ATTRIBUTE SOURCE DESCRIPTION*: **Active Directory** (or another descriptive name)
* *ACTIVE DATA STORE*: **{Your Active Directory Datastore}**
* Click **Next**.
2. In the **LDAP Directory Search** tab, set the following:
* *BASE DN*: **{Your Active Directory Search Base DN}**
* *Attributes to return from search*: **objectSid**
* Click **Next**.
3. In the **LDAP Binary Attribute Encoding Types** tab, select **SID** as the *Attribute Encoding Type* for *objectSID*, and click **Next**.
4. In the **LDAP Filter** tab, set **FILTER** to **sAMAccountName=${username}**, click **Next**.
5. In the **Summary** tab, click **Done**.
2. In the **Attribute Source & User Lookup** tab, click **Next**.
3. In the **Adapter Contract Fulfillment** tab, for **objectSid**:
* Select **LDAP (Active Directory)** as the *Source*.
* Select **objectSid** as the *Value*.
* Click **Next**.
4. In the **Issuance Criteria** tab, click **Next**.
5. In the **Summary** tab, click **Done**.
5. In the **Adapter Contract Mapping** tab, click **Save**.
### Embed Twosense Client in the primary authentication HTML template
The Twosense SDK detects the presence of the primary login form by looking for a specific attribute in the HTML form. In order for this detection to work, we need to modify the primary login form.
1. Navigate to **AUTHENTICATION** and select **IdP Adapters**.
2. Click on the IdP adapter of your primary login HTML form.
3. Find the name of the HTML form file by looking for the **Login Template** field in the **Summary** tab. The default value is `html.form.login.template.html`.
4. Find the file on your PingFederate instance under `pingfederate/server/default/conf/template/`.
5. Modify the HTML form to include the following attribute in the ` ` tag, add the following lines:
{% code overflow="wrap" %}
```html
```
{% endcode %}
{% hint style="warning" %}
You will need to embed the Twosense client script on each primary login form template where you want Twosense to be active.
Please note that the location of this snippet matters; it **must** be added before the closing `` tag, not in `