Single sign-on (SSO) is a user authentication process that permits a user to enter one login and password in order to access multiple applications. For example if your site already has the ability to create accounts and you are using Ecwid your customers may find it rather inconvenient that they have to log in to your site and store separately.
This API allows your customers to sign into your site and fully use your store without having to sign into Ecwid. I.e. if a customer is logged in to your site, he/she is logged in to your store automatically, even if he/she didn’t have an account in your store before. This API is helpful for sites with an existing user base, who wants to make checkout process more transparent and easy for their customers.
Please note that this API is only available in the “Premium Features” subscription.
API Details
Providing user information to Ecwid
To make use of Single Sign-on (SSO) in your website it is neccessary to pass the signed user information to the Ecwid JavaScript API. This can be done by declaring the ecwid_sso_profile variable in your page and assigning it a value, containing three parts separated by spaces:
- Base64-encoded JSON string containing user profile fields. The format of the profile field object is given below;
- HMAC SHA1 signature of the Base64-encoded profile plus timestamp. Use your SSO secret key as a signature key. The secret key can be obtained in Control Panel → System Settings → API.
- Current timestamp, i.e. the number of seconds during UNIX epoch. The system clock on your server must be in sync with the real 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.
Every message should have different signature. If a message has a signature that has already been seen recently, Ecwid denies the sign-on request.
To specify that no user is logged in, pass an empty string to the ecwid_sso_profile. The ecwid_sso_profile variable can be declared anywhere in your web page, either before the script.js or after. The ecwid_sso_profile is read once when Ecwid loads.
Assuming your secret key is ‘TEST’, the following PHP example creates a signed profile string:
Profile field object
The fields of the profile object are:
| Name |
Type |
Description |
| appId |
string |
Any arbitrary string identifying the 3rd-party authentication system. Never change your appId! see note below. |
| userId |
string |
Any string identifying the user in the 3rd-party authentication system. The combination of appId and userId identifies the customer profile in Ecwid |
| profile |
Customer
(see this article)
|
Contains information about the user. The ‘id’ field of this object is ignored. This field is optional. If omitted, an anonymous Ecwid customer profile is created.
If a customer with the given combination of appId and userId already exists in Ecwid database, its profile gets merged with the specified fields of the profile object, except for the customer’s address book (the field shippingAddresses), which is only imported once when profile is created at the Ecwid side.
|
Dynamically signing in or off
There is also a way to provide changes to the signed profile without reloading the web page, e.g. when implementing AJAX login/logout buttons. The Ecwid.setSsoProfile(profile) API call does exactly the same as ecwid_sso_profile, but can be used multiple times. Note that Ecwid.setSsoProfile(profile) only works when Ecwid is in SSO mode, that is, when the global variable ecwid_sso_profile is also defined.
Providing sign in / sign out functionality
Albeit optional, but highly recommended that you provide Ecwid a way to sign in your website. You can do that in two ways:
Either set up the sign in / sign out page URLs:
...or set up JavaScript actions to be invoked when signin in or out:
Note the wrapping window.Ecwid.OnAPILoaded call. As usual, JS API methods are available after window.Ecwid.OnAPILoaded callbacks are signalled. This is explained here: JavaScript API
window.Ecwid.setSignInUrls method
Sets up URLS of sign in / sign out pages of the website. The only argument is an object with the following fields:
| Name |
Type |
Description |
| signInUrl |
url, string |
URL to which a customer will be redirected when Ecwid needs authorization, like when viewing orders. |
| signOutUrl |
url, string |
Optional. If specified, Ecwid shows the 'sign out' link pointing at this URL |
window.Ecwid.setSignInProvider method
Sets up Javascript functions to be called when Ecwid requires authorization or to be called when clicking the 'sign out' link. The only argument is an object with the following fields (all fields are mandatory):
| Name |
Type |
Description |
| addSignInLinkToPB |
function returning boolean |
Return true if you need the 'sign in' link inside your Product browser |
| signIn |
function |
This function is called when Ecwid is trying to authorize the customer, when either 'sign in' link is clicked or a secured page is opened inside Product Browser (e.g. 'My account' page). This function does not accept any arguments nor should return any result. |
| canSignOut |
function returning boolean |
Return true if you need the 'sign out' link inside your Product browser |
| signOut |
function |
This function is called when canSignOut returns true and a customer clicks the 'sign out' link. |
Notes
- 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 appId/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 “customer@example.com” from Facebook, you cannot have another “customer@example.com” signing in using SSO. Ecwid will simply ignore “customer@example.com” in the ecwid_sso_profile variable.
- If the Ecwid store has no paid subscription, Ecwid stops processing SSO messages for that store and will behave as if no user is logged in.
- Never change your appId! Changing appId of an existing authentication system will result in inability of registered customers to sign on your website, because new customers will have different appId/userId combination and conflict with existing database records with the same email.
Examples
The following example shows how to pass the user profile information to Ecwid and how to “log out” the user using JavaScript API. When called with the ?logoff=1 parameter, this script behaves as no user is logged in.
