NAV

Authentication in embedded apps

User authentication

In your application, you will likely show some user-specific data, for example the store order list. To do that, your iframe application will need to know:

  • The ID of the store using your application at the moment
  • The token that allows to access the store data
  • The language of the Ecwid Control Panel
  • Optional application state to initialize the app with

Ecwid will pass this data to your application as soon as it is opened in Ecwid Control panel. The way data is passed to your application and the way you should decrypt the received data depends on whether you process it on a client or a server side of your application.

Below, you will find the description of a default user authentication for native applications.

Default User Authentication

In the default user auth process, Ecwid will call your iframe URL like this:

https://www.example.com/my-app-iframe-page#53035362c226163636573735f746f6b656e223a22776d6

This process allows for simple user authentication in your app using the Ecwid JS SDK.

Continue with default authentication

Enhanced Security User Authentication

In the enhanced security auth process, Ecwid will call your iframe URL like this:

https://www.example.com/my-app-iframe-page?payload=353035362c226163636573735f746f6b656e223a22776d6&app_state=orderId%3A%2012&cache-killer=13532

We recommend using this type of authentication for complex applications that can modify parts of a store and require additional security measures.

Continue with enhanced security authentication

App authentication

After your app authorized a user, it will need an access token to the Ecwid REST API to read and modify Ecwid store orders, products and other information.

The process of getting the access token is different for each user authentication type. Both authentication processes are described below, so please check them out for more info on getting access tokens.

Default User Auth

Example of the iframe URL call in client-side apps

https://www.example.com/my-app-iframe-page#53035362c226163636573735f746f6b656e223a22776d6

Workflow of client-side applications

//
//  Get store details
//
    var storeData = EcwidApp.getPayload();
    var storeId = storeData.store_id;
    var accessToken = storeData.access_token;
    var language = storeData.lang;
    var viewMode = storeData.view_mode;

    if (storeData.public_token !== undefined){
      var publicToken = storeData.public_token;
    }

    if (storeData.app_state !== undefined){
      var appState = storeData.app_state;
    }

//
//  Get store specific data
//

    var backgroundColor;
    EcwidApp.getAppStorage('color', function(value) {
      if (value !== null) {
        // set user color from storage
        backgroundColor = value;
      } else {
        // set default color
        backgrountColor = 'black';
      } 
    });

//
//  Start the flow of your application
//  ...

Ecwid allows your application to fully reside on client side and not use server side at all. So you can authenticate the user, get store ID and access token, and manage the store data via Ecwid API right inside your app in Control panel without calling your server scripts.

By default, all applications are registered as client-side so you can start working on your application’s tab right away without using server side.

The workflow can be described into the following steps:

  1. Get store preferences and data
  2. Initialize your application functionality

1. Get store preferences and data

For convenience, we provide a simple Javascript SDK that you can use in your application to authenticate the user and get access to the API. As soon as the JS SDK script is used, you can call the provided EcwidApp.getPayload() method to retrieve the user’s store ID and access token as shown in example. See also .getPayload() method specification. So, in your application code, you will need to include Ecwid JS SDK script and use provided methods to authenticate the user as shown in the example.

If your application is going to store some user specified information, like background color, page IDs or something else, you can use Ecwid Javascript SDK to access Storage endpoint to easily store and access this data there without saving this information on your server.

See functions EcwidApp.getAppStorage, EcwidApp.setAppStorage and EcwidApp.setAppPublicConfig in Ecwid Javascript SDK for more details.

2. Initialize your application functionality

So once you know the store you are working with and you have the settings and other data specific to that store, you can use that information in your embedded application to start is stndard workflow.

Enhanced Security User Auth

By default, all applications are registered as client-side so you can start working on your application’s tab right away without using server side. If you need your app to be switched to server-side, please contact us and we will update your app.

The workflow of such applications can be divided into several steps:

  1. Decrypt the payload from the Ecwid Control Panel
  2. Get store specific data (optional)
  3. Initialize your application functionality

So let’s look a little closer on how to create a your embedded server-side application:

1. Decrypt the payload from the Ecwid Control Panel

Let’s say, you process user input and prepare the data to display in your app on your server and then pass this information to your application UI to be displayed in the user Control panel.

In this case, you will need to authenticate user on server side of your application. Ecwid sends an auth data to your app in a payload while requesting your iframe URL as follows:

https://www.example.com/my-app-iframe-page?payload={payload}&app_state={app_state}&cache-killer={cache-killer}

By default, all applications are registered as client-side so you can start working on your application’s tab right away without using server side. If you need your app to be switched to server-side to have the URL called as mentioned above, please contact us and we will update your app.

