PHP 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 PHP 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. Add three methods to your application. First, add signup_track (see details):
    <?php
    sqreen\signup_track(['email' => $email])
    ?>
    
  4. Add auth_track (see details):
    <?php
    sqreen\auth_track(is_login_successful, ['email' => $email])
    ?>
    
  5. Add identify (see details):
    <?php
    $user = get_user_from_cookie($_COOKIE['session_id']);
    sqreen\identify(['email' => $user->email])
    ?>
    

Here is a full implementation example:

<?php
// in the signup method, when the user account is created for the first time:
$user = signup($email, $password);
sqreen\signup_track(['email' => $email])

// ...

// in the signin method, when a user creates a new session:
$user = login($email, $password);
sqreen\auth_track($user !== NULL, ['email' => $email])

// ...

// On every request to map the authenticated user to the request
$user = get_user_from_cookie($_COOKIE['session_id']);
sqreen\identify(['email' => $user->email])
?>

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data or Personally Identifying Information (PII) 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.

signup_track

sqreen\signup_track is the SDK method to call when creating a new user account.

The signup_track function accepts a single argument:

<?php
sqreen\signup_track(user_identifiers)
?>

user_identifiers is a hash that represents a user's information. The Sqreen Dashboard uses it to help you identify which users are at risk, or which are attacking your application. The hash's keys and values must be strings.

auth_track

sqreen\auth_track is the SDK method to call call when a user logs in to your app.

The auth_track function accepts two positional arguments:

<?php
sqreen\auth_track(success, user_identifiers)
?>

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

user_identifiers is an object that represents a user's identification information. The Sqreen Dashboard uses it to help you identify which users are at risk, or which are attacking your application. The hash's keys and values must be strings.

Do not call too much

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

identify

sqreen\identify is the SDK method to use to map a user to the current HTTP request. It tracks user sessions.

The identify function accepts two positional arguments:

<?php
sqreen\identify(user_identifiers, traits)
?>

user_identifiers is an associative array that represents a user's identification information. Sqreen's interface uses it to help you identify which users are at risk, or which are attacking your application.

traits is an optional associative array that represents traits about the user. Sqreen does not yet display or process traits, though there are plans to do so in the future.

Consistently identify users

In all three methods (signup_track, auth_track, 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:

<?php
sqreen\auth_track(true, ['email' => $email])
?>

Composite primary key example:

<?php
sqreen\auth_track(true, ['email' => $email, 'platform_id' => $platform_id])
?>

Do not send PII! 🥧

Avoid configuring the microagent to send sensitive data or Personally Identifying Information (PII) 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

After you integrate the SDK for user monitoring in your app, you can extend Sqreen's protection capabilities even further to block suspicious users. To do so, use a Security Automation Playbook, a tool that enables you to customize and automate your app’s response to threats.

When using a playbook's built-in "Block User" security response, you must implement the identify and auth_track methods as above. If you do not implement these methods, Sqreen cannot map a user context to requests they perform on your application.

Next steps