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:
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:
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:
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.
Twosense MFA Adapter Configuration
Create RADIUS Password Credential Validator
Navigate to SYSTEM and select Password Credential Validators.
Click Create New Instance.
In the Type tab, set the following:
Instance Name: Twosense MFA RADIUS PCV
Instance ID: TwosenseMfaRadiusPcv
Type: RADIUS Username Password Credential Validator
Click Next.
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.
Press Show Advanced Fields and set the NAS Identifier to any value ending in "-Challenge". For example, "PingFederate-Challenge".
Click Next.
In the Extended Contract tab, click Next.
Review the Summary tab, and click Save.
Create Twosense MFA IdP Adapter
This adapter will be used by the Twosense to automate MFA requests.
Navigate to AUTHENTICATION and select IdP Adapters.
Click Create New Instance.
In the Type tab, set the following:
Instance Name: Twosense MFA Form
Instance ID: TwosenseMfaForm
Type: HTML Form IdP Adapter
Click Next.
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.
In the Extended Contract tab, click Next.
In the Adapter Attributes tab, check the Pseudonym checkbox for the username attribute, and click Next.
In the Adapter Contract Mapping tab, click Configure Adapter Contract.
In the Attribute Sources & User Lookup tab, click Next.
In the Adapter Contract Fulfillment tab, click Next.
In the Issuance Criteria tab, click Next.
In the Summary tab, click Done.
Click Next.
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.
Navigate to AUTHENTICATION and select IdP Adapters.
Click on the IdP adapter of your primary login HTML form.
In the Summary tab, click Extend Contract.
Under Extend the Contract, add the objectSid attribute.
Navigate back to the Summary tab.
In the Summary tab, click Attribute Sources & User Lookup.
In the Attribute Source & User Lookup tab, click Add Attribute Source.
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.
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.
In the LDAP Binary Attribute Encoding Types tab, select SID as the Attribute Encoding Type for objectSID, and click Next.
In the LDAP Filter tab, set FILTER to sAMAccountName=${username}, click Next.
In the Summary tab, click Done.
In the Attribute Source & User Lookup tab, click Next.
In the Adapter Contract Fulfillment tab, for objectSid:
Select LDAP (Active Directory) as the Source.
Select objectSid as the Value.
Click Next.
In the Issuance Criteria tab, click Next.
In the Summary tab, click Done.
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.
Navigate to AUTHENTICATION and select IdP Adapters.
Click on the IdP adapter of your primary login HTML form.
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
.Find the file on your PingFederate instance under
pingfederate/server/default/conf/template/
.Modify the HTML form to include the following attribute in the
<form>
tagdata-twosense-id="primary-login-form"
. The following is an example of a modified HTML form:
At the bottom of the template, directly before the closing
</body>
tag, add the following lines:
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.
Navigate to AUTHENTICATION and select Policies.
Click Add Policy.
Set Name to Twosense MFA Policy or another descriptive name.
Under Policy, select any SP connection Selector you wish to use.
Under NO, click Continue.
Under YES, select your primary login HTML form IdP adapter.
Under FAIL, select DONE.
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.
Under SUCCESS for the Twosense and manual MFA IdP adapters, select the appropriate policy contract.
Under FAIL, select the action you wish to occur when communication between PingFederate and Twosense fails.
Configure the Rules for the Twosense MFA Form adapter according to the table in the section below.
Click Done.
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:
Twosense Session Adapter Configuration
If your setup requires information about the authenticating user's current Twosense session, you can set up the Twosense Session Adapter to retrieve this information and use it in your policy.
Create Twosense Data Store
Navigate to SYSTEM and select Data Stores.
Click Add New Data Store.
In the Data Store Type tab, set the following:
Name: Twosense API
Type: REST API
Click Next.
In the Configure Data Store Instance tab, perform the following:
Add a new row to "Base URLs and Tags".
Base URL:
https://webapi.twosense.ai
Click Update.
Add the following rows to "Attributes".
startTime
->/startTime
userId
->/userId
device
->/device
ipAddress
->/ipAddress
Set Authentication Method to "OAuth 2.0 Bearer Token".
Set OAuth Token Endpoint to
https://webapi.twosense.ai/oauth/token
.Set Client ID and Client Secret to the values provided by Twosense.
Create Twosense Session Adapter
Navigate to AUTHENTICATION and select IdP Adapters.
Click Create New Instance.
In the Type tab, set the following:
Instance Name: Twosense Session Form
Instance ID: TwosenseSessionForm
Type: HTML Form IdP Adapter
Click Next.
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.session.embedded.html
Allow Username Edits During Chaining: true
Click Next.
In the Extended Contract tab, extend the contract with the following fields as needed per your requirements:
sessionStartTime
sessionUserId
sessionDevice
sessionIpAddress
Click Next.
In the Adapter Attributes tab, check the Pseudonym checkbox for the username attribute, and click Next.
In the Adapter Contract Mapping tab, click Configure Adapter Contract.
In the Attribute Sources & User Lookup tab, click Add Attribute Source.
In the Data Store tab, set the following:
ATTRIBUTE SOURCE ID: TwosenseAPI
ATTRIBUTE SOURCE DESCRIPTION: Twosense API
ACTIVE DATA STORE: Twosense API
Click Next.
In the Configure Data Source Filters tab, set the following:
RESOURCE PATH:
/sessions/${policy.action}
Click Next.
In the Adapter Contract Fulfillment tab, set the Source field to "Other (Twosense API)" for each of the extended contract attributes, then set the Value field to the corresponding attribute name.
In the Issuance Criteria tab, click Next.
In the Summary tab, click Done.
Click Next.
Review the Summary tab, and click Save.
Usage in Policies
You can use this adapter anywhere in your policy where you need to retrieve the current user's Twosense session information.
To use the adapter, add it to your policy and ensure the userSid
is being passed as the user ID in Options → Incoming User ID.
Create a rule on the adapter which checks that the session attribute of interest (e.g., sessionUserId
) is not empty (set "Value" to a single space, since Ping does not allow you to set it to an empty string), and make sure "Default to Success" is unchecked.
Using the example above, we end up with two branches from the adapter: "Fail" and "Session".
The "Fail" branch will be triggered if the user's computer does not have Twosense, or if there is no session for the authenticating user. The "Session" branch will be triggered if the session is found, and you will be able to use the session attributes further in your policy.
Last updated