Documentation

Introduction

Use this guide to configure the SecureAuth Authentication API to use Behavioral Biometrics which analyzes an end-user's keystroke and mouse movement behavior during login / page interaction to create a profile that is then compared to subsequent login attempts using the configured authentication workflow.

Once a profile is trained, the end-user enters the required information into the fields, and SecureAuth IdP can determine whether this behavior is consistent with that of the mature profile.
 

Authentication API Behavioral Biometrics Workflow

The Authentication API uses two (2) endpoints and three (3) requests for Behavioral Biometrics

1. The first endpoint is a simple GET request to acquire the JavaScript source file required to create the behavior profile

Once the JavaScript source file is obtained, it must be added to the webpage(s) in order to collect the relevant data

As the end-user interfaces with the page(s) and form(s), SecureAuth IdP generates a profile containing particular keystroke and mouse movement behavior, actual values, and other components

2. The second endpoint can be called either via

  • a POST request to post the end-user's behavior profile to enable the comparison

The profile created by the JavaScript is then posted to the second endpoint for either training or authentication purposes

- or -

  • a PUT request to reset the end-user's behavior profile or a field in the profile to retrain keystrokes and mouse movements

If the profile is still being trained, then the data is used solely to mature the profile, rather than to validate the end-user's identity

Using the PUT endpoint, the end-user can reset the entire, trained profile, or specific fields in the trained profile

When a profile is trained, that behavior is expected by SecureAuth IdP; so if a field value changes (such as password, address, phone number, etc.), then resetting the profile is necessary to ensure the assessment of correct values

Once a profile is reset, then the end-user undergoes the same prior training procedure until the new values are matured and the profile can once more be used in authentication

Profile Training and Score Definitions / Descriptions

Profile Training

Profile training takes ten (10) sessions, which can be completed in days, weeks, or months, depending on the frequency of user access to the form

Once a profile has matured, it is ready for comparison to securely authenticate the user

After the profile is posted to the API endpoint, SecureAuth IdP responds with an Accuracy Score and a Confidence Score

Accuracy Score and Confidence Score

The Accuracy Score reveals how closely the current behavior resembles that of the trained profile, and the Confidence Score reveals the confidence of SecureAuth IdP in the provided score

To increase accuracy and confidence, it is recommended to utilize numerous, static fields with six (6) or more characters per field

Having a profile that is rich in behavior produces the best results and raises the confidence level of the identity verification

Behavioral Biometrics Best Practices

To achieve the best Behavioral Biometrics results, SecureAuth recommends the following:

  • Use at least six (6) characters for text fields
  • After resetting a password, the profile (or profile field) should be reset to ensure accurate data collection
  • The more data that is captured in the application result in more accuracy and confidence in the scores
  • Since profile training takes ten (10) sessions, applications that are accessed more frequently yield faster training
Prerequisites

1. Complete the steps in the Authentication API Guide

2. Complete the Behavioral Biometrics configuration steps in the SecureAuth IdP Web Admin

LDAP directory integration is the only supported data store for the Behavioral Biometrics API

Refer to Behavioral Biometrics Guide for additional information

SecureAuth IdP Configuration Steps
Behavioral Biometrics Configuration Steps
Data

 

1. In the Profile Fields section, map the Behavior Biometrics Profile Property to a directory attribute field, e.g. comment

2. Check Writable

Click Save once the configurations have been completed and before leaving the Data page to avoid losing changes

Endpoints

Endpoints for /behavebio enable the use of SecureAuth IdP's behavioral biometrics which trains the end-user profile for authentication by the sole individual based on unique keystrokes and mouse movements

The /behavebio/js endpoint uses the GET method to retrieve the JavaScript reference that is required to gather and analyze an end-user's behavioral biometric profile

Using the JavaScript reference, most of the data required for the POST and PUT endpoints are provided, but the remaining information (user ID, host address, and user agent) must be supplied by the application

The /behavebio endpoint uses the POST method to collect and create the end-user's behavioral biometric profile which is then analyzed against subsequent profile information posted to the endpoint

The API gathers the end-user keystroke, text input, and other factors while the application's provided fields are filled out (e.g. username, password, home address, phone number, etc.)

After these fields are filled out ten (10) times, the profile is considered to have been trained, and the API can then return a score based on the comparison of the "normal" behavior and the current behavior

