Java SDK for user monitoring

Sqreen monitors user behavior for signs of Account Takeover (ATO) and targeted attacks. To do so, the microagent uses advanced, integrated functionality in the form of an SDK.

Automatic: (Not available) The Sqreen Microagent does not establish user context automatically on Java applications.

Advanced: (Optional) Install and integrate the Sqreen SDK so that the microagent tracks user activity in your app beyond the built-in capabilities.

Learn more about User protection in general.

Install and integrate the SDK

  1. From the Sqreen Dashboard, access Settings > Global and scroll to User monitoring.
  2. Change the mode from "Off" to "Advanced".
  3. Because the Sqreen SDK is a separate library, you must add it to your application's dependencies.
      Maven
    • Update your pom.xml file. 
      <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 file. 
      repositories {
    maven {
     url "https://packagecloud.io/sqreen/sqreen-public/maven2"
  }
}

dependencies {
  compile group: 'io.sqreen', name: 'sqreen-sdk', version: '0.3'
}
  4. Add three methods to your application. First, add trackSignup (see details): 
    import io.sqreen.agent.sdk.Sqreen;

public class SignupController {
    // .. other parts of the class omitted 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;
    }
}
  5. Add trackLogin (see details): 
    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;
    }

}
  6. Add identify (see details): 
    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 identification
            .trait("mood", user.getMood())
            // associate current request with user
            .identify();

    }
}

Here is 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 = getCurrentUser(request);

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

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data, Personally Identifying Information (PII), or Personal Health Information (PHI) to the Sqreen Platform. Instead, use Universally Unique Identifiers (UUID) or hashes. Read this blog post to learn about best practices for user monitoring and PII.

trackSignup

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

The trackSignup function has no argument. 

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

The microagent creates a user identity using chained authKey builder method calls. The Sqreen's user interface uses the authKey builder method calls to help you identify which users are attacking your application.

trackLogin

trackLogin() is the SDK method to call when a user logs in to your app.

The trackLogin function accepts a single argument. 

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

The microagent creates a user identity using chained authKey builder method calls. The Sqreen's user interface uses the authKey builder method calls to help you identify which users are attacking your application.

success is a boolean indicating whether a user's login attempt was successful or not (true or false).

Do not call too much

Do not call trackLogin every time you check a user session in your application. Use it track when a user logs in.

identify

identify is the SDK method to use to attach a user to the current HTTP request that Sqreen processed. The Sqreen microagent embedded in your app uses this method to provide user context. This user context is useful when you are reviewing malicious requests that Sqreen flagged. Note, this method does not attach a user to a request and send data to Sqreen for every request a user makes, just the requests that Sqreen flagged as malicious.

The identify method has no argument. 

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 microagent creates a user identity using chained authKey builder method calls. The Sqreen's user interface uses the authKey builder method calls to help you identify which users are attacking your application.

The microagent gets user traits using chained trait(String trait, String value) builder method calls. Sqreen does not yet display or process traits, though there are plans to do so in the future.

If you do not configure Sqreen to identify the request using this method, Sqreen relies on login tracking data to map a user's activities. Using login tracking data is not as good as using identify as it is based only on the recent activity of users on the request's IP addresses.

Consistently identify users

In all three methods (trackSignup, trackLogin, identify), you can identify users by:

  • a single identification value, such as an email address or nickname
  • a composite primary key, such as an email address and platform id

All three methods must use the same identity format for Sqreen to map activities to a single user. Further, the Sqreen SDK only accepts user identifiers. Do not send any other information, such as the auth failure reason. Extra information prevents Sqreen from correctly mapping activities to a single user.

Single identification value example: 

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

Composite primary key example: 

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

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data, Personally Identifying Information (PII), or Personal Health Information (PHI) to the Sqreen Platform. Instead, use Universally Unique Identifiers (UUID) or hashes. Read this blog post to learn about best practices for user monitoring and PII.

Block users

Sqreen uses Security Automation Playbook functionality to block users from accessing your app. However, Security Automation Playbooks are not yet available for use with Java applications.

Next steps