HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference

Enabling Behavioral Biometrics

Suggest Edits

Introduction

Adaptive Access Web Behavioral Biometrics is a Trusteer® technology for detecting behavioral typing anomalies during traditional username and password authentication. Behavioral Biometrics can reduce user friction during primary authentication (where user input is required), by comparing the current login actions against previously seen actions in the account to identify anomalies. The assessment analyzes the user's interactions with the system in the login phase.

Web Behavioral Biometrics does not collect or send individual keystroke data, rather the advanced algorithms model and correlate several characteristics during keyboard interaction. The use of Web Behavioral Biometrics during authentication is an inherent multi-authentication factor of "something you are".

In a typical scenario with a valid user completing authentication, the Web Behavioral Biometric assessment of the user session is either successful, or the result can be indeterminate due to insufficient sample data. If the Behavioral Biometrics analysis returns a high confidence of fraud, the system does not block the request as a fraudulent session, but rather triggers a High or Very High result in the Adaptive Access policy.

Additionally, an indicator user_behavioral_score is available for use in Access policy rules to augment the context available for the final Access policy decision.

You can use Web Behavioral Biometrics in an IBM® Security Verify tenant provided the following conditions are met:

Checking your Adaptive Access subscription

You can use the following online documentation to confirm that Adaptive Access is activated:
https://www.ibm.com/docs/en/security-verify?topic=administration-confirming-subscription-activation-deactivation

The activation or deactivation of the IBM Security Verify Adaptive Access subscription in your tenant requires that you reach out to your account planner. The Verify operations team will take the appropriate action for you.

You can also work with your account planner to ask the Verify operations team to enable the Web Behavioral Biometrics feature.

Adding snippets to your Login page

The Web Behavioral Biometric technology must be enabled on the login form of your site to analyze the user's interaction with the keyboard and form elements. Once enabled, a new session can be compared with the previously trained sessions for that user to determine a probability based on the behavioral biometric.

In addition to loading the Adaptive Access JavaScript on the login page, additional callbacks are also required:

  • Session Id callback for correlation between the client-side analysis and the server-side evaluation and prediction
  • Monitoring callback for confirmation of client-side analysis completion prior to initiating the server-side evaluation

IBM Security Verify User Home Page

You can use Themes or Templates to add the required JavaScript snippets to each Identity source template that requires username and password.

Use the following online documentation to assist with this task: https://www.ibm.com/docs/en/security-verify?topic=experience-managing-branding.

As a best practice, consider using themes for this configuration. However, you can also use templates. Please review the guidance on best practices here: https://www.ibm.com/docs/en/security-verify?topic=branding-management-best-practices

  • Add the JavaScript snippets to each Identity source template used in the tenant that requires username and password template entry
    • Cloud Directory
    • Agent Bridge
  • JavaScript snippets
    • See examples here
    • Snippet loader either direct or XHR to compute endpoint
    • Session ID callback
    • Collection completion callback
    • UI Controls (enable/disable buttons or Please Wait... message on form submission)

Once the JavaScript snippets have been added, a note will appear on the login form to indicate that 'Enter key submission is disabled'. The user must click the Sign In button.

1680

Login page snippet loaded

Adaptive Native Login Page

For Adaptive Native Web applications, the form name and fields must match those of the IBM Security Verify forms.
The standard form names & field names are listed below:

  • Main login selection page 

      cloud-directory-form   
  user-name-input  
  password-input

  • Cloud Directory + Pass through LDAP and password retry 

      login-main-form  
  user-name-input  
  password-input

Enabling Adaptive Access in Access policy

Overview

To use Web Behavioral Biometrics, Adaptive Access must be enabled in the Access policy.

For more information about creating an Adaptive Access Policy & associating a policy with an application, see the following topics in the online documentation:

The user_behavioral_score indicator can then be added to a Policy Rule, enabling the policy author to tailor the user experience.

For example, where an Access policy's Default rule required an MFA Per Session action, a new higher order rule can be added to return an Allow decision when matched if the user_behavioral_score is in the the high confidence range, defined in Web Behavioral Biometrics events and reports.

