Multipass​

Understanding Multipass​

Multipass login is designed for store owners who have both a separate website and a SHOPLINE store. It redirects users from the website to the SHOPLINE store, allowing them to seamlessly log in using the same email address they used to register on the original website. If an account with that email address doesn’t already exist, a new account will be created. No customer database synchronization is required.

How to Use Multipass​

Enabling Multipass Login in SHOPLINE​

Log in to your store Administrator, go to "Setting up/sign in method",Scroll down and find "Log in with Multipass" and ensure that you have selected "Customer can sign up/sign in with email address".

Select Enable Multipass. Once enabled, a secret will be shared with you. You will need the secret in order to generate tokens to log your customers into your SHOPLINE store. Make sure you keep your secret private.

Encoding Customer Information Using JSON​

Customer information is represented as a hash, which must include at least the customer’s email address and the current timestamp (ISO8601 encoding). You can also include the customer’s name, surname, or multiple delivery addresses. Additionally, you can include the IP address of the customer’s current browser session, ensuring that the token is only valid for requests from that IP address.

A minimal example containing all required fields might look like this:

{
"email": "foo@shopline.com",
"created_at": "2020-08-01T23:15:22-04:00",
}

An example with some optional fields could be:

{
    "email": "foo@shopline.com",
    "created_at": "2020-08-01T23:15:22-04:00",
    "first_name": "Foo",
    "last_name": "David",
    "tag_string": "singaporean, premium",
    "identifier": "FooTest",
    "remote_ip": "26.122.66.91",
    "return_to": "http://yourstore_site.com/specific_site",
    "addresses": [{
        "address1": "4 Anson Road",
        "city": "Singapore",
        "country": "Singapore",
        "first_name": "Foo",
        "last_name": "David",
        "phone": "7653-2224",
        "province": "Singapore",
        "zip": "Foo",
        "province_code": "SGP",
        "country_code": "SGP",
        "default": true
    }]
}

You can attribute tags to customers by setting the tag_string as a comma-separated list of single-word values. These tags will override any existing tags attributed to the customer.

If you want users to see specific pages of your SHOPLINE store, you can use the return_to field.

Using AES Encryption for JSON Data​

To generate a valid Multipass login token, you’ll need a key provided by SHOPLINE Admin. This key is used to derive two encryption keys—one for encryption and one for signing. The derivation process involves using the SHA-256 hash function (with the first 128 bit as the encryption key and the last 128 bit as the signing key).

Encryption ensures confidentiality, preventing anyone from reading customer data. We use the AES algorithm (128-bit key length, CBC mode, random initialization vector) as the encryption cipher.

Signing Encrypted Data Using HMAC​

Signing (also known as a message authentication code) ensures authenticity.The signature ensures the authenticity of the multipass token and prevents tampering. We use the HMAC algorithm with the SHA-256 hash function and sign the AES-encrypted JSON data from the previous step (instead of plain-text JSON data).

Base64 Encoding for Binary Data​

Multipass login tokens now consist of a 128-bit initialization vector, variable-length ciphertext, and a 256-bit signature (in that order). This data is encoded using base64 (URL-safe variant, RFC 4648).

Redirecting Your Customers to Your SHOPLINE Store​

Once you have the token, trigger an HTTP GET request to your SHOPLINE store:

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

Multipass login tokens are valid for a very short time, and each token can only be used once. For these reasons, avoid pre-generating tokens to render them directly in HTML sites. Instead, create a redirect URL, generate tokens in real-time when needed, and automatically redirect the browser.

Example implementation​

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

public static void main(final String[] args) throws Exception {
  final String createAt =    ZonedDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ISO_INSTANT);
  final Map<String, String> dataMap = new HashMap<>();
  dataMap.put("email", "peter@shoplineapp.com");
  dataMap.put("created_at", createAt);
  final String dataJson = "..."; //json string from dataMap;
  final String secret = "...";
  final String token = generateToken(secret, dataJson);
  log.info("plaintext={}, token={}", dataJson, token);
}
public static String generateToken(final String secret, final String plaintext) throws Exception {
  // SHA-256 hash
  final MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
  final byte[] encodedHash =     messageDigest.digest(secret.getBytes(StandardCharsets.UTF_8));
  final byte[] encryptedKey = new byte[16];
  final byte[] signKey = new byte[16];
  System.arraycopy(encodedHash, 0, encryptedKey, 0, 16);
  System.arraycopy(encodedHash, 16, signKey, 0, 16);
  // iv
  final byte[] iv = new byte[16];
  new SecureRandom().nextBytes(iv);
  final SecretKeySpec encryptedKeySpec = new SecretKeySpec(encryptedKey, "AES");
  final Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
  cipher.init(Cipher.ENCRYPT_MODE, encryptedKeySpec, new IvParameterSpec(iv));
  // encrypt byte array
  final byte[] encrypted =   cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
  final byte[] ivEncryptedByte = new byte[iv.length + encrypted.length];
  System.arraycopy(iv, 0, ivEncryptedByte, 0, iv.length);
  System.arraycopy(encrypted, 0, ivEncryptedByte, iv.length, encrypted.length);
  final Mac hmac = Mac.getInstance("HmacSHA256");
  final SecretKeySpec signKeySpec = new SecretKeySpec(signKey, "HmacSHA256");
  hmac.init(signKeySpec);
  // sign byte array, 256 bit
  final byte[] signByte = hmac.doFinal(ivEncryptedByte);
  final byte[] tokenBytes = new byte[ivEncryptedByte.length + signByte.length];
  System.arraycopy(ivEncryptedByte, 0, tokenBytes, 0, ivEncryptedByte.length);
  System.arraycopy(signByte, 0, tokenBytes, ivEncryptedByte.length, signByte.length);
  String token = Base64.encodeBase64URLSafeString(tokenBytes);
  token = token.replace('+', '-')
.replace('/', '_');
  return token;
}

Security Considerations​

SHOPLINE encourages you to always set the remote_ip field in the customer data hash so that only expected browsers can use the token. We also recommend using secure HTTPS connections to transmit tokens.

You should ensure that new account registration on your main website requires validation of the email address used. Otherwise, someone could register on your main website using another person’s email address, potentially gaining access to their customer account in your SHOPLINE store.

FAQ​

Q: I have a large customer database. How can I synchronize it with SHOPLINE so that I can use multipass login?
A: You don’t need to sync any content. Once you use multipass to redirect customers, we’ll automatically create a customer account for them in your Shopline store (if it doesn’t already exist).

Q: Some of my customers have already placed orders on Shopline. How do I update these customers so they can log in via multipass?
A: You can use the Customer API to set the multipass_identifier for customers. You’ll need to use the identifier for all multipass requests related to these customer accounts.

Q: My secret key has been compromised. What should I do now?
A: If your secret key is leaked, you can disable it in your store admin and then re-enable it to generate a new secret key. This will invalidate all old URLs. It’s essential to do this promptly because anyone who knows the key could potentially access every customer account!

Q: Can I use Multipass login across multiple SHOPLINE stores?
A: No, Multipass cannot be used to log in between multiple SHOPLINE stores without redirecting to an external site.

Q: Is Multipass login applicable to wholesale channels?
A: No, Multipass cannot be used with wholesale channels.

Q: Does the remote_ip field support IPv6 addresses?
A: No, it only supports IPv4 addresses. If the remote_ip doesn’t match the specified IP in the customer data hash, Multipass returns an error: "You are not authorized to use Multipass login."