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.challenge.html
            └── 📁 assets/
                └── 📁 scripts/
                    ├── 📄 twosense-sw.js
                    └── 📄 twosense-client.js

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 <con:config> element:

<!-- Add inside the <con:config> element -->
<con:map name="Service-Worker-Allowed">
    <con:item name="value">/</con:item>
    <con:item name="include-patterns">*.js</con:item>
</con:map>

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:

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

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.

Create RADIUS Password Credential Validator

1. Navigate to SYSTEM and select Password Credential Validators.

2. Click Create New Instance.

3. In the Type tab, set the following:

   • Instance Name: Twosense MFA RADIUS PCV

   • Instance ID: TwosenseMfaRadiusPcv

   • Type: RADIUS Username Password Credential Validator

   • Click Next.

4. In the Instance Configuration tab, click Add a new row to 'RADIUS Servers', and set the following:

   • Hostname: radius.twosense.ai

   • Authentication Port: {Provided by Twosense}

   • Authentication Protocol: PAP

   • Shared Secret: {Provided by Twosense}

   • Click Update.

5. Press Show Advanced Fields and set the NAS Identifier to any value ending in "-Challenge". For example, "PingFederate-Challenge".

   • Click Next.

6. In the Extended Contract tab, click Next.

7. Review the Summary tab, and click Save.

Create Twosense MFA IdP Adapter

This adapter will be used by the Twosense to automate MFA requests.

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 Form

   • Instance ID: TwosenseMfaForm

   • Type: HTML Form IdP Adapter

   • Click Next.

4. In the IdP Adapter tab, under Password Credential Validator Instance, click Add a new row to 'Credential Validators':

   • Select Twosense MFA RADIUS PCV

   • Click Update.

   • Set the following fields:

     • Challenge Retries: 1

     • Click Show Advanced Fields.

     • Login Template: html.form.twosense.mfa.embedded.html

     • Login Challenge Template: html.form.twosense.challenge.html

     • Allow Username Edits During Chaining: true

     • Fail Authentication on Account Lockout: true

     • Click Next.

5. In the Extended Contract tab, click Next.

6. In the Adapter Attributes tab, check the Pseudonym checkbox for the username attribute, and click Next.

7. In the Adapter Contract Mapping tab, click Configure Adapter Contract.

   1. In the Attribute Sources & User Lookup tab, click Next.

   2. In the Adapter Contract Fulfillment tab, click Next.

   3. In the Issuance Criteria tab, click Next.

   4. In the Summary tab, click Done.

   5. Click Next.

8. 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 <form> tag data-twosense-id="primary-login-form". The following is an example of a modified HTML form:

<form method="post" action="$url" autocomplete="off" data-twosense-id="primary-login-form">

1. At the bottom of the template, directly before the closing </body> tag, add the following lines:

<script
  src="/assets/scripts/twosense-client.js"
  data-sw-path="/assets/scripts/twosense-sw.js">
</script>

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 </body> tag, not in <head> or elsewhere.

Create Authentication Policy

You can create a new authentication policy, or modify an existing one. These instructions will assume you are creating a new policy.

1. Navigate to AUTHENTICATION and select Policies.

2. Click Add Policy.

3. Set Name to Twosense MFA Policy or another descriptive name.

4. Under Policy, select any SP connection Selector you wish to use.

5. Under NO, click Continue.

6. Under YES, select your primary login HTML form IdP adapter.

   1. Under FAIL, select DONE.

   2. Under SUCCESS, select your Twosense MFA Form.

      • Click Options, and in the Incoming User ID form:

        • Set Attribute to objectSid.

        • Check User ID Authenticated.

        • Click Done.

   3. Under SUCCESS for the Twosense and manual MFA IdP adapters, select the appropriate policy contract.

   4. Under FAIL, select the action you wish to occur when communication between PingFederate and Twosense fails.

   5. Configure the Rules for the Twosense MFA Form adapter according to the table in the section below.

7. Click Done.

8. In the Policies tab, click Save.

Twosense MFA Form Adapter Rules

The Twosense adapter will set the policy.action attribute to different values for different outcomes. The following table lists the possible values and their meaning. Use these values to create rules to fit your organization's needs.

policy.action Value	Outcome
no-agent	The Twosense agent was not detected on the client machine.
twosense-client-error	An internal error occurred in the Twosense SDK.
challenge	The user was not authenticated (i.e., due to a low trust score) and should be presented an additional MFA challenge.

For example, here's how you can customize your policy with rules based on the outcome:

Then you can use these results to determine the next steps in your policy: