Secure Identity MMOB Signature

Objective

To enable secure connection between the mmob platform and digital channels integrating embedded services, and to prevent snippets from being abused by unauthorised parties, wmmob utilises an HMAC signature for more secure authentication method.

Introduction

There are 4 levels of security choices for mmob clients:

Levels of Security	Description
`Basic`	No extra security is needed, signature is not necessary to 'boot' the mmob snippet
`CSP`	This will enable the Content Security Policy (CSP) which will stop others from 'booting' mmob snippet without the permission of the snippet’s owner
`SECURE_IDENTITY`	This will enforce a security identity feature between mmob and the Partner channel implementing the embedded service, hence, signature is required for customer to 'boot' the 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 a 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',
});