Implementing Device Fingerprints With Intelligent Authentication Trees in AM

[stephen.payne]

For more information, see this Knowledge Base article:
Authentication trees in AM

Overview

Device fingerprints are an out-of-the-box feature included with ForgeRock Access Management (AM) that work with authentication modules/chains and scripts. This article discusses how to implement the same device fingerprinting in intelligent authentication trees with AM 6.5. [For more information on the module/chain method, please refer to ForgeRock Access Management 6.5 > Authentication and Single Sign-On Guide and https://backstage.forgerock.com/docs/am/6.5/authentication-guide/#device-id-save-hints]. With this method, device fingerprints saved with the module/chain method can also be validated using the intelligent authentication tree method, allowing backward-compatibility with existing fingerprints.

How Does It Work?

Device fingerprinting uses a client-side script to identify many attributes of a user’s device. A representation of these attributes is stored for later use, to determine whether a user is using the same device. The device fingerprint can be used in intelligent authentication flows in many flexible ways. It essentially acts as a form of authentication without any user interaction. It is commonly used as a second factor for authentication when a device fingerprint matches, and it only prompts a user for a strong second factor authentication when the device fingerprint doesn’t match.

Many websites use cookies this way (ForgeRock Access Management 6.5 > Authentication and Single Sign-On Guide), but device fingerprints are saved as part of the user profile, instead of being stored as a cookie, so they continue to work even after a user clears all the cookies on their browser. A device fingerprint can also work in private/incognito windows.

In this article, we use the device fingerprint as the primary authentication factor, and only ask for a password in the event that the device fingerprint does not match. The intelligent authentication framework gives you the flexibility to use the fingerprint as your use case demands—for frictionless authentication to low risk sites, and later, step-up authentication, as the user accesses more secure sites.

The script used in this article uses the following factors:

• Installed/detected fonts
• Screen information:
  • Height
  • Width
  • Color depth
• Time zone information
• Browser plugins
• Geolocation information (user will be prompted to accept location information)

The AM intelligent authentication script uses a client-side script node to execute the script and collect the device information. It then puts the output into the authentication shared state using the devicePrint variable for use by other nodes and scripts in the authentication tree. For more information on shared state, see this article: ForgeRock Access Management 6.5 > Authentication Node Development Guide.

Set Up Device Fingerprinting

The high-level steps to setting up device fingerprinting are:

1. Prepare your schema attributes in DS and AM.
2. Add the required Marketplace nodes to your AM instance.
3. Create scripts and add them to AM.
4. Create authentication tree(s).

Prepare Your Directory

The device fingerprints are stored in a multivalued attribute in the user profile store. When using ForgeRock Directory Services (DS) as the profile store, and installing DS using the AM identity store installation profile (Directory Services 6.5 > Installation Guide), the devicePrintProfiles attribute is automatically added to the schema. If you are using a different directory (or if this attribute doesn’t exist in your DS installation), you will need to add an attribute to the schema. The following example shows the schema extension for DS:

60-identity-store-ds-deviceprint.ldif

#
# Copyright 2013-2020 ForgeRock AS. All Rights Reserved
#
# Use of this code requires a commercial software license with ForgeRock AS.
# or with one of its affiliates. All use shall be exclusively subject
# to such license between the licensee and ForgeRock AS.
#
dn: cn=schema
objectClass: top
objectClass: ldapSubentry
objectClass: subschema
attributeTypes: ( 1.3.6.1.4.1.36733.2.2.1.4
  NAME 'devicePrintProfiles'
  DESC 'Device print profiles information is stored in this attribute'
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  X-ORIGIN 'OpenAM' )
objectClasses: ( 1.3.6.1.4.1.36733.2.2.2.4
  NAME 'devicePrintProfilesContainer'
  DESC 'Class containing device print profiles'
  SUP top
  AUXILIARY
  MAY ( devicePrintProfiles )
  X-ORIGIN 'OpenAM' )

Add the attribute to AM

To enable the AM intelligent authentication nodes to read and update the device fingerprinting attribute in the user profile, you must add the attribute to the AM Identity store configuration. To do this:

1. Log in to AM as a realm administrator for the appropriate realm.
2. Select Identity Stores, and then select your identity store:

1. Select the User Configuration tab, then click the LDAP User Attributes tab.
2. Enter devicePrintProfiles (or your attribute name if you are using a custom name), then Enter. If the string disappears, it means that it was already entered:

3. Click Save Changes to save your work.

Add Custom Authentication Nodes

• Before setting up the authentication tree, you’ll need to add a few Marketplace nodes to your AM instance. Start by following the documentation for each of these nodes and adding them to AM. You’ll need to restart your AM instance after installing the lib files:

• Set Profile Property Authentication Node: (updated 4/08/2020 to support multi-valued attributes) ForgeRock Marketplace

  • This node takes variables from the sharedState, and writes them to the user profile (in our case, DS).

• Input Collector Authentication Node: (updated 4/1/19 to support AM 6.5)
  ForgeRock Marketplace

• This node lets us ask the user to input, takes that input, and stores it in the SharedState.

• Profile Attribute to State: (updated 3/24/2020 to support AM 6.5) ForgeRock Marketplace

  • This node reads a profile attribute and makes it available to the shared state.

• Client Script Auth Tree Node: (updated 3/30/2020 to support AM 6.5) : ForgeRock Marketplace

  • This node executes a client-side browser JavaScript, returning any configured results to a shared state object.

Add Scripts to AM

For the demo, we created three scripts: a client-side script, and two decision node scripts for authentication trees:

• CS-DeviceID Match-ClientSide: This client-side script is the JavaScript code that runs at the client to inspect the device, and saves the fingerprint into the shared state devicePrint variable.

• AT_Device Match: This decision node script for authentication trees script evaluates the device fingerprint. Does it already exist in the devicePrintProfiles? If so, update the lastUpdated date and userCount (number of times utilized). It also removes any expired profiles (based on configurable expiration time).

• AT_DeviceSave: This decision node script for authentication trees script creates a shared state deviceprintProfile variable that contains the new device fingerprint (which must be added to the user profile with a SetProfileProperty Node in the Authentication Tree):

CS-DeviceID Match-ClientSide

var fontDetector = (function () {
    /**
     * JavaScript code to detect available availability of a
     * particular font in a browser using JavaScript and CSS.
     *
     * Author : Lalit Patel
     * Website: http://www.lalit.org/lab/javascript-css-font-detect/
     * License: Apache Software License 2.0
     *          http://www.apache.org/licenses/LICENSE-2.0
     * Version: 0.15 (21 Sep 2009)
     *          Changed comparision font to default from sans-default-default,
     *          as in FF3.0 font of child element didn't fallback
     *          to parent element if the font is missing.
     * Version: 0.2 (04 Mar 2012)
     *          Comparing font against all the 3 generic font families ie,
     *          'monospace', 'sans-serif' and 'sans'. If it doesn't match all 3
     *          then that font is 100% not available in the system
     * Version: 0.3 (24 Mar 2012)
     *          Replaced sans with serif in the list of baseFonts
     */
    /*
     * Portions Copyrighted 2013 ForgeRock AS.
     */
    var detector = {}, baseFonts, testString, testSize, h, s, defaultWidth = {}, defaultHeight = {}, index;

    // a font will be compared against all the three default fonts.
    // and if it doesn't match all 3 then that font is not available.
    baseFonts = ['monospace', 'sans-serif', 'serif'];

    //we use m or w because these two characters take up the maximum width.
    // And we use a LLi so that the same matching fonts can get separated
    testString = "mmmmmmmmmmlli";

    //we test using 72px font size, we may use any size. I guess larger the better.
    testSize = '72px';

    h = document.getElementsByTagName("body")[0];

    // create a SPAN in the document to get the width of the text we use to test
    s = document.createElement("span");
    s.style.fontSize = testSize;
    s.innerHTML = testString;
    for (index in baseFonts) {
        //get the default width for the three base fonts
        s.style.fontFamily = baseFonts[index];
        h.appendChild(s);
        defaultWidth[baseFonts[index]] = s.offsetWidth; //width for the default font
        defaultHeight[baseFonts[index]] = s.offsetHeight; //height for the defualt font
        h.removeChild(s);
    }

    detector.detect = function(font) {
        var detected = false, index, matched;
        for (index in baseFonts) {
            s.style.fontFamily = font + ',' + baseFonts[index]; // name of the font along with the base font for fallback.
            h.appendChild(s);
            matched = (s.offsetWidth !== defaultWidth[baseFonts[index]] || s.offsetHeight !== defaultHeight[baseFonts[index]]);
            h.removeChild(s);
            detected = detected || matched;
        }
        return detected;
    };

    return detector;
}());
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2009 Sun Microsystems Inc. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at
 * https://opensso.dev.java.net/public/CDDLv1.0.html or
 * opensso/legal/CDDLv1.0.txt
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at opensso/legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 */
/*
 * Portions Copyrighted 2013 Syntegrity.
 * Portions Copyrighted 2013-2014 ForgeRock AS.
 */

var collectScreenInfo = function () {
        var screenInfo = {};
        if (screen) {
            if (screen.width) {
                screenInfo.screenWidth = screen.width;
            }

            if (screen.height) {
                screenInfo.screenHeight = screen.height;
            }

            if (screen.pixelDepth) {
                screenInfo.screenColourDepth = screen.pixelDepth;
            }
        } else {
            console.warn("Cannot collect screen information. screen is not defined.");
        }
        return screenInfo;
    },
    collectTimezoneInfo = function () {
        var timezoneInfo =  {}, offset = new Date().getTimezoneOffset();

        if (offset) {
            timezoneInfo.timezone = offset;
        } else {
            console.warn("Cannot collect timezone information. timezone is not defined.");
        }

        return timezoneInfo;
    },
    collectBrowserPluginsInfo = function () {

        if (navigator && navigator.plugins) {
            var pluginsInfo = {}, i, plugins = navigator.plugins;
            pluginsInfo.installedPlugins = "";

            for (i = 0; i < plugins.length; i++) {
                pluginsInfo.installedPlugins = pluginsInfo.installedPlugins + plugins[i].filename + ";";
            }

            return pluginsInfo;
        } else {
            console.warn("Cannot collect browser plugin information. navigator.plugins is not defined.");
            return {};
        }

    },
// Getting geolocation takes some time and is done asynchronously, hence need a callback which is called once geolocation is retrieved.
    collectGeolocationInfo = function (callback) {
        var geolocationInfo = {},
            successCallback = function(position) {
                geolocationInfo.longitude = position.coords.longitude;
                geolocationInfo.latitude = position.coords.latitude;
                callback(geolocationInfo);
            }, errorCallback = function(error) {
                console.warn("Cannot collect geolocation information. " + error.code + ": " + error.message);
                callback(geolocationInfo);
            };
        if (navigator && navigator.geolocation) {
            // NB: If user chooses 'Not now' on Firefox neither callback gets called
            //     https://bugzilla.mozilla.org/show_bug.cgi?id=675533
            navigator.geolocation.getCurrentPosition(successCallback, errorCallback);
        } else {
            console.warn("Cannot collect geolocation information. navigator.geolocation is not defined.");
            callback(geolocationInfo);
        }
    },
    collectBrowserFontsInfo = function () {
        var fontsInfo = {}, i, fontsList = ["cursive","monospace","serif","sans-serif","fantasy","default","Arial","Arial Black",
            "Arial Narrow","Arial Rounded MT Bold","Bookman Old Style","Bradley Hand ITC","Century","Century Gothic",
            "Comic Sans MS","Courier","Courier New","Georgia","Gentium","Impact","King","Lucida Console","Lalit",
            "Modena","Monotype Corsiva","Papyrus","Tahoma","TeX","Times","Times New Roman","Trebuchet MS","Verdana",
            "Verona"];
        fontsInfo.installedFonts = "";

        for (i = 0; i < fontsList.length; i++) {
            if (fontDetector.detect(fontsList[i])) {
                fontsInfo.installedFonts = fontsInfo.installedFonts + fontsList[i] + ";";
            }
        }
        return fontsInfo;
    },
    devicePrint = {};

devicePrint.screen = collectScreenInfo();
devicePrint.timezone = collectTimezoneInfo();
devicePrint.plugins = collectBrowserPluginsInfo();
devicePrint.fonts = collectBrowserFontsInfo();

if (navigator.userAgent) {
    devicePrint.userAgent = navigator.userAgent;
}
if (navigator.appName) {
    devicePrint.appName = navigator.appName;
}
if (navigator.appCodeName) {
    devicePrint.appCodeName = navigator.appCodeName;
}
if (navigator.appVersion) {
    devicePrint.appVersion = navigator.appVersion;
}
if (navigator.appMinorVersion) {
    devicePrint.appMinorVersion = navigator.appMinorVersion;
}
if (navigator.buildID) {
    devicePrint.buildID = navigator.buildID;
}
if (navigator.platform) {
    devicePrint.platform = navigator.platform;
}
if (navigator.cpuClass) {
    devicePrint.cpuClass = navigator.cpuClass;
}
if (navigator.oscpu) {
    devicePrint.oscpu = navigator.oscpu;
}
if (navigator.product) {
    devicePrint.product = navigator.product;
}
if (navigator.productSub) {
    devicePrint.productSub = navigator.productSub;
}
if (navigator.vendor) {
    devicePrint.vendor = navigator.vendor;
}
if (navigator.vendorSub) {
    devicePrint.vendorSub = navigator.vendorSub;
}
if (navigator.language) {
    devicePrint.language = navigator.language;
}
if (navigator.userLanguage) {
    devicePrint.userLanguage = navigator.userLanguage;
}
if (navigator.browserLanguage) {
    devicePrint.browserLanguage = navigator.browserLanguage;
}
if (navigator.systemLanguage) {
    devicePrint.systemLanguage = navigator.systemLanguage;
}

// Attempt to collect geo-location information and return this with the data collected so far.
// Otherwise, if geo-location fails or takes longer than 30 seconds, auto-submit the data collected so far.
document.getElementById('loginButton_0').style.display="none";
autoSubmitDelay = 30000;
output.value = JSON.stringify(devicePrint);
collectGeolocationInfo(function(geolocationInfo) {
    devicePrint.geolocation = geolocationInfo;
    output.value = JSON.stringify(devicePrint);
    submit();
});

AT_DeviceMatch

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2009 Sun Microsystems Inc. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at
 * https://opensso.dev.java.net/public/CDDLv1.0.html or
 * opensso/legal/CDDLv1.0.txt
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at opensso/legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 */
/*
 * Portions Copyrighted 2013 Syntegrity.
 * Portions Copyrighted 2013-2018 ForgeRock AS.
 */

var ScalarComparator = {}, ScreenComparator = {}, MultiValueComparator = {}, UserAgentComparator = {}, GeolocationComparator = {};

var config = {
    profileExpiration: 30,              //in days
    maxProfilesAllowed: 5,
    maxPenaltyPoints: 0,
    attributes: {
        screen: {
            required: true,
            comparator: ScreenComparator,
            args: {
                penaltyPoints: 50
            }
        },
        plugins: {
            installedPlugins: {
                required: false,
                comparator: MultiValueComparator,
                args: {
                    maxPercentageDifference: 10,
                    maxDifferences: 5,
                    penaltyPoints: 100
                }
            }
        },
        fonts: {
            installedFonts: {
                required: false,
                comparator: MultiValueComparator,
                args: {
                    maxPercentageDifference: 10,
                    maxDifferences: 5,
                    penaltyPoints: 100
                }
            }
        },
        timezone: {
            timezone: {
                required: false,
                comparator: ScalarComparator,
                args: {
                    penaltyPoints: 100
                }
            }
        },
        userAgent: {
            required: true,
            comparator: UserAgentComparator,
            args: {
                ignoreVersion: true,
                penaltyPoints: 100
            }
        },
        geolocation: {
            required: false,
            comparator: GeolocationComparator,
            args: {
                allowedRange: 100,      //in miles
                penaltyPoints: 100
            }
        }
    }
};

//---------------------------------------------------------------------------//
//                           Comparator functions                            //
//---------------------------------------------------------------------------//

var all, any, calculateDistance, calculateIntersection, calculatePercentage, nullOrUndefined, splitAndTrim,
    undefinedLocation;

// ComparisonResult

/**
 * Constructs an instance of a ComparisonResult with the given penalty points.
 *
 * @param penaltyPoints (Number) The penalty points for the comparison (defaults to 0).
 * @param additionalInfoInCurrentValue (boolean) Whether the current value contains more information
 *                                               than the stored value (defaults to false).
 */
function ComparisonResult() {

    var penaltyPoints = 0,
        additionalInfoInCurrentValue = false;

    if (arguments[0] !== undefined && arguments[1] !== undefined) {
        penaltyPoints = arguments[0];
        additionalInfoInCurrentValue = arguments[1];
    }

    if (arguments[0] !== undefined && arguments[1] === undefined) {
        if (typeof(arguments[0]) === "boolean") {
            additionalInfoInCurrentValue = arguments[0];
        } else {
            penaltyPoints = arguments[0];
        }
    }

    this.penaltyPoints = penaltyPoints;
    this.additionalInfoInCurrentValue = additionalInfoInCurrentValue;

}

ComparisonResult.ZERO_PENALTY_POINTS = new ComparisonResult(0);

/**
 * Static method for functional programming.
 *
 * @return boolean true if comparisonResult.isSuccessful().
 */
ComparisonResult.isSuccessful =  function(comparisonResult) {
    return comparisonResult.isSuccessful();
};


/**
 * Static method for functional programming.
 *
 * @return boolean true if comparisonResult.additionalInfoInCurrentValue.
 */
ComparisonResult.additionalInfoInCurrentValue =  function(comparisonResult) {
    return comparisonResult.additionalInfoInCurrentValue;
};

/**
 * Comparison function that can be provided as an argument to array.sort
 */
ComparisonResult.compare = function(first, second) {
    if (nullOrUndefined(first) && nullOrUndefined(second)) {
        return 0;
    } else if (nullOrUndefined(first)) {
        return -1;
    } else if (nullOrUndefined(second)) {
        return 1;
    } else {
        if (first.penaltyPoints !== second.penaltyPoints) {
            return first.penaltyPoints - second.penaltyPoints;
        } else {
            return (first.additionalInfoInCurrentValue ? 1 : 0) - (second.additionalInfoInCurrentValue ? 1 : 0);
        }
    }
};

/**
 * Amalgamates the given ComparisonResult into this ComparisonResult.
 *
 * @param comparisonResult The ComparisonResult to include.
 */
ComparisonResult.prototype.addComparisonResult = function(comparisonResult) {
    this.penaltyPoints += comparisonResult.penaltyPoints;
    if (comparisonResult.additionalInfoInCurrentValue) {
        this.additionalInfoInCurrentValue = comparisonResult.additionalInfoInCurrentValue;
    }
};

/**
 * Returns true if no penalty points have been assigned for the comparison.
 *
 * @return boolean true if the comparison was successful.
 */
ComparisonResult.prototype.isSuccessful = function() {
    return nullOrUndefined(this.penaltyPoints) || this.penaltyPoints === 0;
};

/**
 * Compares two simple objects (String|Number) and if they are equal then returns a ComparisonResult with zero
 * penalty points assigned, otherwise returns a ComparisonResult with the given number of penalty points assigned.
 *
 * @param currentValue (String|Number) The current value.
 * @param storedValue (String|Number) The stored value.
 * @param config: {
 *            "penaltyPoints": (Number) The number of penalty points.
 *        }
 * @return ComparisonResult.
 */
ScalarComparator.compare = function (currentValue, storedValue, config) {
    if (logger.messageEnabled()) {
        logger.message("StringComparator.compare:currentValue: " + JSON.stringify(currentValue));
        logger.message("StringComparator.compare:storedValue: " + JSON.stringify(storedValue));
        logger.message("StringComparator.compare:config: " + JSON.stringify(config));
    }
    if (config.penaltyPoints === 0) {
        return ComparisonResult.ZERO_PENALTY_POINTS;
    }

    if (!nullOrUndefined(storedValue)) {
        if (nullOrUndefined(currentValue) || currentValue !== storedValue) {
            return new ComparisonResult(config.penaltyPoints);
        }
    } else if (!nullOrUndefined(currentValue)) {
        return new ComparisonResult(true);
    }

    return ComparisonResult.ZERO_PENALTY_POINTS;
};

/**
 * Compares two screens and if they are equal then returns a ComparisonResult with zero penalty points assigned,
 * otherwise returns a ComparisonResult with the given number of penalty points assigned.
 *
 * @param currentValue: {
 *            "screenWidth": (Number) The current client screen width.
 *            "screenHeight": (Number) The current client screen height.
 *            "screenColourDepth": (Number) The current client screen colour depth.
 *        }
 * @param storedValue: {
 *            "screenWidth": (Number) The stored client screen width.
 *            "screenHeight": (Number) The stored client screen height.
 *            "screenColourDepth": (Number) The stored client screen colour depth.
 *        }
 * @param config: {
 *            "penaltyPoints": (Number) The number of penalty points.
 *        }
 * @return ComparisonResult
 */
ScreenComparator.compare = function (currentValue, storedValue, config) {
        logger.message("ScreenComparator.compare:currentValue: " + JSON.stringify(currentValue));
        logger.message("ScreenComparator.compare:storedValue: " + JSON.stringify(storedValue));
        logger.message("ScreenComparator.compare:config: " + JSON.stringify(config));

    if (nullOrUndefined(currentValue)) {
        currentValue = {screenWidth: null, screenHeight: null, screenColourDepth: null};
    }
    if (nullOrUndefined(storedValue)) {
        storedValue = {screenWidth: null, screenHeight: null, screenColourDepth: null};
    }

    var comparisonResults = [
        ScalarComparator.compare(currentValue.screenWidth, storedValue.screenWidth, config),
        ScalarComparator.compare(currentValue.screenHeight, storedValue.screenHeight, config),
        ScalarComparator.compare(currentValue.screenColourDepth, storedValue.screenColourDepth, config)];

    if (all(comparisonResults, ComparisonResult.isSuccessful)) {
        return new ComparisonResult(any(comparisonResults, ComparisonResult.additionalInfoInCurrentValue));
    } else {
        return new ComparisonResult(config.penaltyPoints);
    }
};

/**
 * Splits both values using delimiter, trims every value and compares collections of values.
 * Returns zero-result for same multi-value attributes.
 *
 * If collections are not same checks if number of differences is less or equal maxDifferences or
 * percentage of difference is less or equal maxPercentageDifference.
 *
 * If yes then returns zero-result with additional info, else returns penaltyPoints-result.
 *
 * @param currentValue: (String) The current value.
 * @param storedValue: (String) The stored value.
 * @param config: {
 *            "maxPercentageDifference": (Number) The max difference percentage in the values,
 *                                                before the penalty is assigned.
 *            "maxDifferences": (Number) The max number of differences in the values,
 *                                       before the penalty points are assigned.
 *            "penaltyPoints": (Number) The number of penalty points.
  *        }
 * @return ComparisonResult
 */
MultiValueComparator.compare = function (currentValue, storedValue, config) {
    if (logger.messageEnabled()) {
        logger.message("MultiValueComparator.compare:currentValue: " + JSON.stringify(currentValue));
        logger.message("MultiValueComparator.compare:storedValue: " + JSON.stringify(storedValue));
        logger.message("MultiValueComparator.compare:config: " + JSON.stringify(config));
    }

    var delimiter = ";",
        currentValues = splitAndTrim(currentValue, delimiter),
        storedValues = splitAndTrim(storedValue, delimiter),
        maxNumberOfElements = Math.max(currentValues.length, storedValues.length),
        numberOfTheSameElements = calculateIntersection(currentValues, storedValues).length,
        numberOfDifferences = maxNumberOfElements - numberOfTheSameElements,
        percentageOfDifferences = calculatePercentage(numberOfDifferences, maxNumberOfElements);

    if (nullOrUndefined(storedValue) && !nullOrUndefined(currentValue)) {
        return new ComparisonResult(true);
    }

    if (logger.messageEnabled()) {
        logger.message(numberOfTheSameElements + " of " + maxNumberOfElements + " are same");
    }

    if (maxNumberOfElements === 0) {
        logger.message("Ignored because no attributes found in both profiles");
        return ComparisonResult.ZERO_PENALTY_POINTS;
    }

    if (numberOfTheSameElements === maxNumberOfElements) {
        logger.message("Ignored because all attributes are same");
        return ComparisonResult.ZERO_PENALTY_POINTS;
    }

    if (numberOfDifferences > config.maxDifferences) {
        if (logger.messageEnabled()) {
            logger.message("Would be ignored if not more than " + config.maxDifferences + " differences");
        }
        return new ComparisonResult(config.penaltyPoints);
    }

    if (percentageOfDifferences > config.maxPercentageDifference) {
        if (logger.messageEnabled()) {
            logger.message(percentageOfDifferences + " percents are different");
            logger.message("Would be ignored if not more than " + config.maxPercentageDifference + " percent");
        }
        return new ComparisonResult(config.penaltyPoints);
    }

    if (logger.messageEnabled()) {
        logger.message("Ignored because number of differences(" + numberOfDifferences + ") not more than "
            + config.maxDifferences);
        logger.message(percentageOfDifferences + " percents are different");
        logger.message("Ignored because not more than " + config.maxPercentageDifference + " percent");
    }
    return new ComparisonResult(true);
};

/**
 * Compares two User Agent Strings and if they are equal then returns a ComparisonResult with zero penalty
 * points assigned, otherwise returns a ComparisonResult with the given number of penalty points assigned.
 *
 * @param currentValue (String) The current value.
 * @param storedValue (String) The stored value.
 * @param config: {
 *            "ignoreVersion": (boolean) If the version numbers in the User Agent Strings should be ignore
 *                                       in the comparison.
 *            "penaltyPoints": (Number) The number of penalty points.
 *        }
 * @return A ComparisonResult.
 */
UserAgentComparator.compare = function (currentValue, storedValue, config) {
    if (logger.messageEnabled()) {
        logger.message("UserAgentComparator.compare:currentValue: " + JSON.stringify(currentValue));
        logger.message("UserAgentComparator.compare:storedValue: " + JSON.stringify(storedValue));
        logger.message("UserAgentComparator.compare:config: " + JSON.stringify(config));
    }

    if (config.ignoreVersion) {
        // remove version number
        currentValue = nullOrUndefined(currentValue) ? null : currentValue.replace(/[\d\.]+/g, "").trim();
        storedValue = nullOrUndefined(storedValue) ? null : storedValue.replace(/[\d\.]+/g, "").trim();
    }

    return ScalarComparator.compare(currentValue, storedValue, config);
};

/**
 * Compares two locations, taking into account a degree of difference.
 *
 * @param currentValue: {
 *            "latitude": (Number) The current latitude.
 *            "longitude": (Number) The current longitude.
 *        }
 * @param storedValue: {
 *            "latitude": (Number) The stored latitude.
 *            "longitude": (Number) The stored longitude.
 *        }
 * @param config: {
 *            "allowedRange": (Number) The max difference allowed in the two locations, before the penalty is assigned.
 *            "penaltyPoints": (Number) The number of penalty points.
*         }
 * @return ComparisonResult
 */
GeolocationComparator.compare = function (currentValue, storedValue, config) {
    if (logger.messageEnabled()) {
        logger.message("GeolocationComparator.compare:currentValue: " + JSON.stringify(currentValue));
        logger.message("GeolocationComparator.compare:storedValue: " + JSON.stringify(storedValue));
        logger.message("GeolocationComparator.compare:config: " + JSON.stringify(config));
    }

    // Check for undefined stored or current locations

    if (undefinedLocation(currentValue) && undefinedLocation(storedValue)) {
        return ComparisonResult.ZERO_PENALTY_POINTS;
    }
    if (undefinedLocation(currentValue) && !undefinedLocation(storedValue)) {
        return new ComparisonResult(config.penaltyPoints);
    }
    if (!undefinedLocation(currentValue) && undefinedLocation(storedValue)) {
        return new ComparisonResult(true);
    }

    // Both locations defined, therefore perform comparison

    var distance = calculateDistance(currentValue, storedValue);

    if (logger.messageEnabled()) {
        logger.message("Distance between (" + currentValue.latitude + "," + currentValue.longitude + ") and (" +
            storedValue.latitude + "," + storedValue.longitude + ") is " + distance + " miles");
    }

    if (parseFloat(distance.toPrecision(5)) === 0) {
        logger.message("Location is the same");
        return ComparisonResult.ZERO_PENALTY_POINTS;
    }

    if (distance <= config.allowedRange) {
        if (logger.messageEnabled()) {
            logger.message("Tolerated because distance not more then " + config.allowedRange);
        }
        return new ComparisonResult(true);
    } else {
        if (logger.messageEnabled()) {
            logger.message("Would be ignored if distance not more then " + config.allowedRange);
        }
        return new ComparisonResult(config.penaltyPoints);
    }
};


//---------------------------------------------------------------------------//
//                    Device Print Logic - DO NOT MODIFY                     //
//---------------------------------------------------------------------------//

// Utility functions

/**
 * Returns true if evaluating function f on each element of the Array a returns true.
 *
 * @param a: (Array) The array of elements to evaluate
 * @param f: (Function) A single argument function for mapping elements of the array to boolean.
 * @return boolean.
 */
all = function(a, f) {
    var i;
    for (i = 0; i < a.length; i++) {
        if (f(a[i]) === false) {
            return false;
        }
    }
    return true;
};

/**
 * Returns true if evaluating function f on any element of the Array a returns true.
 *
 * @param a: (Array) The array of elements to evaluate
 * @param f: (Function) A single argument function for mapping elements of the array to boolean.
 * @return boolean.
 */
any = function(a, f) {
    var i;
    for (i = 0; i < a.length; i++) {
        if (f(a[i]) === true) {
            return true;
        }
    }
    return false;
};

/**
 * Returns true if the provided location is null or has undefined longitude or latitude values.
 *
 * @param location: {
 *            "latitude": (Number) The latitude.
 *            "longitude": (Number) The longitude.
 *        }
 * @return boolean
 */
undefinedLocation = function(location) {
    return nullOrUndefined(location) || nullOrUndefined(location.latitude) || nullOrUndefined(location.longitude);
};

/**
 * Returns true if the provided value is null or undefined.
 *
 * @param value: a value of any type
 * @return boolean
 */
nullOrUndefined = function(value) {
    return value === null || value === undefined;
};

/**
 * Calculates the distances between the two locations.
 *
 * @param first: {
 *            "latitude": (Number) The first latitude.
 *            "longitude": (Number) The first longitude.
 *        }
 * @param second: {
 *            "latitude": (Number) The second latitude.
 *            "longitude": (Number) The second longitude.
 *        }
 * @return Number The distance between the two locations.
 */
calculateDistance = function(first, second) {
    var factor = (Math.PI / 180),
        theta,
        dist;
    function degreesToRadians(degrees) {
        return degrees * factor;
    }
    function radiansToDegrees(radians) {
        return radians / factor;
    }
    theta = first.longitude - second.longitude;
    dist = Math.sin(degreesToRadians(first.latitude)) * Math.sin(degreesToRadians(second.latitude))
        + Math.cos(degreesToRadians(first.latitude)) * Math.cos(degreesToRadians(second.latitude))
        * Math.cos(degreesToRadians(theta));
    dist = Math.acos(dist);
    dist = radiansToDegrees(dist);
    dist = dist * 60 * 1.1515;
    return dist;
};

/**
 * Converts a String holding a delimited sequence of values into an array.
 *
 * @param text (String) The String representation of a delimited sequence of values.
 * @param delimiter (String) The character delimiting values within the text String.
 * @return (Array) The comma separated values.
 */
splitAndTrim = function(text, delimiter) {

    var results = [],
        i,
        values,
        value;
    if (text === null) {
        return results;
    }

    values = text.split(delimiter);
    for (i = 0; i < values.length; i++) {
        value = values[i].trim();
        if (value !== "") {
            results.push(value);
        }
    }

    return results;
};

/**
 * Converts value to a percentage of range.
 *
 * @param value (Number) The actual number to be converted to a percentage.
 * @param range (Number) The total number of values (i.e. represents 100%).
 * @return (Number) The percentage.
 */
calculatePercentage = function(value, range) {
    if (range === 0) {
        return 0;
    }
    return parseFloat((value / range).toPrecision(2)) * 100;
};

/**
 * Creates a new array containing only those elements found in both arrays received as arguments.
 *
 * @param first (Array) The first array.
 * @param second (Array) The second array.
 * @return (Array) The elements that found in first and second.
 */
calculateIntersection = function(first, second) {
    return first.filter(function(element) {
        return second.indexOf(element) !== -1;
    });
};

function getValue(obj, attributePath) {
    var value = obj,
        i;
    for (i = 0; i < attributePath.length; i++) {
        if (value === undefined) {
            return null;
        }
        value = value[attributePath[i]];
    }
    return value;
}


function isLeafNode(attributeConfig) {
    return attributeConfig.comparator !== undefined;
}

function getAttributePaths(attributeConfig, attributePath) {

    var attributePaths = [],
        attributeName,
        attrPaths,
        attrPath,
        i;

    for (attributeName in attributeConfig) {
        if (attributeConfig.hasOwnProperty(attributeName)) {

            if (isLeafNode(attributeConfig[attributeName])) {
                attrPath = attributePath.slice();
                attrPath.push(attributeName);
                attributePaths.push(attrPath);
            } else {
                attrPath = attributePath.slice();
                attrPath.push(attributeName);
                attrPaths = getAttributePaths(attributeConfig[attributeName], attrPath);
                for (i = 0; i < attrPaths.length; i++) {
                    attributePaths.push(attrPaths[i]);
                }
            }
        }
    }

    return attributePaths;
}

function getDevicePrintAttributePaths(attributeConfig) {
    return getAttributePaths(attributeConfig, []);
}

function hasRequiredAttributes(devicePrint, attributeConfig) {

    var attributePaths = getDevicePrintAttributePaths(attributeConfig),
        i,
        attrValue,
        attrConfig;

    for (i = 0; i < attributePaths.length; i++) {

        attrValue = getValue(devicePrint, attributePaths[i]);
        attrConfig = getValue(attributeConfig, attributePaths[i]);

        if (attrConfig.required && attrValue === undefined) {
            logger.warning("Device Print profile missing required attribute, " + attributePaths[i]);
            return false;
        }
    }

    logger.message("device print has required attributes");
    return true;
}

function compareDevicePrintProfiles(attributeConfig, devicePrint, devicePrintProfiles, maxPenaltyPoints) {

    var attributePaths = getDevicePrintAttributePaths(attributeConfig),
        dao = sharedState.get('_DeviceIdDao'),
        results,
        j,
        aggregatedComparisonResult,
        i,
        currentValue,
        storedValue,
        attrConfig,
        comparisonResult,
        selectedComparisonResult,
        selectedProfile,
        curDevicePrintProfile,
        vals;

    results = [];
    for (j = 0; j < devicePrintProfiles.length; j++) {
        curDevicePrintProfile = devicePrintProfiles[j];
        aggregatedComparisonResult = new ComparisonResult();
        for (i = 0; i < attributePaths.length; i++) {

            currentValue = getValue(devicePrint, attributePaths[i]);
            storedValue = getValue(curDevicePrintProfile.devicePrint, attributePaths[i]);
            attrConfig = getValue(attributeConfig, attributePaths[i]);

            if (storedValue === null) {
                comparisonResult = new ComparisonResult(attrConfig.penaltyPoints);
            } else {
                comparisonResult = attrConfig.comparator.compare(currentValue, storedValue, attrConfig.args);
            }

            logger.message("Comparing attribute path: " + attributePaths[i]
                    + ", Comparison result: successful=" + comparisonResult.isSuccessful() + ", penaltyPoints="
                    + comparisonResult.penaltyPoints + ", additionalInfoInCurrentValue="
                    + comparisonResult.additionalInfoInCurrentValue);

            aggregatedComparisonResult.addComparisonResult(comparisonResult);
        }
        if (logger.messageEnabled()) {
            logger.message("Aggregated comparison result: successful="
                + aggregatedComparisonResult.isSuccessful() + ", penaltyPoints="
                + aggregatedComparisonResult.penaltyPoints + ", additionalInfoInCurrentValue="
                + aggregatedComparisonResult.additionalInfoInCurrentValue);
        }

        results.push({
            key: aggregatedComparisonResult,
            value: devicePrintProfiles[j]
        });
    }

  	//logger.message("RESULTS " + results);
    if (results.length === 0) {
        return null;
    }

    results.sort(function(a, b) {
        return ComparisonResult.compare(a.key, b.key);
    });
    selectedComparisonResult = results[0].key;
    if (logger.messageEnabled()) {
        logger.message("Selected comparison result: successful=" + selectedComparisonResult.isSuccessful()
            + ", penaltyPoints=" + selectedComparisonResult.penaltyPoints + ", additionalInfoInCurrentValue="
            + selectedComparisonResult.additionalInfoInCurrentValue);
    }

    selectedProfile = null;
    if (selectedComparisonResult.penaltyPoints <= maxPenaltyPoints) {
        selectedProfile = results[0].value;
            logger.message("Selected profile: " + JSON.stringify(selectedProfile) +
                " with " + selectedComparisonResult.penaltyPoints + " penalty points");
    }

    if (selectedProfile === null) {
        return false;
    }

    /* update profile */
    selectedProfile.selectionCounter =
        java.lang.Integer.valueOf(parseInt(selectedProfile.selectionCounter, 10) + 1);
    selectedProfile.lastSelectedDate = new Date().getTime();
    selectedProfile.devicePrint = devicePrint;

    vals = [];
    for (i = 0; i < devicePrintProfiles.length; i++) {
        vals.push(JSON.stringify(JSON.parse(org.forgerock.json.JsonValue.json(devicePrintProfiles[i]))));
    }

    //putting an array of devicePrintProfile strings in sharedState
  	sharedState.put("devicePrintProfiles", vals);
    return true;
}

function matchDevicePrint() {

    if (!username) {
        logger.error("Username not set. Cannot compare user's device print profiles.");
        outcome = "error";
    } else {

        if (logger.messageEnabled()) {
            logger.message("client devicePrint: " + clientScriptOutputData);
        }

        var getProfiles = function () {

                function isExpiredProfile(devicePrintProfile) {
                    var expirationDate = new Date(),
                        lastSelectedDate;
                    expirationDate.setDate(expirationDate.getDate() - config.profileExpiration);

                    lastSelectedDate = new Date(devicePrintProfile.lastSelectedDate);

                    return lastSelectedDate < expirationDate;
                }

                function getNotExpiredProfiles() {
                    var profile,
                        dao = sharedState.get('_DeviceIdDao'),
                        results = [],
                        profiles,
                        iter;


                    profiles = JSON.parse(sharedState.get("devicePrintProfiles"));
                    logger.message("devicePrintProfiles: " + JSON.stringify(profiles));


                  	if (profiles) {
                      for (var i=0; i< profiles.length; i++) {
                        	if (!isExpiredProfile(profiles[i])) {
                            	results.push(profiles[i]);
	                        }
	                    }
                    }

                    if (logger.messageEnabled()) {
                        logger.message("stored non-expired profiles: " + results);
                    }
                    return results;
                }

                return getNotExpiredProfiles();
            },
            devicePrint = JSON.parse(clientScriptOutputData),
            devicePrintProfiles = getProfiles();

        if (!hasRequiredAttributes(devicePrint, config.attributes)) {
            logger.message("devicePrint.hasRequiredAttributes: false");
            // Will fail this module but fall-through to next module. Which should be OTP.
            outcome = "error";
        } else if (compareDevicePrintProfiles(config.attributes, devicePrint, devicePrintProfiles, config.maxPenaltyPoints)) {
            logger.message("devicePrint.hasValidProfile: true");
            outcome = "matched";
        } else {
            logger.message("devicePrint.hasValidProfile: false");
            // Will fail this module but fall-through to next module. Which should be OTP.
            outcome = "not matched";
        }
    }
}

username = sharedState.get("username");
realm = sharedState.get("realm");
clientScriptOutputData = sharedState.get("devicePrint");
matchDevicePrint();

AT_DeviceSave

function uuidv4() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}