❗️

Addition of the user_behavioral_score indicator to Access policies is currently only available using the Access Policy Vault APIs.

You can can create or update Access policies to add Policy rules which use the adaptiveAttributes condition to resolve the user_behavioral_score.

Using Web Behavioral Biometrics to bypass an MFA per session action

The successful completion of a username and password authentication passing a Web Behavioral Biometrics predication should only be used to satisfy an MFA per session action.
Users cannot be ‘challenged’ with Web Behavioral Biometrics when the decision is MFA always and as such a successful completion of Web Behavioral Biometrics should not be considered as having satisfied a multi-factor authentication requirement.
Rather, a positive prediction using Web Behavioral Biometrics could be used to reduce user friction, where without any additional context, all users are normally required to complete an MFA in the session.

For example, where an Access policy with Adaptive Access enabled contains a Default rule requiring MFA per session, even when the Adaptive Risk Level is Low and the default configuration would Allow, the combining of the Allow from Adaptive and the MFA per session from the Default rule would result in an MFA per session.

Adding a new adaptiveAttributes rule above the Default rule which returns the Allow action when the user_behavioral_score falls within the high confidence range would be matched first and combined with the Allow from the Adaptive Risk Level resulting in a final Allow decision.

2606

See examples here of Access policy Rules that can be added to your policies to tailor the user experience based on the user_behavioral_score.

Behavioral Biometrics Training and Best Practices

Overview

Web Behavioral Biometrics analyses the keyboard interactions during authentication to detect typing anomalies that could indicate a fraudulent login attempt. To accurately assess the login behaviors of a given user, the system must first have sufficient sample data for the given user on a particular device. The system gathers data from the initial sessions to create a baseline for each user on each device.

Training data

The first 8-10 sessions per user on each device are used to gather sample data for the Web Behavioral Biometrics. During the training phase, the system works on the premise that the data collected are legitimate authentications and that the collected baseline samples are valid. The baseline samples are then used for the subsequent analysis.

It is possible to gather the training samples in a short period of time, but it may take longer for some users. The rate at which the data becomes available for each user will differ depending on the session frequency of each user. To give sufficient time for your user base to record sessions, leave the Web Behavioral Biometrics Factor disabled for a period while samples are being gathered.

The system detects password change events, which will trigger a new training period for the affected user on each associated device. The subsequent sessions are used to gather sample data to re-train the system on the standard user behavior during authentication with the new password.

Behavioral Biometrics evaluations

When the Web Behavioral Biometrics Factor is enabled, if there is insufficient sample data for a particular user, the result of the evaluation may be indeterminate. If a prediction is unavailable or the analysis cannot be completed, the Verifying page may be displayed.

1680

Verifying page during evaluation

After training is complete and the Web Behavioral Biometrics Factor is in use, the model will continue to learn. However, if the system detects a ‘fraudulent’ session, the session receives a high behavioral_score and is excluded from the training data so that potentially invalid sessions do not influence subsequent evaluations.

Password Best Practices

A long and versatile password will yield better results. Consider setting a password policy to ensure users meet some minimum length and complexity requirements.

You can review details about how to configure password requirements here: https://www.ibm.com/docs/en/security-verify?topic=security-managing-password-policies.

Suggested password minimum requirements include:

  • should consist of 10 or more characters
  • should include both numbers and letters
  • should be known and comfortable for you to type
  • should not be use commonly used passwords such as 1234567890, the word "password" or consecutive keys in row

Adaptive Access policies in conjunction with Web Behavioral Biometrics

The Web Behavioral Biometrics Factor aims to provide an additional layer of protection by analyzing the keystroke patterns for a given user on a given device. However, even if the username and password are compromised and a fraudster is successful in impersonating a legitimate user, the Adaptive Access policy risk indicators also continue to apply. A policy risk indicator can still detect anomalies and trigger the associated policy rule.

Web Behavioral Biometrics events and reports

You can use reports to check the successful completion of Web Behavioral Biometrics, provided that the required JavaScript snippets have been added to the login page. The reporting features is available regardless of whether Behavioral biometrics is included in an Access policy.

