Secure Mode

Secure Mode is an optional setting for the JavaScript Analytics code that provides an additional layer of security for People and Live Chat.

It ensures that tracked pageviews, events and Chat messages can only be attributed to the genuine person actually sending them. This prevents a malicious visitor from being able to impersonate/spoof events using somebody else's unique identifier (we recommend using email but alternatively you can use id.)

How does it work?

In addition to identifying a user with a unique identifier, you can also sign any pageviews/events from that user with a keyed-hash that authenticates the user. We call this hash a 'Person Signature'.

The 'Person Signature' should be generated on your server by combining the user's unique identifier with your project's 'Secure Mode Secret' using a SHA-256 HMAC function (keyed-hash message authentication code). The output of the function would be your 'Person Signature' – which you would then inject into the tracking code when the identified visitor loads a page.

Why is this more secure?

Only your server and GoSquared have knowledge of the 'Secure Mode Secret' that was used to generate the 'Person Signature'.

When using Secure Mode, GoSquared can compare the 'Person Signature' in your tracking code to the 'Person Signature' we would expect to be generated for that user's unique identifier. If the 'Person Signatures' match, their activity is tracked. If the 'Person Signatures' don't match, we ignore their activity. Therefore it is impossible for anybody else to spoof activity that has not been signed by your server.

What about anonymous visitors?

If a user hasn't been identified yet, GoSquared will automatically handle Secure Mode for anonymous visitors.

Setting up Secure Mode

Secure Mode can only be configured for identified users. Therefore it is a pre-requisite that you must have implemented the identify function first. When a visitor is identified on your site, the tracking code on your site will also have to provide a 'Person Signature' that authenticates that the visitor is truly who they say they are.

  1. Log-in and navigate to Settings > Current Project > General to generate a Secure Mode Secret for your project. If you have more than one site, each one will have its own unique Secret. You should not share them publicly. Leave the Secure Mode toggle OFF until you have completed all the steps.

  2. Paste the Secure Mode Secret into you SHA-256 HMAC function on your server. Combine this with the unique identifier of the currently online person to generate a 'Person Signature'.

  3. Inject the 'Person Signature' into the tracking code on your webpage.

  4. When you are confident that you are successfully generating and injecting the 'Person Signature' you need to switch the Secure Mode toggle ON in Settings > Current Project > General. Turning on Secure Mode means that any pageviews/events without a 'Person Signature' will be ignored.

It is highly recommended that you test your Secure Mode implementation on a test site first before turning it on for your main site.

Usage

To sign requests with the JavaScript tracker, you'll need to generate the person-signature on your servers, then pass it to the Tracker via your webpage content:

// the standard Analytics code
!function(g,s,q,r,d){r=g[r]=g[r]||function(){(r.q=r.q||[]).push(arguments)};
d=s.createElement(q);d.src='//d1l6p2sc9645hc.cloudfront.net/gosquared.js';q=
s.getElementsByTagName(q)[0];q.parentNode.insertBefore(d,q)}(window,document
,'script','_gs');

_gs('your-project-token');

//your identify code
_gs('identify', {email: 'user@email.com'}):

//your person signature that is injected by your server
_gs('auth', 'PERSON_SIGNATURE');

The signature is a SHA-256 HMAC in hex format. The HMAC shared secret is your Secure Mode Secret, and the value is the id of the person being tracked. Most platforms ship with libraries for easily generating HMAC signatures.

NodeJS Example

var crypto = require('crypto');
var hmac = crypto.createHmac('sha256', 'Secure Mode Secret');
hmac.update('email-of-the-person');
var sig = hmac.digest('hex');
// Inject the signature into your page content, for example:
var ejsTemplate = "_gs('auth', '<%= YOUR_PERSON_SIGNATURE_HERE %>');";

PHP Example

_gs('auth', '<?php echo hash_hmac('sha256', 'email-of-the-person', 'Secure Mode Secret'); ?>');