Skip to content

Create a plug-in

A plugin is a (responsive) web application. Let us imagine Super Company is developing a plugin for the Relevance platform. This plugin runs on the following domain: plugin.supercompany.com. A plugin can have one (or more) entrypoints - these are the base URL's that will be called when the plugin is integrated in the app or webapp. Let us say the Super Company plugin has one entrypoint: https://plugin.supercompany.com/home.

When the Relevance app or webapp opens the plugin, it will pass a JWT token to the entrypoint URL as the token parameter. This serves 2 purposes:

  1. The token is signed using a private key known only to the Relevance platform. The public key is then shared with the plugin so that the plugin can check the validity of the JWT's signature. In this way, the plugin can be sure that the user trying to access the plugin is actually a legitimate Relevance user and that the data contained in the token can be trusted.

  2. The token contains information about the user trying to access the plugin (eg: their ID). It can also contain more information, this is configurable through the Relevance dashboard.

A sample JWT token is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ0ZXN0QG9ydGVjLmNvbSJ9.sNGHyPWYMgqj0eLYL90Rj1JiJJ-Wukw-iWp4i07NuAo

The playload of this token is:

{
  "uid": "test@ortec.com"
}

The token is signed and verified using an asymmetric private/public key pair. Plugin developers only have access to the public key to verify the signature, but are not able to sign tokens using this key. The private key is necessary to sign the token and this remains available only to the relevance platform. When verifying the key, plugin developers should ensure they choose the correct algorithm (RS256) for use with asymmetric keys (see this explanation for more detail).

In addition to the token parameter, the plugin will receive the following paramaters:

  • os_name: The OS from which the user is opening the plugin
  • lang: The language preference of the user opening the plugin

A plugin may use cookies to manage sessions and state (see caveats about cookie usage).

An example of a basic (skeleton) plug-in using node.js and express:

var jwt = require('jsonwebtoken');  
var express = require('express');  
var bodyParser = require('body-parser');
var cookieParser = require('cookie-parser');
var app = express();  

app.use(cookieParser());
app.use(bodyParser.urlencoded({extended:true}));

app.use(function(req, res, next){  
    var token = req.query.token || req.cookies.token;  
    jwt.verify(token, key, {algorithms:['RS256']}, function(err, params){  
        if (err) return res.status(400).send('error');  
        if (!params) return res.status(400).send('error');  
        // params contains a json object with the exposed profile data  
        req.user = params;              // for use in routes  
        res.cookie('token', token);     // store token in cookie  
        next();  
    });  
});

app.get('/', function(req, res){
    res.json({user:req.user});
});

app.listen(8080, function(err){
    if (err) throw(err);
});