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";

/*
  Receives HTTP requests, and responds with the user's
  identity information.
*/
export default async function handler(req, res) {
  const vizzAuth = VizzlyAuth.createSigner({
    privateKey: PRIVATE_KEY,
    ttlInMinutes: IDENTITY_TTL,
  });

  const tokens = await vizzAuth.generateTokens({
    // Provide Vizzly with a reference of the current user.
    userReference: getUserReference(req),
    // Does the current user have 'editor' or 'standard' access.
    accessType: "editor",
    // Provide access to all data sets.
    // Or provide a list of data set IDs if you want to limit access.
    dataSetIds: "*",
    // Setup the secure filters. (None setup in this example)
    secureFilters: {},
    // Your organisation ID. Found at https://app.vizzly.co/dashboards
    organisationId: "org_9817c013a80944cea5890df34ab792cd",
    // Your dashboard template ID. Found at https://app.vizzly.co/dashboards
    dashboardId: "dsh_42496c1c55e24bd985dc71bdc4a85f9d",
    // Allow the user to have read_write access to their dashboard.
    // Allowed values are 'read_write' or 'read'.
    scope: 'read_write'
  });

  res.status(200).json(tokens);
}

What is access type?

The accessType value can either be editor or standard and controls who gets to modify the initial dashboard new users will see.

Set this value to editor if the current user should be allowed to manage the dashboard that every user will initially see. Most commonly, this value will be set to editor only for certain staff from your company.

If you're an editor - you'll see a banner at the top of the dashboard with a "configure" button which will allow you to make changes to the default dashboard. If you are a standard user, then you will not be able to see the banner.

The editor banner looks like this;

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 live 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>> \
  -d dsh_<<rest of dashboard ID>> \
  -u "user 123456" \
  -t editor \
  --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
    type='self-hosted'
    vizzlyDockerImageEndpoint='http://0.0.0.0:8000'
    identityCallback={async () => {
      const response = await fetch("http://0.0.0.0:3005/api/identity");
      if(response.ok) {
        const tokens = await response.json();

        return tokens;
      };

      return null;
    }}
    />
  );
}

export default App;