Secure Identity MMOB Signature

Objective

To enable secure connection between MMOB and our customers and to prevent snippets from being abused by unauthorised parties, we are using an HMAC signature for more secure authentication method.

Introduction

There are 4 levels of security choices for our customers:

Levels of Security	Description
`Basic`	No extra security is needed, signature is not necessary for boot mmob snippet
`CSP`	This will enable Content Security Policy (CSP) which will stop others to boot mmob snippet without the permission of the snippet’s owner
`SECURE_IDENTITY`	This will enforce security identity feature between mmob and customer, hence, signature is required for customer to boot mmob snippet. Otherwise, a session to a user will not be issued.
`SECURE_IDENTITY_DEBUG`	This is similar to Basic security but it will generate response for debugging usage.

Implementation

mmob will provide our customers secret key for generating correct signature.

Create Signature with the provided secret key :

Example of generating HMAC signature with secret key in Typescript:

const createSignature = (cpId: string, cpDeploymentId: string, userEmail: string = '') => {
  // nonce     - a random string from 30 characters to 50 characters long. It's use is to prevent
  //             replay attack and statistical attack (eg. a rainbow table).
  //             It functions similar to a salt in hashing.
  // timestamp - an integer in string form of Unix epoch time (number of seconds
  //             since 1/1/1970). This also prevents replay attacks since it
  //             forces a recalculation for each request. The server should
  //             reject requests more than a specified amount of time out of sync
  //             (eg. 1 minute) to avoid reuse of old requests.
  // secretKey - secret_key provided by mmob

  const value = `${cpId}:${cpDeploymentId}:${userEmail}`;

  const timeStamp: number = Math.floor(Date.now() / 1000);
  const algorithmHMAC: string = 'sha256';
  const nonce: string = crypto.randomBytes(16).toString('hex');
  const secretKey = 'secret_key';
  const secretByteArray = Buffer.from(secretKey, 'base64');
  const signatureRawData = `${timeStamp.toString()}:${value}:${nonce}`;
  const signatureRawDataBuffer = Buffer.from(signatureRawData, 'utf-8');
  const signatureBytes = crypto
    .createHmac(algorithmHMAC, secretByteArray)
    .update(signatureRawDataBuffer)
    .digest();
  const base64SignatureBytes = signatureBytes.toString('base64');

  const hmacValue = `${timeStamp.toString()}:${base64SignatureBytes}:${nonce}`;
  return hmacValue;
};

Pass the signature in mmob snippet

Example mmob snippet for booting:

mmob.init({
  customerInfo: {
    email: customer email,
    first_name: 'Stephen',
    surname: 'Hayes',
    gender: 'male',
    title: 'Mr',
    building_number: '81',
    address_1: 'Miller Street',
    town_city: 'Hull',
    postcode: 'HG45BU',
    dob: '1968-05-30T21:12:22.275Z',
  },

  // integration configuration
  cp_id: 'cp_XXXXXXXXXXXXXXXXXXXXX',
  cp_deployment_id: 'cpd_XXXXXXXXXXXXXXXXXXXXX',
  location: '#integration',
  signature: 'xxxxxxxxx:xxxxxxxxxxxxxxxxxx:xxxxxxxxx'
  marketplace_url: 'https://integration.YOUR_DOMAIN.TLD',
});