Behavioral Biometrics Authentication API Guide

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.

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

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

Prerequisites

1. Complete the steps in the Authentication API guide.

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

Notice

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

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 thePOST 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 thePUT 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 Method	URI	Example
GET	`/api/v1/behavebio/js`	https://secureauth.company.com/secureauth2/api/v1/behavebio/js

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>

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 Method	URI	Example
POST	`/api/v1/behavebio`	https://secureauth.company.com/secureauth2/api/v1/behavebio

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

JSON Parameters	Success Response	Failure / 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 M100ethod	URI	Example
PUT	`/api/v1/behavebio`	https://secureauth.company.com/secureauth2/api/v1/behavebio

JSON Parameters	Success Response	Failure / 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." }

Behavioral Biometrics Authentication API Guide

Introduction

Profile Training

Accuracy Score and Confidence Score

Prerequisites

Notice

SecureAuth IdP Configuration Steps

Data

Warning

Endpoints

GET

/behavebio/js

POST

/behavebio

PUT

/behavebio

Search results