F8th MFA Node.JS SDK Documentation

How to Install?

1. Run npm install @f8th/continuous-authentication in your package.json directory
2. Include the F8th library const F8th = require('@f8th/continuous-authentication');
3. Start the F8th object using the following syntax let f8th = new F8th(isEnabled, apiKey, mfaClient, branchId, req);. Req should be the request object that contains the IP address, host, etc.
4. Initialize the F8th object by calling await f8th.init();
5. Include the F8th JavaScript library into your code including the session ID requested when the F8th object has been created. See How to Add the JavaScript Library for more details

Important:
Running the F8th SDK makes use of Express Sessions. Please make sure your express session has started before instantiating the F8th object.

How to Add the JavaScript Library

Add an HTML element script to your HTML element head including the f8th.cdnUrl() response in the src value, f8th.sessionId() response as value of the sid URL parameter, and f8th.privateKey() as value of the pk URL parameter such as below.

<script src="<?= f8th.cdnUrl() ?>f8th.js?sid=<?= f8th.sessionId() ?>&pk=<?= f8th.privateKey() ?>"></script>

A Word on the Data Collector

The data collector when running will track the mouse inputs and keyboard inputs of the user. However, we do not track what keys the user is pressing. In other words, passwords and other sensitive data will not be stored in our database. We keep track of the way the user uses their computer, but we make sure there's no way the data can be used to identify the data the user is actually inputting.

F8th MFA Methods

cdnUrl()

Return the Content Delivery Network URL.

Output: (string): Content Delivery Network URL

sessionId()

Return the Session ID requested when creating the F8th object.

Output: (string): Session ID requested

setUserId(userId = null)

Sets the userId in the object

Input:

• userId (string): Unique identification of the user

authCheck(policy, userId = null, metadata = null)

Detects multiple risks of fraud and account take over. A policy must be provided as a dictionary (see schema AuthCheckScore for the policy risk types options). The policy risk scores sent represent the maximum of acceptable risk. Which means, if the response's risk scores are equal of lower than all the policy risk scores provided, the value of is_auth of the response will be 1.

Metadata is an optional parameter that can be passed in to offer additional data to the backend service that you can reference later. It can take the form of a string or a dictionary.

Input:

• policy* (AuthCheckScore): Checks the authenticity of the user
• userId (string): Unique identification of the user
• metadata (string or dictionary): Optional data to be passed in to be referenced later

Usage Example:

let authCheck = await f8th.authCheck(
    {
        'risk': 50,
        'authenticity': 70,
        'bot': 90,
        'insider_threat': 95,
        'blacklist': 80
    },
    username
);

if(authCheck.is_auth) {
    // user is authenticated
} else {
    // user is did not pass the policy requirements
}

Important:
You can create your own policies similar to shown below.

    let policy = {"risk": 35};
    policy.Add("authenticity", "65");

Output:

• is_auth* (bool): Checks if the response is valid
• behavioral_data* (bool): Returns true if enough current data is gathered to make a prediction
• is_existing* (bool): Returns true if enough data existed previously to make a prediction
• score (AuthCheckScore): Response Score
• request (GetAuthCheck): Request received by the server

Response Example:

object(stdClass) (3) {
    ["is_auth"] => int(1)
    ["behavioral_data"] => int(1)
    ["is_existing"] => int(1)
    ["score"] => object(stdClass) (5) {
        ["authenticity"] => int(39)
        ["blacklist"] => int(2)
        ["bot"] => int(14)
        ["insider_threat"] => int(36)
        ["risk"] => int(12)
    }
    ["request"] => object(stdClass) (3) {
        ["user_id"] => string(8) "jonathan"
        ["session_id"] => string(32) "1234567890abcdefghijklmnopz"
        ["policy"] => object(stdClass) (5) {
            ["risk"] => NULL
            ["authenticity"] => int(70)
            ["bot"] => int(90)
            ["insider_threat"] => int(95)
            ["blacklist"] => int(80)
        }
    }
}

authConfirm(sessionId = null, userId = null, metadata = null)

Confirms the authentication of an user. If you initially created the F8th object without passing in a user ID, you can use this function to assign a user ID to the session ID after the fact.

Metadata is an optional parameter that can be passed in to offer additional data to the backend service that you can reference later. It can take the form of a string or a dictionary.

Input:

• sessionId (string): Session ID of the confirmation
• userId (string): Unique identification of the user
• metadata (string or Dictionary)

Usage Example:

await f8th.authConfirm();

Output:

• affected_rows* (int): The number of rows affected
• request (GetAuthCheck): Request received by the server

Response Example

object (2) {
    ["affected_rows"] => int(22)
    ["request"] => object (1) {
        "session_id": 294
        "user_id": "jonathan"
        "metadata": "metadata"
    }
}

authCancel(sessionId = null, userId = null, metadata = null)

Cancels the authentication of an user. This will remove the association of the user ID with the session ID.

Metadata is an optional parameter that can be passed in to offer additional data to the backend service that you can reference later. It can take the form of a string or a dictionary.

Input:

• sessionId (string): Session ID of the cancellation
• userId (string): Unique identification of the user
• metadata (string or Dictionary)

Usage Example:

await f8th.authCancel();

Output:

• affected_rows* (int): The number of row affected
• request (GetAuthCheck): Request received by the server

Response Example

object(stdClass) (2) {
    ["affected_rows"] => int(13)
    ["request"] => object(stdClass) (1) {
        "session_id": 27
        "user_id": "jonathan"
    }
}

authReset(userId = null, metadata = null)

Resets the behavioral biometric of the user.

Metadata is an optional parameter that can be passed in to offer additional data to the backend service that you can reference later. It can take the form of a string or a dictionary.

Input:

• userId (string): Unique identification of the user
• metadata (string or Dictionary)

Usage Example:

await f8th.authReset("Bob01");

Output:

• affected_rows* (int): The number of row affected
• request (GetAuthCheck): Request received by the server

Response Example

object(stdClass) (2) {
    ["affected_rows"] => int(356)
    ["request"] => object(stdClass) (1) {
        "user_id": "jonathan"
    }
}

Schema

AuthCheckScore

• authenticity (integer): Risk of account take over
• risk (integer): Risk global based on every others scores
• bot (integer): Risk of bot actor
• insider_threat (integer): Risk of an insider threat
• blacklist (integer): Risk of blacklisted profile

GetAuthCheck

• user_id (string): Unique identification of the user
• session_id (integer): Session ID requested
• policy (AuthCheckScore): Policy risk scores associative array

Effects of isEnabled Set to False

This property is often used when developers work in a development environment. When isEnabled is set to false the F8th MFA is disabled, and:

• the method sessionId return 0, which disable the JavaScript library
• the method setUserId is disabled
• the method authCheck return 1 as below

  object(stdClass) (1) {
    ["is_auth"] => int(1)
  }

• the method authReset return as below

  object(stdClass) (1) {
    ["affected_rows"] => int(0)
  }

To Keep in Mind

• You can send API requests only if your IP has been added to the list of allowed IPs to use this API key.
• If you run F8th MFA on your localhost, your IP seen by your local webserver will be different then the one seen by F8th's clouds, which means, the user won't be allowed to send behavioral data to the cloud, and will receive an HTTP error code 422 as response.

Implementing F8th MFA Without Using SDK

API Documentation:

• Docs: https://demo-api.cluster-01.f8th.cloud/docs
• Redoc: https://demo-api.cluster-01.f8th.cloud/redoc