You can refer to the online documentation for details on accessing audited events and generating reports here

  • The event attribute behavioral_score indicates the prediction of Web Behavioral Biometrics. This attribute is assigned a value from 0-1000 for a completed prediction, or -1 when a prediction is not available, as detailed below:
    • -1 represents no predication was available, normally due to autocomplete, copy/paste or password managers
    • 0 - 699 represents High Confidence
    • 700 - 999 represents positive prediction
    • 1000 represents either indeterminate or known fraud
  • The report element Behavioral score under Adaptive details shows the prediction from 0 - 1000 or a - for no result.
  • The expected return values are -1 / 0 / 700 / 1000 with the ranges allowing for additional fine grained support as password, collection and usage patterns evolve.

Report Examples:

1680

Adaptive Report with no prediction

1680

Adaptive Report with Block action due to high fraud prediction

1680

Adaptive Report with Allow action due to low risk

Web Behavioral Biometrics prediction and collection errors

A successful Web Behavioral Biometrics prediction requires session correlation between the user's browser and the Adaptive Access policy evaluation. Review the items in this section if users are consistently have no predication available.

No predication available

  • The JavaScript snippets must be included in the login form with the correct form and element names.
    Refer to IBM Security Verify User Home Page.
  • Before loading the loging page use the Developer Tools Console Log to view the JavaScript trace.
    The entry getFlow() called: 1 indicates the snippet loading is complete and collection can occur. If the user enters data in the form fields prior to this entry appearing the analysis may not complete in time.
    Consider replacing the dynamic inclusion of the JavaScript elements obtained from /risk/v3.0/authz/api/compute in to the login page directly.

Obtaining support

  • The Session ID and Correlation ID from an event in the Adaptive Access report assist in identifying causes of errors.
    When requesting support, provide both of these values which are displayed when clicking Show session data in the Adaptive access event.
    Refer to Web Behavioral Biometrics events and reports.

Script snippets for inclusion on login pages

Script to disable enter button 
<script type="text/javascript">
  window.addEventListener('keydown', function (e) {
    if (e.keyIdentifier == 'U+000A' || e.keyIdentifier == 'Enter' || e.keyCode == 13) {
      if ((e.target.nodeName == 'INPUT' && (e.target.type == 'text' || e.target.type == 'password')) ||
            (e.target.nodeName == 'BUTTON' && e.target.type == 'submit')) {
        e.preventDefault();
        console.log("Behavioural Biometrics Model testing. Enter key disabled")
        return false;
      }
    }
  }, true);