The /behavebio endpoint uses the PUT method to reset the end-user's profile to enable retraining – this is especially useful after the end-user changes a password

Resetting a profile can involve completely resetting the profile, or resetting specific fields from which behavior profile information is collected

GET
/behavebio/js
HTTP MethodURIExample
GET/api/v1/behavebio/js
https://secureauth.company.com/secureauth2/api/v1/behavebio/js
Response to Request Example
{
  "src": "https://SecureAuthIdPFQDN/SecureAuthIdPRealm/assets/scripts/api/behaveBio.obf.js?ver=9.0.0.22"
}
JavaScript Initialization Example
Code Example
<form>
...
	<input id="password" class="form-control" type="password" name="loginForm:Password" autocomplete="off" value="" placeholder="Password">
	<input type="hidden" name="behavio_hidden" id="behavio_hidden">
	<input id="textbox" class="form-control" type="text" name="loginForm:NotMonitored" autocomplete="off" value="" placeholder="Ignored">
...
</form>
 
<script>
	$(document).ready(function() {
		secureAuth.api.behaveBio({
			anonymousByName: [],
    		anonymousById: [],
			anonymousByType: ['password'],
			behavioHiddenId: ['behavio_hidden'],
			ignoreFields: ['loginForm:NotMonitored'],
			haveMouse: false
		});
	});
</script>
Code Explanation

Form

  • <input type="hidden" name="behavio_hidden" id="behavio_hidden"> – Required anywhere in the <form> to create the behaviorProfile, with any preferred name and id values
  • <input id="password" class="form-control" type="password" name="loginForm:Password" autocomplete="off" value="" placeholder="Password"> – Example of input field with necessary components id, type, and name to identify anonymoustext fields

  • <input id="textbox" class="form-control" type="text" name="loginForm:NotMonitored" autocomplete="off" value="" placeholder="Not for Profile"> – Example of input field with necessary components id, type, and name to identify ignored fields

Script

  • Full script required in app code
  • anonymousByName – Identifies anonymoustext fields by name (in <input>)
  • anonymousById – Identifies anonymoustext fields by id (in <input>)
  • anonymousByType – Identifies anonymoustext fields by type (in <input>, as shown in code example)
  • behavioHiddenId – Calls to <input type="hidden" ...> line (required in <form>) with the same id value
  • ignoreFields – Identifies fields to not include in the behaviorProfile by name (in <input>, as shown in code example)
  • haveMouse – Monitors mouse movements as well as keystroke behavior (true or false)
POST
/behavebio
HTTP MethodURIExample
POST/api/v1/behavebio
https://secureauth.company.com/secureauth2/api/v1/behavebio
Definitions
  • userID: End-user's username
  • behaviorProfile: End-user's behavioral biometric profile, generated by the JavaScript reference acquired in the /behavebio/js endpoint
  • hostAddress: End-user's IP address
  • userAgent: End-user's user agent (computer / browser information)
  • TotalScore: Similarities between the presented behavior and the stored profile
  • TotalConfidence: Level of assurance by the API that the score is accurate
  • Device: Type of device the end-user employs
  • Results: Breakdown of specific field scores
POST Endpoint JSON Parameters and Response Examples
JSON ParametersSuccess ResponseFailure / Error Response
{
    "userId":"<USERNAME>",
    "behaviorProfile":'<BEHAVIORAL BIOMETRIC PROFILE>',
    "hostAddress":"<IP ADDRESS>",
    "userAgent":"<USER AGENT>"
}

Example:

