Multipass

Multipass login is for store owners who have a separate website and a StoreHippo store. It redirects users from the website to the StoreHippo store and seamlessly logs them in with the same email address they used to sign up for the original website.

Let's say you are the owner of a successful website forum. All of your users must log in to the forum to contribute. Members of your forum can then purchase a forum t-shirt through your StoreHippo store. Unfortunately, your users have to log in to the forum first and then log in to your StoreHippo store before they can purchase a t-shirt. To reduce all this pain, you can use the multipass functionality which allows you to log in with the same credentials. 

Implementation

Follow the steps given below to implement the multipass functionality:

Enable Multipass login through your store admin

1. Log in to your StoreHippo Admin Panel.
2. Go to the Settings >  MISC section.
3. Scroll down to Multipass field. Select the checkbox to enable the multipass feature.
   
4. Once the Multipass is enabled, a secret multipass key is visible underneath. You need the secret key to generate tokens to log your customers into your store. Make sure you keep your secret private.

Encode customer information using JSON

The customer information is represented as a hash which must contain at least the email address of the customer. You can also include the customer's first name, last name.
A minimal example, containing all required fields, might look like this:

{  email: \"[email protected]\",  first_name: \"Xyz\",}

Encrypt the JSON data using AES

To generate a valid multipass login token, you need the secret key obtained from your StoreHippo Admin Panel. The secret is used to derive two cryptographic keys — one for encryption and one for signing. This key derivation is done through the use of the SHA-256 hash function (the first 128 bit are used as the encryption key, and the last 128 bit are used as signature key).

The encryption provides confidentiality. It makes sure that no one can read the customer data. As encryption cypher, we use the AES algorithm (128-bit key length, CBC mode of operation, random initialisation vector).

Sign the encrypted data using HMAC

The signature (also called message authentication code) provides authenticity. It makes sure that the multipass token is authentic and hasn't been tampered. We use the HMAC algorithm with an SHA-256 hash function, and we sign the encrypted JSON data from step 2 (not the plaintext JSON data from step 1).

Base64 encode the binary data

The multipass login token now consists of the 128-bit initialisation vector, a variable length ciphertext, and a 256 bit signature (in this order). This data is encoded using base64 (URL-safe variant, RFC 4648).

Redirect your customer to your StoreHippo store

Once you have the token, you should trigger an HTTP GET request to your StoreHippo store.

GET /ms/login/multipass/insert_token_here

When the request is successful (e.g. the token is valid and not expired), the customer will be logged in to your StoreHippo store.

Implementation example

The following shows a basic example implementation of the token generation in NodeJS.

const crypto = require('crypto');

const KEY = "multipass secret from admin";

let hash = crypto.createHash("md5").update(KEY).digest('hex');
let _encryptionKey = hash.slice(0, 16);
let _signingKey = hash.slice(16, 32);
let calculateHmac = function (key, data) 
{    
     return crypto.createHmac('SHA256', data).update(key).digest();
};
let encryptToken = function (key, data, iv) 
{    
    let cipher = crypto.createCipheriv('aes-128-cbc', key, iv);    
    return Buffer.concat([iv, cipher.update(data, 'utf8'), cipher.final()]);
};
let user = {
      email: "test.user@store.com"
};
let iv = crypto.randomBytes(16);
let verUser = encryptToken(_encryptionKey, JSON.stringify(user), iv);
let verHmac = calculateHmac(_signingKey, verUser);
let token = Buffer.concat([verUser, verHmac]).toString('base64');
token = token.replace(/\\+/g, '-');