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, 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.

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 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 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, 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

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