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 unusual VPN.

Advanced User Context allows you to set up user monitoring in your application with flexibility and powerful additional features. You will need to integrate Sqreen SDK in your application (< 10 minutes).

User monitoring SDK

The Sqreen agent SDK is provided as a library and should be added to your application dependencies. See the Sqreen SDK dependency section below to add it to your project.

The Sqreen SDK integration is very simple. It relies on 3 methods: authTrack, signupTrack 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);
Map<String,String> userIdentifiers = new HashMap<>();
userIdentifiers.put("email", email);
Sqreen.signupTrack(userIdentifiers);

// ...

// in the signin method, when a user creates a new session:
User user = login(email, password);
Map<String,String> userIdentifiers = new HashMap<>();
userIdentifiers.put("email", email);
Sqreen.authTrack(user != null, userIdentifiers);

// ...

// On every request to map the authenticated user to the request
User user = login(email, password);
Map<String,String> userIdentifiers = new HashMap<>();
userIdentifiers.put("email", email);
Sqreen.identify(userIdentifiers);

Login tracking

Sqreen.authTrack 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);

        // prepare user properties for event, any map implementation can be used
        Map<String,String> userIdentifiers = new HashMap<>();
        userIdentifiers.put("login", login);
        userIdentifiers.put("email", user != null ? user.getEmail() : null);

        // track user authentication success|error events
        Sqreen.authTrack(user != null, userIdentifiers);

        return user;
    }

}

The authTrack function accepts two arguments:

Sqreen.authTrack(boolean loginSuccess, Map<String,String> userIdentifiers)

  1. The loginSuccess argument is a boolean indicating if the login/signup attempt was successful or not (true or false).

  2. The userIdentifiers argument is a map with your user identification information. They will be used on Sqreen's user interface to help you identify which users are at risk, or which are attacking your application. The hash keys and values should only be strings.

Sqreen integration at signup and login

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

Signup tracking

Sqreen.signupTrack is the SDK method to call when creating a new user account, basically 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);

        // prepare user properties for event, any map implementation can be used
        Map<String,String> userIdentifiers = new HashMap<>();
        userIdentifiers.put("login", user.getLogin());
        userIdentifiers.put("email", user.getEmail());
        userIdentifiers.put("id", user.getId()); // you can also use your own properties in key

        // track user signup events
        Sqreen.signupTrack(userIdentifiers);

        return user;
    }
}

The signupTrack function accepts a single argument:

Sqreen.signupTrack(Map<String,String> userIdentifiers)

The userIdentifiers argument is a map whith your user identification information. They will be used on Sqreen's user interface to help you identify which users are at risk, or which are attacking your application. The hash keys and values should only be strings.

Session tracking

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

When the request is not identified using this method, Sqreen fallbacks 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;
        }

        // prepare user properties for event, any map implementation can be used
        Map<String,String> userIdentifiers = new HashMap<>();
        userIdentifiers.put("login", user.getLogin());
        userIdentifiers.put("email", user.getEmail());

        // associate current request with user
        Sqreen.identify(userIdentifiers, null /* no traits yet */ );

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

The identify function accepts two arguments:

Sqreen.identify(Map<String,String> userIdentifiers, Map<String,String> traits)
Sqreen.identify(Map<String,String> userIdentifiers)

  1. The userIdentifiers argument is a map representing the identification information. It will be used on Sqreen's user interface to help you identify which users are attacking your application. The hash keys and values should only be strings.

  2. The traits argument is an optional map of traits about the user.

User traits

At the moment, we do not display nor process the traits. In the near future, 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

If your users can be identified with a single value (email, nickname...), you can proceed that way:

Map<String,String> userIdentifiers = new HashMap<>();
userIdentifiers.put("email", user.getEmail());
Sqreen.authTrack(true, userIdentifiers);

User monitoring and PII

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

If your users are identified with a composite primary key (multiple values), all of them should be sent in order to identify them accurately on Sqreen's user interface.

For example, if you are are operating a whitelabel platform and your users are identified by their email and the shop id, you can send these identifiers like this:

Map<String,String> userIdentifiers = new HashMap<>();
userIdentifiers.put("email", user.getEmail());
userIdentifiers.put("platform_id", user.getPlatformId());
Sqreen.authTrack(true, userIdentifiers);

This also applies to signupTrack and identify methods.

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

Sqreen SDK only accepts user identifiers

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

Primary key

Sqreen will try to determine a primary key amongst the keys you provided. The following keywords will be used to determine the user primary identification key: email, mail, e-mail, username, login.

If none of those key are found, we will use the first in alphabetic order.

If multiple keys are found, we'll use 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 will be ignored.

Maven

Update your pom.xml with:

<repositories>
    <repository>
        <id>sqreen-sqreen</id>
        <url>https://packagecloud.io/priv/0b8af24f66baa46d7a70157fbc72641b4cbede5c9423b009/sqreen/sqreen/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.1</version>
    </dependency>
</dependencies>

Gradle

Update your build.gradle with :

repositories {
    maven {
        url "https://packagecloud.io/priv/0b8af24f66baa46d7a70157fbc72641b4cbede5c9423b009/sqreen/sqreen/maven2"
    }
}

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