</script>
Script for biometrics capture and transmission 
<script type="text/javascript">
			let data = localStorage.getItem('getFormatCalled');

			var start = loadSnippets();
			var insertedSnippets = false;
			var collectionWaits = 0;
			var COLLECTION_MONITOR_TIMEOUT = 500;
			var COLLECTION_MONITOR_COUNTER = 20;
			var PAGE_COLLECTION_TIMEOUT = 1000;
		
			function collectionMonitor() {
				if  (getFlowCalled < 1 && collectionWaits < COLLECTION_MONITOR_COUNTER) {
					console.log("Behavioural Biometrics Model testing. Collection monitor sleeper");
					collectionWaits++;
					setTimeout(collectionMonitor, COLLECTION_MONITOR_TIMEOUT);
				}
				else {
					doSubmitActions();
					//Assume only a single form
					document.forms[0].submit();
				}
			}

			function collectAllKeyStrokes() {			
				if (insertedSnippets && getFlowCalled < 1) {
					console.log("Behavioural Biometrics Model testing. Collection monitor not called");
					setTimeout(collectionMonitor, COLLECTION_MONITOR_TIMEOUT);
					return false;
				}
				else {
					doSubmitActions();
					return true;
				}
			}

			function doSubmitActions() {
				if (insertedSnippets) {
					console.log("Behavioural Biometrics Model testing. Calling main account tag on submit");
					window['tcfn']('main_account');
					var date = new Date();
					var curDate = null;
					console.log("Behavioural Biometrics Model testing. Looping to collect last keystrokes");
					do { curDate = new Date(); }
					while (curDate - date < PAGE_COLLECTION_TIMEOUT);
					console.log("Behavioural Biometrics Model testing. main account and sleep complete. Submitting");
				}
				else {
					console.log("Behavioural Biometrics Model testing. No inserted loader snippet");
				}
			}
		
			function loadSnippets() {
				var xhttp = new XMLHttpRequest();
				xhttp.onreadystatechange = function () {
					if (this.readyState == 4 && this.status == 200) {
					jsToInsert = JSON.parse(this.responseText);
					//We know the compute API has the snippets before the callbacks.  Iterate backwards so we don't miss the session id callback
					for (var i = jsToInsert.snippets.length - 1; i >= 0; i--) {	  

						if (jsToInsert.snippets[i].includes('aloads.js')) {
							console.log("Behavioural Biometrics Model testing. Inserting loader snippet");
							if (data == getFormat().c) {
								console.log("Behavioural Biometrics Model testing. Page reload detected.  Replacing with dt=verify");
								jsToInsert.snippets[i] = jsToInsert.snippets[i].replace("dt=login", "dt=verify");
							}
							else {
								console.log("Behavioural Biometrics Model testing. New page load detected.  Using dt=login");
							}					
						}
										
						let frag = document.createRange().createContextualFragment(jsToInsert.snippets[i]);
						document.getElementsByTagName('head')[0].appendChild(frag);

						if (jsToInsert.snippets[i].includes('getFormat')) {
							console.log("Behavioural Biometrics Model testing. Overriding CSID callback to set local storage");
							getFormat = (function () {
							var cached_function = getFormat;
							return function () {							
								var result = cached_function.apply(this, arguments); // use .apply() to call it
								localStorage.setItem('getFormatCalled', result.c);
								return result;
							};
							})();
						}
					}
					insertedSnippets = true;
					}
					else if (this.readyState == 4 && this.status != 200) {
						console.error("Behavioural Biometrics Model testing. Unable to insert loader snippet");
					}
				};
				console.log("Behavioural Biometrics Model testing. Calling compute API to insert snippets in template page");
				xhttp.open("GET", this.location.protocol + "//" + this.location.hostname + "/risk/v3.0/authz/api/compute", true);
				xhttp.send();
			};
		</script>
Login form action modified to collect remaining keystrokes 
<!-- form id="cloud-directory-form" method="post" -->
<form id="cloud-directory-form" method="post" onsubmit="return collectAllKeyStrokes()">

Access Policy Rule samples

Allow high confidence 
        {
            "id": "2",
            "name": "Adaptive WBB high confidence Allow",
            "description": "Allow the user when the WBB predication satisfies the high confidence range of 0 to 699.",
            "conditions": [
                {
                    "attributes": [
                        {
                            "name": "$.[1].message.behavioral_insights.user_behavioral_score",
                            "opCode": "<",
                            "values": [
                                "701"
                            ]
                        },
                        {
                            "name": "$.[1].message.behavioral_insights.user_behavioral_score",
                            "opCode": ">",
                            "values": [
                                "-1"
                            ]
                        }
                    ],
                    "type": "adaptiveAttributes"
                }
            ],
            "result": {
                "action": "ACTION_ALLOW",
                "serverSideActions": []
            }
        }
Block known fraud and send notification e-mail

The Block and Redirect action may also be used.

        {
            "id": "1",
            "name": "Adaptive WBB known fraud Block",
            "description": "Block the user when the WBB predication indicates known fraud of 1000.",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [
                {
                    "attributes": [
                        {
                            "name": "$.[1].message.behavioral_insights.user_behavioral_score",
                            "opCode": "=",
                            "values": [
                                "1000"
                            ]
                        }
                    ],
                    "type": "adaptiveAttributes"
                }
            ],
            "result": {
                "action": "ACTION_DENY",
                "serverSideActions": [
                    {
                        "actionId": "N100",
                        "version": "0"
                    }
                ]
            }
        }

Updated 3 months ago