Login with Multipass is designed for store owners who have a separate website and a SHOPLINE store. It redirects customers from the website to the SHOPLINE store and seamlessly logs them in with the same email address they would for the original site, together with new accounts if none were bound or created. Together with the fact that there is no need to synchronize any customer databases, this app can bring great convenience to its users. 

This article will explain what a Multipass is, how it is used, and its security features.

In This Article

• How to Use Multipass
• Implementation Case
• Security Concerns
• FAQs

 

---

How to Use Multipass

Enabling Login with Multipass in SHOPLINE

1. From your SHOPLINE admin panel, go to Settings > Customer account > Customer account type. Make sure that you have selected Classic customer account. Go to the Classic customer account section > Login with Multipass > Edit and click Enable.

2. Once enabled, you’ll receive an ‘encryption key’. This key is required for generating a token that allows customers to log in to your store. Please keep the keys safe.

Encoding Customer Information to JSON Format

Customer information is represented as a hash value, which must contain at least the customer’s email address and the current timestamp (refer to ISO8601). You can also include the customer’s given name, family name, or multiple shipping addresses, or include the IP address of the customer’s current browser session.

Sample hash value containing all required fields:

{
“email”: “peter@shopline.com”,
“created_at”: “2013-04-11T15:16:23-04:00”,
}

Sample hash value containing optional fields:

{
“email”: “peter@shopline.com”,

“created_at”: “2013-04-11T15:16:23-04:00”,

“first_name”: “Peter”,

“last_name”: “jason”,

“tag_string”: “canadian, premium”,

“identifier”: “peter123”,

“remote_ip”: “107.20.160.121”,

“return_to”: “http://yourstore.com/some_specific_site”,

“addresses”: [

{

“address1”: “123 Oak St”,

“city”: “Ottawa”,

“country”: “Canada”,

“first_name”: “Peter”,

“last_name”: “Jason”,

“phone”: “555-1212”,

“province”: “Ontario”,

“zip”: “123 ABC”,

“province_code”: “ON”,

“country_code”: “CA”,

“default”: true

}

]

}

You can attribute tags to your customer by setting “tag_string” to a list of comma-separated one-word values. These tags will override any tags you may have associated with this customer.

If you want your customers to view a specific page of your store, use the return_to field.

 

AES Encryption of the JSON Data

To generate a valid multipass login token, you need the key given to you in your SHOPLINE admin. The key 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 bits are used as the encryption key and the last 128 bits are used as the signing key).

Encryption provides confidentiality as it ensures that no one can read the customer data. The encryption key (128 bits, CBC mode, and random initialization vector) is generated through the AES algorithm.

Signing Encrypted Data Using HMAC

Signatures (also called message authentication codes) provide authenticity. They ensure that the Multipass token is authentic and has not been tampered with. The encrypted JSON data (instead of the plaintext JSON data) is signed using the HMAC algorithm of SHA-256.

Encoding Binary Data Using Base64

The token for login with Multipass consists of a 128-bit initialization vector, variable-length ciphertext, and 256-bit signature (in the order as stated here). It is encoded using Base64 (with URL-safe alphabet, as stated in RFC 4648).

Redirecting Customers to Your SHOPLINE Store

Once you have obtained the token, the HTTP GET requests will be redirected to your SHOPLINE store.

HTTP GET request: api/user/account/login/multipass/insert_token_here

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

The token is valid only for a short period and can be used only once, so you should not generate the token in advance. Otherwise, requests will be redirected to HTML websites. You should create a redirect URL and generate the token when needed so that requests can be redirected to your store automatically via the browser.

 

---

 

Implementation Case

The following shows a basic case of generating the token in Java:

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 Concerns

SHOPLINE encourages you to always set the remote_ip field in the customer data hash value so that only the specified browsers can use the token. SHOPLINE also encourages you to use a secure HTTPS connection to send the token to the browser.

You should ensure that registering new accounts at your main website requires validating the email address used. Otherwise, your account security may be compromised.

 

---

 

FAQs

• Q1: I have a huge customer database. How can I synchronize it with SHOPLINE so that I can use login with Multipass?
  A1: You don’t need to synchronize anything. Once you log in with Multipass to redirect customer requests, accounts will be created for the customers automatically in your SHOPLINE store (if no account has been created previously).
• Q2: Some of my customers have already placed orders on SHOPLINE. How can I update the information on these customers so that they can log in with Multipass?
  A2: You can use the customer APIs to set multipass_identifier for customers. The identifier is required for all log in with Multipass requests for these customer accounts.
• Q3: My key has been leaked. What should I do?
  A3: If your key is leaked, you can disable it on the Admin page of your store. A new key will be generated when you enable it again. This will invalidate all original URLs. You should disable the key as soon as possible because everyone who knows the key may use it to access your store using their customer accounts.
• Q4: Can I use login with Multipass across SHOPLINE stores?
  A4: No, Multipass cannot be used to log in between multiple SHOPLINE stores without redirection to an external website.
• Q5: Is login with Multipass applicable to wholesale channels?
  A5: No, Login with Multipass cannot be used for wholesale channels.
• Q6: Does the remote_ip field support IPv6 addresses?
  A6: No, only IPv4 addresses are supported. If the value of remote_ip does not match the IP address specified in the customer data hash value, log in with Multipass will return the error: “You do not have permission to log in with Multipass.”