{
"userId":"jsmith",
"behaviorProfile":'[["m","n",{"mozPay":null,"mozContacts":{},"mozApps":{},"doNotTrack":
"unspecified","battery":{},"oscpu":"Intel+Mac+OS+X+10.10","vendor":"","vendorSub":"",
"productSub":"20100101","cookieEnabled":true,"buildID":"20160210153822","mediaDevices"
:{},"serviceWorker":{"controller":null},"geolocation":{},"appCodeName":
"Mozilla","appName":"Netscape","appVersion":"5.0+(Macintosh)","platform":"MacIntel"
,"userAgent":"Mozilla/5.0+(Macintosh;+Intel+Mac+OS+X+10.10;+rv:44.0)+
Gecko/20100101+Firefox/44.0","product":"Gecko","language":"en-US","languages"
:["en-US","en"],"onLine":true}],["m","s",{"availWidth":1440,"availHeight":823,"width"
:1440,"height":900,"colorDepth":24,"pixelDepth":24,"top":0,"left":0,"availTop":23,
"availLeft":0,"mozOrientation":"landscape-primary","onmozorientationchange":null,"orientation":
{}}],["m","v",250],["w",[{"text#UserID":7},{"password#Password":12},{"submit#Submitclick":7}
]],["f","text#UserID",[[0,65,14285],[0,68,14362],[1,65,14459],[0,77,14466],
[1,68,14562],[1,77,14643],[0,73,14682],[0,78,14818],[1,73,14882],[1,78,14946],
[0,49,15018],[1,49,15194],[0,48,15202],[1,48,15282],[0,9,15410]]],["fa","password#Password",
[[0,0,15804],[0,1,15850],[0,2,15915],[1,0,15955],[0,3,15970],[1,1,16010],[1,2,16066],[1,3,16106],
[0,4,16282][0,4,16411],[0,5,16459],[0,6,16530],[0,7,16586],[1,4,16634],
[1,5,16674],[1,4,16714],[1,6,16730],[1,7,16770],[0,8,17219],[0,9,17283],[0,10,17339],
[0,11,17395],[1,8,17426],[1,9,17434],[1,10,17466],[1,11,17498]]]]',
"hostAddress":"111.222.33.44",
"userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:44.0) Gecko/20100101 Firefox/44.0"
}

Untrained Profile:

{
 "BehaviorBioResults": {
   "TotalScore": 0.5,
   "TotalConfidence": 0,
   "Device": "DESKTOP",
   "Results": []
 },
 "status": "valid",
 "message": ""
}
{
 "status": "invalid",
 "message": "Request validation failed with: userId was not present."
}

Trained Profile:

{
 "BehaviorBioResults": {
   "TotalScore": 0.999999780,
   "TotalConfidence": 0.999780,
   "Device": "DESKTOP",
   "Results": [
     {
       "ControlID": "text#UserID",
       "Score": 0.99997949,
       "Confidence": 0.9997949,
       "Count": 10
     },
     {
       "ControlID": "password#Password",
       "Score": 0.99997807,
       "Confidence": 0.9997807,
       "Count": 10
     }
   ]
 },
 "status": "valid",
 "message": ""
}
{
 "status": "invalid",
 "message": "Request validation failed with: behaviorProfile was not present."
}
{
 "status": "invalid",
 "message": "Request validation failed with: hostAddress was not present."
}
{
 "status": "invalid",
 "message": "Request validation failed with: userAgent was not present."
}
PUT
/behavebio
HTTP MethodURIExample
PUT/api/v1/behavebio
https://secureauth.company.com/secureauth2/api/v1/behavebio
Definitions
  • fieldName: Name of field to reset (unique to application); or set to ALL for global reset
  • fieldType: Type of field, either regulartext (actual values stored in profile) or anonymoustext (no actual values stored in profile, e.g. password entries); or set to ALL for global reset
  • deviceType: Type of device used by user (Desktop or Mobile); or set to ALL for global reset
PUT Endpoint JSON Parameters and Response Examples
JSON ParametersSuccess ResponseFailure / Error Response
{
   "userId":"<USERNAME>",
   "fieldName":"<FIELD TO RESET>",
   "fieldType":"<TYPE OF FIELD>",
   "deviceType":"<TYPE OF DEVICE>"
}

Specific Field Reset Example:

{
   userId:"jsmith",
   fieldName:"UserID",
   fieldType:"regulartext",
   deviceType:"DESKTOP"
}

Global Reset Example:

{
   userId:"jsmith",
   fieldName:"ALL",
   fieldType:"ALL",
   deviceType:"ALL"
}
{
 "status": "valid",
 "message": "Reset sent to data store"
}
{
 "status": "invalid",
 "message": "Request validation failed with: userId was not present."
}
{
 "status": "invalid",
 "message": "Request validation failed with: fieldName was not present."
}
{
 "status": "invalid",
 "message": "Request validation failed with: fieldType was not present."
}
{
 "status": "invalid",
 "message": "Request validation failed with: deviceType was not present."
}