Multipass login is available for store owners who have a separate website and a SHOPLINE store to redirect customers from the website to your SHOPLINE store with seamless logs using the same email address that they used to sign up from the original website.
If your customer does not have an account with the same email address, they are unable to create a new account with that email address, and the customer database will not be synced.
Table of content
- How to set up multipass
- Encode your customer information using JSON
- Encrypt the JSON data using AES
- Sign the encrypted data using HMAC
- Base64 encode the binary data
- Redirect your customer to your SHOPLINE store
- Example implementation
- Security considerations
- FAQ
How to set up multipass
To set up multipass:
-
From your SHOPLINE admin, go to Settings > Customer login.
- Toggle enable Login in with Multipass.
- Once enabled, a secret key will be shared with you. You will need the secret key in order to generate tokens to log your customer into your SHOPLINE store. Make sure you keep your secret key private.
Encode your customer information using JSON
The customer information is represented as a hash which must contain at least the email address of the customer and a current timestamp (in ISO8601 encoding). You can also include the customer's first name, last name or several shipping addresses. Optionally, you can include an IP address of the customer's current browser session, that makes the token valid only for requests originating from this IP address.
A minimal example, containing all required fields, might look like this:
{
"email": "jon@shopline.com",
"created_at": "2013-04-11T15:16:23-04:00",
}
An example containing some optional fields might look like this:
{
"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 that you may have already attributed to this customer.
If you want your users to see a specific page of your SHOPLINE store, you can use the return_to field for that.
|
SHOPLINE uses email addresses as unique identifiers for customers of a shop. When registering customers in SHOPLINE, the merchant must set the unique identifier in the "identifier" field in the following cases:
|
Encrypt the JSON data using AES
To generate a valid multipass login token, you need the secret given to you in your SHOPLINE admin. 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 bits are used as the encryption key and the last 128 bits are used as the signature key).
Encryption provides confidentiality. It makes sure that no one can read the customer data. As encryption cipher, we use the AES algorithm (128-bit key length, CBC mode of operation, random initialization 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 with. We use the HMAC algorithm with n SHA-256 hash function, and we sign the encrypted JSON data from step 3 (not the plaintext JSON data from step 2).
Base64 encode the binary data
The multipass login token now consists of the 128-bit initialization 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 SHOPLINE store
Once you have the token, you should trigger a HTTP GET request 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 not expired), the customer will be logged in to your SHOPLINE store.
The multipass token is only valid within a very short timeframe, and each token can only be used once. For those reasons, you should not generate tokens in advance for rendering them into your HTML sites. You should create a redirect URL which generates tokens on-the-fly when needed and then automatically redirects the browser.
Example implementation
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 the intended browser can use the token. We also encourage you to send tokens to the browser using secure HTTPS connections.
You should make sure that registering new accounts at your main website requires validation of the email address which is used. Otherwise, someone could sign up to your main site using somebody else's email address, thus getting access to this customer account in your SHOPLINE store.
FAQ
I have a huge customer database. How do I synchronize this with Shopify so that I can use multipass login?
You don't need to synchronize anything. As soon as you redirect a customer using multipass, we will automatically create a customer account for them in your Shopify store (if one doesn't exist yet).
Some of my customers have already placed orders on Shopify. How do I update those customers so they can log in through multipass?
You can use the Customer API to set the multipass_identifier for the customer. You will need to use the identifier with all your multipass requests for those customer accounts.
My secret was leaked. What do I do now?
If your secret ever leaks, it can be revoked in your shop admin, and a new one can be generated. This will make all of the old URLs invalid. You should do this as quickly as possible since everybody who knows the secret can potentially access every customer account!
Can I use a Multipass login between multiple Shopify stores?
No, Multipass cannot be used to log in between multiple SHOPLINE stores without redirection to an external site.
Does Multipass login work with the wholesale channel?
No, Multipass cannot be used with the wholesale channel.
Does the remote_ip field support IPv6 addresses?
No, only IPv4 addresses are supported. Multipass returns the error "You are not authorized to use Multipass login" if the remote_ip doesn't match the IP specified in the customer data hash.
Get in touch
SHOPLINE has a specialized Merchant Success Team available to assist you with any questions or issues. Please feel free to contact us via the chatbox in the lower right corner of your SHOPLINE admin panel or on the SHOPLINE official website. We are always here to support you every step of the way and help your business thrive.
Comments