var device = {
	"lastSelectedDate": new Date().getTime(),
	"devicePrint": JSON.parse(String(sharedState.get("devicePrint"))),
	"name": String(sharedState.get("deviceName")),
	"selectionCounter": 1,
	"uuid": uuidv4()
}

logger.message("New device: " + JSON.stringify(device));

sharedState.put("devicePrintProfile", JSON.stringify(device));

outcome = "true";

Create Authentication Trees

In this example, we create two authentication trees. The “outer” tree is the authentication tree, where we ask the user for a username, and then validate the device fingerprint. If the device fingerprint does not match a previously saved fingerprint, we call the “inner” tree to collect and verify the user’s password. This is a very simple example; you can start with it to verify that your device fingerprint works as expected, and then later, add any additional authentication tree logic as required.

Start by creating the inner tree to validate the password, assuming the device fingerprint did not match. You will collect the username in the outer tree:

Node Details: [The numbers refer to the node numbers in the above diagram]

1. Start [Next node = Password Collector]
2. Password Collector [Next node =Data Store Decision]
3. Data Store Decision:

• True [Next node = Success]
• False [Next node =Retry Limit Decision]

4. Retry Limit decision:

• Retry [Next node = Password Collector]
• Reject [Next node = Failure]

5. Success
6. Failure

