Java SDK for user monitoring


Sqreen protects your application users against major threats, such as account takeover, password bruteforce, suspicious activities coming from TOR or an unusual VPN.

Integrating the Sqreen Advanced User Context SDK into your application allows you to set up user monitoring with flexibility and powerful extra features.

Syntax upgrade with version 0.1 and 0.2

We improved the SDK API in version 0.3 to provide a more compact and fluent style. Existing code relying on previous API is still supported but won't receive any further updates, and we encourage you to update to the latest version.

User monitoring SDK

Sqreen provides the Sqreen agent SDK as a library that you add to your application dependencies. Read the Sqreen SDK dependency section below to add it to your project.

The Sqreen SDK integration relies on three methods: trackLogin, trackSignup and identify.

Here's a full implementation example:

// in the signup method, when the user account is created for the first time:
User user = signup(email, password);

Sqreen.user()
    .authKey("email", email)
    .trackSignup();

// ...

// in the signin method, when a user creates a new session:
User user = login(email, password);

Sqreen.user()
    .authKey("email", email)
    .trackLogin(user != null);

// ...

// On every request to map the authenticated user to the request
User user = login(email, password);

Sqreen.user()
    .authKey("email", email)
    .identify();

Login tracking

trackLogin() is the SDK method to call on user login activity.

import io.sqreen.agent.sdk.Sqreen;

public class LoginController {
    // .. other parts of the class ommited for clarity

    private User doLogin(String login, String password) {
        // this is where you check login/password credentials
        // this function returns null in case of login failure
        User user = checkLogin(login, password);

        // track user authentication success|error events
        Sqreen.user()
            .authKey("login", login)
            .authKey("email", user != null ? user.getEmail() : null)
            .trackLogin(user != null);

        return user;
    }

}

The trackLogin function accepts a single boolean argument for login success/error.

The agent creates a user identity using chained authKey builder method calls.

Sqreen.user()
    // using 'login' and 'email' as user identification keys
    .authKey("login", login)
    .authKey("email", email)
    // track authentication success/error
    .trackLogin(boolean success)

Sqreen integration at signup and login

You should not call trackLogin each time you check a user session in your application.

Signup tracking

trackSignup() is the SDK method to call when creating a new user account at signup.

import io.sqreen.agent.sdk.Sqreen;

public class SignupController {
    // .. other parts of the class ommited for clarity

    private User doSignup(String login, String email) {
        // this is where you create your user account
        User user = createUser(login, email);

        Sqreen.user()
            // using 'login' and 'email' as user identification keys
            .authKey("login", user.getLogin())
            .authKey("email", user.getEmail())
            // you can also use your own properties in key
            .authKey("id", user.getId())
            // track signup
            .trackSignup()

        return user;
    }
}

The trackSignup function has no argument.

The agent creates a user identity using chained authKey builder method calls.

Sqreen.user()
    // using 'login' and 'email' as user identification keys
    .authKey("login", login)
    .authKey("email", email)
    // track user signup
    .trackSignup()

Session tracking

identify is the SDK method to map a user to the current HTTP request.

When the request does not use this method for identification, Sqreen falls back to login tracking information to map a user. It's a best effort approach based on the recent activity of users on the requests IPs.

import io.sqreen.agent.sdk.Sqreen;

public class MainController {
    // .. other parts of the class ommited for clarity

    private void executeRequest(HttpServletRequest request, HttpServletResponse response) {
        // this is where you retrieve your current authenticated user,
        // probably from session or request headers
        User user = getCurrentUser(request);

        if( user == null ) {
            // user not authenticated
            response.setStatus(401);
            return;
        }

        Sqreen.user()
            .authKey("login", user.getLogin())
            .authKey("email", user.getEmail())
            // user traits can be used to provide extra properties outside of user identificaition
            .trait("mood", user.getMood())
            // associate current request with user
            .identify();

        // we're done, now we are ready to do meaningful work...
    }
}

The identify method has no argument:

The agent creates a user identity using chained authKey builder method calls. It gets user traits using chained trait(String trait, String value) builder method calls.

Sqreen.user()
    .authKey("login", user.getLogin())
    .authKey("email", user.getEmail())
    // user traits can be used to provide extra properties outside of user identificaition
    .trait("mood", user.getMood())
    // associate current request with user
    .identify();

The Sqreen's user interface uses the authKey arguments to help you identify which users are attacking your application.

The trait arguments provile optional traits for the user.

User traits

Sqreen does not display nor process the traits. In a future release, we'll display them to faciliate attack investigation and allow you to build custom workflows. Interested in this feature? Contact us.

Block users (security automation)

Security Automation isn't yet available for Java.

User identification

For users with a single identification value, such as an email address or nickname:

Sqreen.user()
    .authKey("email", user.getEmail())
    .identify()

User monitoring and PII

If you're concerned about sending sensitive data to Sqreen and not leaking any Personally Identifying Information (PII), visit this blogpost to learn best practices around user tracking (covers Ruby but easy to translate in Java).

For users with a composite primary key (more than one value), send all the values to identify them accurately on Sqreen's user interface.

For example, if you are are operating a whitelabel platform and it identifies your users by their email and the shop ID, you can send these identifiers like below:

Sqreen.user()
    .authKey("email", user.getEmail())
    .authKey("platform_id", user.getPlatformId())
    .identify()

This also applies to trackSignup and identify methods.

Please note that the three calls rely on the same identity format for Sqreen to map the activities to a single user.

The Sqreen SDK only accepts user identifiers

Don't send any other information (like the auth failure reason). Sqreen considers them as part of the user identifier, and is not able to merge successful and failed authentications.

Primary key

Sqreen tries to determine a primary key amongst the keys you provided. Sqreen uses the following keywords to determine the primary identification key: email, mail, e-mail, username, login.

If Sqreen cannot find any of those keys, it uses the first key in alphabetic order.

If Sqreen finds more than one key, it uses the first in the sequence mentioned above.

Sqreen SDK dependency

Since the Sqreen SDK is a separate library you should add it to your application's dependencies.

The SDK requires the Sqreen agent to be installed and running in the application. See the Install Java Agent section to get the installation instructions. When the agent isn't installed, the calls to SDK methods are ignored.

Maven

Update your pom.xml with:

<repositories>
    <repository>
        <id>sqreen-sqreen</id>
        <url>https://packagecloud.io/sqreen/sqreen-public/maven2</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.sqreen</groupId>
        <artifactId>sqreen-sdk</artifactId>
        {VERSION}0.3</version>
    </dependency>
</dependencies>

Gradle

Update your build.gradle with :

repositories {
    maven {
        url "https://packagecloud.io/sqreen/sqreen-public/maven2"
    }
}

dependencies {
    compile group: 'io.sqreen', name: 'sqreen-sdk', version: '0.3'
}