Mattermost User Security Analytics

Mattermost — a popular collaboration platform — does not directly offer user behaviour analytics capabilities. This limitation can be overcome by integrating Tirreno with Mattermost. Having Tirreno platform integrated, you can maintain detailed audit trails, monitor login locations, and protect accounts from unauthorized sharing or takeover.

Setting up data capture on a Mattermost instance requires only adjustments to the existing web server configuration. No changes to the Mattermost codebase are necessary.

Prerequisites

Attention

Before implementing the provided Nginx configuration in a production environment, testing it in a development or staging environment is crucial. Using these settings without prior testing and validation is strongly discouraged and done entirely at your own risk.

Tirreno Integration

Basics

In order to enable integration with Tirreno, information about the original Mattermost requests has to be transmitted to the Tirreno API.

To achieve this, in the Nginx configuration file add the location = /mirror {...} block to the server context. Also, append mirror /mirror; directives to all existing location blocks.

 1location = /mirror {
 2    internal;
 3
 4    set $args "";
 5    set $new_query_string "userName=$cookie_MMUSERID&ipAddress=$remote_addr&userAgent=$http_user_agent&httpReferer=$http_referer&httpMethod=$request_method&url=$request_uri&eventTime=$php_timestamp&browserLanguage=$http_accept_language";
 6
 7    proxy_pass https://tirreno.yourcompany.com; # Replace with your Tirreno URL
 8    proxy_method POST;
 9    rewrite ^ /sensor/ break;
10
11    proxy_set_body $new_query_string;
12    proxy_set_header Content-Type "application/x-www-form-urlencoded";
13    proxy_set_header Api-Key "XXXXXXXXXXXXXXXXXXXXXXXXX"; # Replace with your Tirreno tracking code
14    proxy_pass_request_body off;
15}

For the example to function in your environment, remember to replace the placeholders with actual values. That is:

  • Enter your Tirreno URL as proxy_pass value.

  • Enter Tirreno tracking code as Api-Key header value (see API page).

Configuration Details

The subsection below demonstrates the complete Nginx configuration file. It contains additional placeholders that must be replaced with values pertinent to your setup.

Also, note the following details:

Time format

The Tirreno API requires the parameter eventTime to be sent in the Y-m-d H:i:s.v format (with milliseconds). Since Nginx does not support direct timestamp format manipulation, the example configuration uses the map directive for time formatting.

Timezone

Ensure that Nginx or its environment is configured to use the UTC timezone. For instance, you can use the directive env TZ=UTC in the Nginx configuration file to specify the timezone.

User name

By default, Mattermost only provides internal usernames. To find actual user names, go to System Console > User Management > Users in your Mattermost instance and compare MMUSERID with the user’s name and email.

Final Steps

After adjusting the Nginx configuration, verify its syntax with sudo nginx -t. Apply the changes by reloading the configuration file or by restarting the web server (e.g., sudo systemctl restart nginx).

Now open your Mattermost client and login. Finally, visit the Tirreno console to check the displayed event details.

Example Nginx Configuration

 1server {
 2    listen 80;
 3    server_name mattermost.yourcompany.com;  # Replace with Mattermost host
 4
 5    return 301 https://$server_name$request_uri;
 6}
 7
 8map $time_iso8601 $formatted_datetime {
 9    "~^(?<date>\d{4}-\d{2}-\d{2})T(?<time>\d{2}:\d{2}:\d{2})" "$date $time";
10}
11
12map $msec $milliseconds {
13    '~^\d+\.(?<millis>\d+)$' $millis;
14}
15
16map $formatted_datetime $php_timestamp {
17    "~^(.+)$" "$formatted_datetime.$milliseconds";
18}
19
20server {
21    listen 443 ssl http2;
22    server_name mattermost.yourcompany.com; # Replace with Mattermost host
23
24    ssl_certificate /etc/letsencrypt/live/mattermost.yourcompany.com/fullchain.pem; # Replace with your certificate path
25    ssl_certificate_key /etc/letsencrypt/live/mattermost.yourcompany.com/privkey.pem; # Replace with your certificate path
26    ssl_session_timeout 1d;
27    ssl_session_cache shared:MozSSL:10m;
28    ssl_session_tickets off;
29
30    ssl_protocols TLSv1.2 TLSv1.3;
31    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
32    ssl_prefer_server_ciphers off;
33
34    add_header Strict-Transport-Security "max-age=63072000" always;
35
36    location / {
37        proxy_pass http://backend; # Replace with IP and port if you use container deployment
38        proxy_http_version 1.1;
39
40        proxy_set_header Upgrade $http_upgrade;
41        proxy_set_header Connection "upgrade";
42        proxy_set_header Host $host;
43        proxy_set_header X-Real-IP $remote_addr;
44        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
45        proxy_set_header X-Forwarded-Proto $scheme;
46        proxy_set_header X-Frame-Options SAMEORIGIN;
47
48        # Websocket support
49        proxy_set_header Upgrade $http_upgrade;
50        proxy_set_header Connection "upgrade";
51
52        mirror /mirror;
53    }
54
55    location = /mirror {
56        internal;
57
58        set $args "";
59        set $new_query_string "userName=$cookie_MMUSERID&ipAddress=$remote_addr&userAgent=$http_user_agent&httpReferer=$http_referer&httpMethod=$request_method&url=$request_uri&eventTime=$php_timestamp&browserLanguage=$http_accept_language";
60
61        proxy_pass https://tirreno.yourcompany.com; # Replace with your Tirreno URL
62        proxy_method POST;
63        rewrite ^ /sensor/ break;
64
65        proxy_set_body $new_query_string;
66        proxy_set_header Content-Type "application/x-www-form-urlencoded";
67        proxy_set_header Api-Key "XXXXXXXXXXXXXXXXXXXXXXXXX"; # Replace with your Tirreno tracking code
68        proxy_pass_request_body off;
69    }
70}

Your Tirreno Adventure Awaits

This use case is just one small example of what you can achieve with the Tirreno platform.

Tirreno is the easiest way to get started with security user analytics. An open-source version of Tirreno is available for free on GitHub.