Here is our outer tree with the device fingerprinting scripts:

Node Details: [The numbers refer to the node numbers in the above diagram]

1. Start [Next node = 2-Username Collector]
2. Username Collector [Next node = 3-Inspect Client Device]
3. Client Script:

• Node Name: Inspect Client Device
• Script: CS-DeviceID Match-ClientSide
• Script Result Object: devicePrint [Next node = 4-Get stored Fingerprints from shared state]

4. Profile Attribute To State:

• Node Name: Get stored fingerprints to Shared State
• Attribute name to state:
  • devicePrintProfiles = devicePrintProfiles
• Selection Type: SelectExact [Next node = 5-Save new fingerprint]

5. Scripted Decision Node:

• Node Name: Find Match?
• Script: AT_DeviceMatch
• Outcomes:
  • matched [Next node 11-Update Device Fingerprints]
  • not matched [Next node = 6- Password Inner Tree]
  • error [Next node = 12-failure]

6. Inner Tree Evaluator:

• Node Name: Password Inner Tree
• Tree Name: IT_Password
• True [Next node = 7-Save new fingerprint]
• False [Next node = 12- Failure]

7. Choice Collector:

• Node Name: Save new fingerprint?
• Choices:
  • Save [Next node = 8-Prompt Device Name]
  • Skip [Next node = 11-Success]
