Identity

The purpose of the identity callback is to generate two JSON web tokens (JWTs) that provide access to the dashboard configuration, and access to the user's data. These keys are signed with your private key on your server, and validated with the public key you upload to Vizzly, and provide in the Vizzly config of the Vizzly Query Engine.

Server side token generation

yarn add @vizzly/auth

import * as VizzlyAuth from "@vizzly/auth";

import * as fs from 'fs';
import { createSigner } from '@vizzly/auth';

const TTL_IN_MINUTES = 120;

export const getIdentityTokens = async () => {
  const privateKey = fs.readFileSync("../../example-key-pairs/vizzly-private.pem").toString();
  
  const signer = createSigner({ ttlInMinutes: TTL_IN_MINUTES, privateKey })

  return await signer.generateTokens({
    // What data sets does this user have access too?
    // If can either be a list of data set IDs, or a "*" to allow
    // access to all data sets.
    dataSetIds: ["hr-payroll-data", "hr-people-data"],

    // What secure filters need to be added, to ensure this user
    // only sees their own data? For example here, we set a filter
    // to only use data where the field `field_user_id` equals a
    // specific user ID. 
    secureFilters: {
      "hr-payroll-data": [{
        field: "field_user_id",
        op: "=",
        value: "<< the user's ID >>"
      }],
      "hr-people-data": [{
        field: "field_user_id",
        op: "=",
        value: "<< the user's ID >>"
      }],
    },

    // Is the user a standard user, or should they have 'admin'
    // access allowing them to manage the dashboard for ALL your users.
    accessType: 'standard',

    // What is your organisation ID? Find yours on
    // https://app.vizzly.co/dashboards
    organisationId: 'org_12345',

    // Which dashboard template should be used? Find yours on
    // https://app.vizzly.co/dashboards
    dashboardId: 'dsh_12345',

    // A unique identifier for the current user, that you are
    // happy for Vizzly to store.
    userReference: '<< a reference to the current user >>',

    // Allow the user to view and make changes to the dashboard.
    scope: 'read_write'
  });
};

To find out more about the access type, you can see the definition of it on our concepts page.

Scope and read-only access

By default, Vizzly will allow users to make changes to their dashboards. However, if you want to provide a read-only view to your users, you can set scope to be 'read'. This is also useful if you want to build a dashboard sharing feature, where you can provide one user with read-only access to another user's dashboard.

The allowed scope values are 'read_write' and 'read'.

Generating test identity configs

A test identity config can be generated using our CLI tool. To do this you will need to collect your organisation ID and template dashboard ID from the dashboards page (opens in a new tab) on the Vizzly website after signing in.

You will then be able to run the command which MUST only be used in development environments;

vizzly access-tokens \
  -o org_<<rest of organisation ID>> \
  -u "user 123456" \
  -t admin \
  --private-key vizzly-private.pem

That will generate an identity signature that you can use for testing. This MUST only be used in test environments, as it grants full read access to all the data in the database.

{
  "dashboardAccessToken": "...",
  "dataAccessToken": "..."
}

Finding parameters

To find your organisationId and initialDashboard values of your live dashboards, see the parameters doc.

Controlling data set access

If you're running the Vizzly query engine, the dataSetIds value of the data access token is where you can control what data sets your users have access too. For example, say you have 3 data sets defined in the configuration file of your Vizzly query engine, which have IDs das_1, das_2 and das_3, then you could return an identity config which only specifies das_1 and das_2 in the dataSets parameter, and prevent the user from having access to the third data set.

Multi-tenancy with secure filters

To secure access to your data sets, you must provide a list of secure filters for each data set that is available to the user. For example, say you have a data set with an ID of das_1, and you want to only show users there own data from this data set, you might specify a secureFilters value of:

{
  secureFilters: {
    "das_1": [{
      field: "User ID",
      op: "=",
      value: 1
    }]
  }
  // ... rest of identity config
}

These secure filters will be signed and sent to the Vizzly query engine by the Vizzly react embed, where they will be validated using your organisation's public key and ensure that each user only ever has access to their own data.

Reduce the impact of a compromised private key

If your private key becomes compromised, then one way to reduce the impact of this is to also provide secure filters on your data sets defined in the config of your Vizzly query engine.

Generating private and public keys

For help generating the public and private keys, please see the security docs.

Client side

The client side implementation of the identity callback can be as simple as the following;

import Vizzly from '@vizzly/dashboard';
import './App.css';

function App() {
  return (
    <Vizzly.Dashboard
    queryEngineEndpoint='<< Your query engine endpoint >>'
    identity={async () => {
      const response = await fetch("<< Your identity endpoint >>");
      if(response.ok) {
        const tokens = await response.json();

        return tokens.accessTokens;
      };

      return null;
    }}
    />
  );
}

export default App;