@f8th/continuous-authentication v1.0.1

F8th MFA PHP 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, userId = null, metadata = null);. 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

You will need to include a JavaScript link in your HTML in order to use F8th. In order to do this, you will need to include a few values from the F8th object you created earlier. You can use a templating engine or any other method you prefer. You are looking for a script tag that looks like the following.

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

When the variables are set, the final script tag will look close to the following.

<script src="https://f8th-cdn.cluster-10.f8th.cloud/f8th.js?sid=ExampleSessionId&pk=ExamplePk"></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,
        'web_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};

Output:

• is_auth* (bool): Checks if the response is valid
• score (AuthCheckScore): Response Score
• request (GetAuthCheck): Request received by the server

Response Example:

object(stdClass) (3) {
    ["is_auth"] => int(1)
    ["score"] => object(stdClass) (5) {
        ["risk"] => int(12)
        ["authenticity"] => int(39)
        ["web_bot"] => int(14)
        ["insider_threat"] => int(36)
        ["blacklist"] => int(2)
    }
    ["request"] => object(stdClass) (3) {
        ["user_id"] => string(8) "jonathan"
        ["session_id"] => string(32) "1234567890abcdefghijklmnopz"
        ["policy"] => object(stdClass) (5) {
            ["risk"] => NULL
            ["authenticity"] => int(70)
            ["web_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

• risk (integer): Risk global based on every others scores
• authenticity (integer): Risk of account take over
• web_bot (integer): Risk of web 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