6. Authenticating an App

1. Make your application appear in Erply back office, inside an iframe. A piece of Javascript glue code can pass a session key (or JSON Web Token) and client code to your application.
2. The application is hosted at a separate URL and presents a login page. Users will have to enter their back office user name and password; you can validate the credentials with the verifyUser API call.

Adding a New Plugin

A plugin integrated into the ERPLY Backoffice user interface can be almost anything: a separate page, a subsection of a form, a tab pane etc. The plugins should preferably be developed as standalone applications (for example a single-page application using React).

Plugins should be integrated as iframes by utilising the following methods described in section 6. Adding new pages and menu items. These code snippets can be inserted to the Backoffice by navigating to Settings → Configuration → Edit plugins.

The following is an example integrating a product pictures management plugin to the Backoffice:

$(document).ready(function () {
  if (section == 'product' && isExistingRecord) {
    var id = 'cdn'
    var iframeSrc = 'https://cdn-ui-sb.erply.com/cdn-product/' + recordID + '/' + page_lang
    var shortTitle = 'CDN Product Pictures'
    ErplyJsApi.addTabstripButtonToOpenIframe(id, iframeSrc, shortTitle, height, width)
  }
});

Authenticating Plugins

In order to be able to make successful API requests with the integrated plugins we need to use the JWT and/or session key that are usually provided by the Backoffice. Sending these tokens/keys as URL parameters is not a good security practice, and may not even be possible; a token might be too long to be passed as a URL parameter. This document provides a quick overview how to pass these tokens by utilising the Window.postMessage() method

Window.postMessage()

As mentioned in the MDN web docs:

The window.postMessage() method safely enables cross-origin communication between Window objects; e.g., between a page and a pop-up that it spawned, or between a page and an iframe embedded within it.

then the Window.postMessage() method can be used to communicate between an iframe and a parent window which is the case when integrating plugins into the ERPLY Backoffice.

Example

While the plugins are being initialised they should send a simple message to the parent window (ERPLY Backoffice) requesting for tokens/keys as such:

window.parent.postMessage(message, targetOrigin)

Where message could be JWT and targetOrigin as * for example. We don't need to know and set the targetOrigin specifically because we are not sending sensitive data in this step.

When the parent window (ERPLY Backoffice) catches the specific message from its iframe asking for tokens/keys it should send back the values to the iframe:

var authMessage = {
  sender: 'erply',
  jwt: jwt,
  apiSessionKey: apiSessionKey
}

window.addEventListener('message', function(message) {
  if (message.origin === 'https://cdn-ui-sb.erply.com' && message.data === 'JWT') {
    plugin.contentWindow.postMessage(authMessage, message.origin);
  }
}, false)

In this example message.origin is https://cdn-ui-sb.erply.com but it depends on the location of the plugin. plugin is the iframe element integrated into the Backoffice. jwt and apiSessionKey are variables that should already exist when Backoffice has been loaded. authMessage is the message object that can be customised depending on whatever tokens or keys have to be sent to the plugin. When the plugins receive the message they can start using the values:

window.addEventListener(
  'message',
  message => {
    if (message.origin.includes('erply.com')
      && message.data.sender === 'erply'
      && message.data.jwt
      && message.data.apiSessionKey) {
      // Proceed using message.data.jwt and message.data.apiSessionKey
    }
  },
  false
)

message.origin has to be the origin of the parent window, in this case it is pointing to the Backoffice origin like before. message.data.sender, message.data.jwt and message.data.apiSessionKey are the values sent with the message object that can be changed.