Login

Overview

Trustfull Login is an advanced authentication API designed to secure user access while maintaining a seamless experience. It integrates behavioral biometrics, device fingerprinting, and connection analysis to protect against account takeovers, phishing, and unauthorized logins. This lightweight and frictionless solution operates silently in the background, ensuring enhanced security without impacting user interactions.

Key Features

• Behavioral Analysis: Monitors typing patterns, mouse activity, and other in-browser behaviors to detect anomalies.
• Device & IP Intelligence: Identifies returning users with device fingerprints and flags risky sessions based on IP, VPN, or proxy usage.
• Centralized Dashboard: Tracks login activities, provides analytics, and generates detailed reports for auditing and monitoring.

Applications

Trustfull Login is ideal for any platform requiring robust authentication, including fintech, e-commerce, and online services. It strengthens defenses against account takeover attempts, streamlines onboarding processes, and ensures secure access for users globally.

Technical Implementation

Installing the JavaScript

To begin using Trustfull Login, install the provided JavaScript script on your login page. This script collects activity-related data during login attempts and securely associates it with a unique session ID.

Key Points:

• The JavaScript snippet will capture behavioral and device data in real-time.
• No passwords or sensitive user information are tracked or authenticated.
• Each login attempt must generate a unique session ID, which should be securely stored for subsequent API calls.
• Username field must be marked by data-tf="username"attribute tag.

Example of Including the JavaScript Script:

<script>
    (function (f, i, d, o, c, od, e) {
        f['FidoObject'] = c;
        f[c] = f[c] || function () {
            (f[c].q = f[c].q || []).push(arguments);
        }, f[c].l = 1 * new Date();
        od = i.createElement(d),
            e = i.getElementsByTagName(d)[0];
        od.async = 1;
        od.src = o;
        e.parentNode.insertBefore(od, e);
    })(window, document, 'script', 'https://login.trustfull.com/login.js', 'tf');

    tf('create', 'your-js-key');
</script>

⚠️

Replace 'your-js-key' with the JS key provided to you. Ensure the script is placed on the login page where user interactions will be monitored.

API Workflow: Enrollment and Login Event Scoring

The Trustfull Login API supports two primary actions:

1. Registering an Enrollment
   • An enrollment represents a reference point for scoring login events.
   • You can store up to 20 enrollments per user, providing flexibility for evolving user behavior.
2. Scoring a Login Event
   • Login events can only be scored if a related enrollment exists for the user, so an enrollment must be created before scoring a login event.
   • The session ID is required to calculate an authentication score.

Easy Implementation Strategy Example

Step 1: Include the Trustfull JavaScript Script

Ensure that the Trustfull JavaScript script is included on your login page. This script collects user behavior and device data during login attempts.

For installation details, refer to the example in the Installing the JavaScript Script section.

Step 2: Capture Login Events and Send Data

Use the following JavaScript code to capture login events and send the required data to Trustfull:

const form = document.getElementById("login-form");
form.addEventListener("submit", (ev) => {
    const username = document.querySelector('input[data-tf="username"]').value;
    if (!username) {
        // Cannot send login event without a username
        return;
    }

    const sessionId = getSessionId(); // Ensure session ID is generated and shared with the backend
    tf.sendRecord(sessionId, username);
});

Notes:

• Form ID: This example assumes your login form has the ID login-form. Ensure the form in your application uses this ID or update the code to match your form's ID.
• Username Field: The username input field must include the data-tf="username" attribute as per Trustfull's requirements.
• Session ID: The getSessionId() function is a placeholder for retrieving a unique session ID. This ID must also be shared with your backend for the subsequent API call.

Step 3: try to get the Login score

Once the session data is collected, your backend must call the Trustfull API to retrieve the login score:

POST http://api.fido.id/1.0/track/results?session_id=<session-id>
x-api-key: <your-api-key>

Replace <session-id> and <your-api-key> with the actual sessionId and API key provided to you. Note that the API key is not the same as the JS key and must never be exposed in the frontend. It is a shared secret between your backend and Trustfull for authentication. For further details about this API call, refer to the API Documentation.

If the API returns a 400 Error indicating that no enrollment exists for the user, proceed to Step 4.

Step 4: Create an Enrollment

If no enrollment exists for the user, your backend must call the Trustfull API to create an enrollment:

POST http://api.fido.id/1.0/track/enrollments?session_id=<session-id>
x-api-key: <your-api-key>

Replace <session-id> and <your-api-key> with the actual sessionId and API key. For further details about this API call, refer to the API Documentation.

After successfully creating the enrollment, you can either score the previous login event or score any subsequent login events associated with the same username.

Recommended Implementation Strategy

To maximize the potential of Trustfull Login, we suggest an advanced implementation strategy that balances security with user convenience. This approach leverage on behavioral analysis and risk-based decisions to streamline authentication processes while maintaining robust account protection.

Register the first enrollment

Register the first successful login of a user as an enrollment to establish a baseline of trusted behavior. We suggest using Multi-Factor Authentication (MFA) during the first login attempt if an enrollment does not exist to verify the user’s identity before creating the enrollment.

Dynamic Scoring for Subsequent Logins

Use the score and score cluster provided in the API response to determine how to handle login attempts:

• High/Good: Grant access, as these scores indicate trusted behavior.
• Moderate: Prompt the user with an MFA challenge. After successful completion, register the login event as a new enrollment to account for behavioral changes over time.
• Bad/Poor: Deny access to protect against potential credential compromise or malicious activity.

This strategy strengthens authentication workflows while adapting to evolving user behavior and ensuring security remains unobtrusive for trusted users.