Add SSO to the website

Get started

You will need to go through these steps to get started with the SSO for your store:

• have a registered application for Ecwid with create_customers access scope

• install that app in your Ecwid store using instructions from Ecwid

• use application keys (client_*) for the SSO features

Pass user data to Ecwid

To enable Storefront Single Sign-on (SSO) on merchant's website, you need to pass encrypted user information to Ecwid JavaScript API. The user data itself needs to be prepared and encrypted on the server. See SSO Payload for the details.

Then, in the code of the store web page, you should send the encrypted user data to Ecwid. There are two ways you can do that:

1. Declaring a ecwid_sso_profile JS variable on the store web page containing the user information

2. Dynamically sending a user info to Ecwid by means of the Ecwid.setSsoProfile() JS API method

ecwid_sso_profile

You can inform Ecwid of the logged in user on your site in the ecwid_sso_profile JavaScript variable declared on the store pages. The ecwid_sso_profile variable can be declared anywhere in a web page, either before the Ecwid's script.js or after. The ecwid_sso_profile is initialized once – when Ecwid loads on the page.

Send user information in an SSO payload to Ecwid:

var ecwid_sso_profile = '93n3ufncucndndner9872h34b43ird8djd8d8 8787aa437a4aaa3ds8787 1421317550';

Ecwid.setSsoProfile()

The above mentioned SSO approach with setting ecwid_sso_profile variable works well when login/logout actions on the site are done along with the page reload. If a website utilizes AJAX for login/logout functionality, the page won't be reloaded and thus ecwid_sso_profile will not be updated instantly. In this case, you can use Ecwid.setSsoProfile() API method.

The Ecwid.setSsoProfile() method does exactly the same as setting of the ecwid_sso_profile variable, but can be used multiple times within the same "session".

Here is how you will use that:

• Handle all logins/logouts events on the page

• When a user is logged in, send an AJAX request to your server to retrieve SSO payload

• Execute Ecwid.setSsoProfile() function and pass the retrieved SSO payload as parameter

Sign in a user dynamically without page reloading by means of Ecwid.setSsoProfile():

// This is supposed to be executed after a user is logged in on your site

// Retrieve SSO payload from the server
var ssoPayload = ... 

Ecwid.setSsoProfile(ssoPayload);

📘

Ecwid.setSsoProfile works only when Ecwid is in SSO mode, that is, when the global variable 'ecwid_sso_profile' is also defined. Make sure 'ecwid_sso_profile' is defined at least as empty string, like this: ecwid_sso_profile = '' .

When no one is logged in

To specify that no user is logged in, pass an empty payload either to the ecwid_sso_profile='' variable or to Ecwid.setSsoProfile("") method. Ecwid will 'understand' that nobody is logged in at the moment and log out the current user if any.

Sign the SSO payload

When you pass user information to Ecwid either in ecwid_sso_profile JS variable or with Ecwid.setSsoProfile() method, you need to create and sign the payload. SSO payload contains of the following parts connected with a space character:

Generate SSO payload and send it to Ecwid to log the user in Ecwid (Example)

<?php
    $client_secret = "A1Lu7ANIhKD6A1Lu7ANIhKD6ADsaSdsa"; // example value
    $message = base64_encode("{appClientId: 'my-cool-app', userId:'234', profile: { email:'[e-mail]', billingPerson: { name: 'John Doe' } }}"); // example values
    $timestamp = time();
    $hmac = hash_hmac('sha256', "$message $timestamp", $client_secret);

    echo "<script> var ecwid_sso_profile = '$message $hmac $timestamp'; </script>";
?>

Message

The message is a Base64-encoded JSON string containing user profile fields and the application ID. See the Message field format explained below.

📘

Parameters in bold are mandatory

Field	Type	Description
appClientId	string	Your application's client_id value. Example: my-cool-app
userId	string	Any string identifying the user in the 3rd-party authentication system. Examples: 72551, johnsmith87. The combination of appClientId and userId identifies the customer profile in Ecwid connected with your site.
profile	Profile	User information. If a customer with the given combination of appClientId and userId already associated with some customer in your Ecwid store, the profile on file will be merged with the provided fields. Exception is the customer address book (shippingAddresses), which is only filled once when profile is created in Ecwid.

Profile

Field	Type	Description
email	string	Customer email
billingPerson	<Person>	Customer's billing name/address
shippingAddresses	Array<Person>	Customer address book items
registered	number (UNIX timestamp)	Registration date

Person

Field	Type	Description
name	string	Customer full name
companyName	string	Customer company name
street	string	Street
city	string	City
countryCode	string	Country code (2-letter code)
countryName	string	Country name
postalCode	string	Postal code (zip code)
stateOrProvinceCode	string	State/province code
phone	string	Phone number

Signature

The signature should be generated by HMAC SHA256 encryption of the Base64-encoded profile data and timestamp. Use your client_secret as a signature key. The secret key is provided when you register an application.

Every message should have different signature. If a message has a signature that has already been seen recently, Ecwid denies the sign-on request.

Timestamp

UNIX timestamp. The system clock on your server must be in sync with the actual time, otherwise signatures generated by your server will fail to validate in Ecwid. Ecwid allows this timestamp to be up to 10 minutes late. The timestamp ensures that the message cannot be intercepted and misused later.

FAQ

Q: Is SSO available to all stores?

Single Sign On is available for paid Ecwid users only. If an Ecwid store has no paid subscription, Ecwid stops processing SSO requests for that store and will behave as if no user is logged in.

Q: How do I know that SSO is working?

When ecwid_sso_profile variable is set on a page, Ecwid will hide the Sign In and Sign Out links in a storefront. However in some cases this doesn't mean that the SSO functionality is working successfully.

To make sure that Single Sign On functionality is working, customer in merchant's store should be able to do any action that any logged in customer would do: add shipping addresses to their address book, use prefilled details on checkout, etc.

Another clear indicator can be the email field in the payment method selection of the checkout process. If your storefront has this field hidden, then the Single Sign On is working correctly in your store.

When troubleshooting this issue, please make sure to check if the client_secret that you specified in your code is correct. You can find out more about it in the Signature section above.

Q: Can I use SSO for existing customer account in a store?

Ecwid does not allow two customers with the same email address in one store. If a customer with the same email already exists and has different SSO appClientId/userId, or does not have them at all, then Ecwid will fail to create a customer account and will behave as if no user is logged in.

For example, If you have a customer [e-mail] from Facebook, you cannot have another [e-mail] signing in using SSO. Ecwid will simply ignore [e-mail] passed in SSO.