• Default Choice: Skip
• Prompt: Save device as trusted?

8. Input Collector Node:

• Node Name: Prompt Device Name
• Variable name: deviceName
• Prompt: Enter name for device
• Password Input: [Not selected]
• Use Transient State: [Not selected] [Next node = 9-Add Trusted Device]

9. Scripted Decision:

• Node Name: Add Trusted Device
• Script: AT_DeviceSave
• Outcomes:
  • true [Next node = 10-Add Device Fingerprint]

10. Set Profile Property {Key, Value}:

• Node Name: Add Device Fingerprint
• devicePrintProfiles, devicePrintProfile [Pay special attention to the spelling difference]
• Transient Properties: None {Note: If this option is missing, you have an older version of the Set Profile Property node, and you need to upgrade it for this use case.}: Leave this setting blank.
• Add Attributes: True {Note: If this option is missing, you have an older version of the Set Profile Property node, and you need to upgrade it for this use case.}.
• [Next node = 12-Success]

11. Set Profile Property {Key, Value}:

• Node Name: Update Device Fingerprints
• devicePrintProfiles, devicePrintProfiles [Note this is different than #10]
• Transient Properties: None {Note: If this option is missing, you have an older version of the Set Profile Property node, and you need to upgrade it for this use case.}: Leave this setting blank.
• Add Attributes: False {Note: If this option is missing, you have an older version of the Set Profile Property node, and you need to upgrade it for this use case.}
• [Next node = 12-Success]

12. Success
13. Failure

Testing the Authentication Trees

Use your browser to login to the outer tree. For example: https://testing.frdpcloud.com/openam/XUI/?service=DevicePrint.

Enter your username:

Click Allow to allow access to location information:

Note: If you do not wish to utilize location access, modify the CS-DeviceID Match-ClientSide script, and remove or comment out the call to collectGeolocationInfo on lines 144–162.

Enter your password:

If you don’t have a valid and matched fingerprint, your are prompted to save your device or skip the step:

Give your device a name:

After login is complete, view your device in the AM self-service dashboard (for example, https://testing.frdpcloud.com/openam/openam/XUI/#dashboard/):

Log out, and then log in again with your same authentication tree. This time, you should only be prompted with your username, as the device fingerprint should match.

Conclusion

Congratulations on successfully configuring device fingerprints using ForgeRock intelligent authentication trees!

Helpful Links

ForgeRock AM 7 > Authentication Node Development Guide > The Action...

ForgeRock AM 7 > Authentication and Single Sign-On Guide >...