Example of the iframe URL call in server-side apps

https://www.example.com/my-app-iframe-page?payload=353035362c226163636573735f746f6b656e223a22776d6&app_state=orderId%3A%2012&cache-killer=13532

Workflow of server-side applications

<?php
//
//  Get and decrypt the payload from Ecwid
//

// authenticate user in iframe page
function getEcwidPayload($app_secret_key, $data) {
  // Get the encryption key (16 first bytes of the app's client_secret key)
  $encryption_key = substr($app_secret_key, 0, 16);

  // Decrypt payload
  $json_data = aes_128_decrypt($encryption_key, $data);

  // Decode json
  $json_decoded = json_decode($json_data, true);
  return $json_decoded;
}

function aes_128_decrypt($key, $data) {
  // Ecwid sends data in url-safe base64. Convert the raw data to the original base64 first
  $base64_original = str_replace(array('-', '_'), array('+', '/'), $data);

  // Get binary data
  $decoded = base64_decode($base64_original);

  // Initialization vector is the first 16 bytes of the received data
  $iv = substr($decoded, 0, 16);

  // The payload itself is is the rest of the received data
  $payload = substr($decoded, 16);

  // Decrypt raw binary payload
  $json = openssl_decrypt($payload, "aes-128-cbc", $key, OPENSSL_RAW_DATA, $iv);
  //$json = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, $payload, MCRYPT_MODE_CBC, $iv); // You can use this instead of openssl_decrupt, if mcrypt is enabled in your system

  return $json;
}

// Get payload from the GET and process it
$ecwid_payload = $_GET['payload'];
$client_secret = "0123abcd4567efgh1234567890"; // this is a dummy value. Please place your app secret key here
$result = getEcwidPayload($client_secret, $ecwid_payload);

// Get store info from the payload
$token = $result['access_token'];
$storeId = $result['store_id'];
$lang = $result['lang'];
$viewMode = $result['view_mode'];

if (isset($result['public_token'])){
  $public_token = $result['public_token'];
}

// URL Encoded App state passed to the app
if (isset($_GET['app_state'])){
  $app_state = $_GET['app_state'];
}

//
//  Get store specific data
//

// Get store specific data from storage endpoint
$key = 'color';

$url = 'https://app.ecwid.com/api/v3/' .$storeId. '/storage/' .$key. '?token=' .$token;

$ch = curl_init();

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL,$url);

$curlResult = curl_exec($ch);
curl_close($ch);

$curlResult = (json_decode($curlResult));
$color = $curlResult -> {'value'};

  if ($color !== null ) {
    // set color from storage
    } else {
    // set default colors
  }

//
//  Start the flow of your application
//  ...
?>

Example of decrypted payload

{
  "store_id": 1003,
  "lang": "en",
  "access_token":"xxxxxxxxxxxxxxxx",
  "view_mode":"PAGE",
  "public_token":"public_ASDlkDASmasdaslkdASkndasANJKLsAf"
}
NameTypeDescription
payloadstringEncrypted JSON string containing the authentication information (see the details below)
cache-killerstringRandom string preventing caching on your server
app_statestringOptional URL Encoded app state passed to the app in the URL

Payload

The payload parameter is encrypted JSON string, which, when decrypted, has the following format:

NameTypeDescription
store_idnumberEcwid store ID
langstringUser language (which is currently set in their Control Panel). Use this parameter to translate your application UI to the user language.
access_tokenstringSecure oAuth token for Ecwid REST API
public_tokenstringPublic oAuth token for Ecwid REST API
view_modestringMode used to display the application interface: in a POPUP or in a PAGE. PAGE is a default mode when app is displayed in a separate tab in Ecwid Control Panel

Decryption of payload on your server

Ecwid uses AES-128 to encrypt the payload. The key is the first 16 symbols (128 bit) of your application secret key (client_secret). It is provided when you register an app with us. See a PHP example of decryption to get better idea on how to receive and decrypt the payload.

2. Get store preferences and data

Now that you have successfully got store details and have access to it using Ecwid API, you can get store-specific information from the storage endpoint or from your local database.

The result of the payload decryption will be provided in an array $result, which you can use to get store ID, access token and language information about a store, that opened your app tab in Ecwid control panel.

To store and get store-specific data in storage endpoint, you can use cURL functionality in PHP or any other way that you prefer to access REST API endpoints. You can see the example code on how to retrieve the value of 'color' key in application storage using cURL and process the result on the right based on a response from API.

3. Initialize your application functionality

Once you got all details that you need, you can start the standard planned workflow for your app and operate with Ecwid API using the details you got earlier.