Node.js Authentication

Security starts with identity. You claim you’re Alice, but the Virtru SDK doesn’t know that. We can’t protect or access data without an identity that’s responsible for protecting or accessing that data. Otherwise, no one (or anyone) would be able to do whatever they want with your data. But we all have sensitive data to protect.

So how do you prove your identity to the Virtru SDK? We’re glad you asked, “Alice…”

Here are your options on the server-side:

  • Use an appId Token from the Virtru Control Center
  • Provision HMAC Token & Secret Pairs

appId Token

Generate an appId from the Virtru Control Center. If you need help, see detailed steps.

Key points about appId authentication:

  • appIds expire in 120 days
  • appIds are tied to your email address (i.e. your login to Virtru Control Center)
  • appIds cannot be used to encrypt or decrypt data on behalf of your app’s end users

For safekeeping, don’t hard code your appID anywhere. A more secure option is to store it in your local environment:

export VIRTRU_SDK_EMAIL=[paste from Virtru Control Center]
export VIRTRU_SDK_APP_ID=[paste from Virtru Control Center]

A combination of email & appId can be used to create a Virtru client and make all other SDK calls:

// Authentication by AppId Token
const Virtru = require("virtru-sdk");

// Set the environment variables:
//   VIRTRU_SDK_APP_ID: AppId Token from https://secure.virtru.com/dashboard#/settings
//   VIRTRU_SDK_EMAIL: Email address used for https://secure.virtru.com/dashboard#/profile
// Please note, the identity used will be associated with any policies created.

try {
  const email = process.env.VIRTRU_SDK_EMAIL;
  const appId = process.env.VIRTRU_SDK_APP_ID;
  if (!email || !appId) {
    console.error(
      "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID"
    );
    return;
  }
  const client = new Virtru.Client({ email, appId });
  console.log("Ready to protect!");
} catch (error) {
  console.error(error);
  process.exit(1);
}

HMAC Token & Secret Pairs

HMAC authentication is a long-lived alternative to appIds.

Key points about HMAC authentication:

  • HMAC does not expire
  • HMAC is tied to your domain
  • HMAC can only be used to encrypt or decrypt data on behalf of your domain’s users

Thus, Virtru must provision an HMAC token & secret pair. Contact Virtru for HMAC provisioning.

If you provision an HMAC token & secret pair for example.com, [email protected] can use your server-side app to encrypt his data and control who has access. A different domain, such as [email protected] will not be able to encrypt or decrypt data with your server-side app. Emails in other domains would need to use a client-side app or Secure Reader to access the same data.

For safekeeping, don’t hard code your HMAC token & secret pair anywhere. A more secure option would be to store them in your local environment:

export VIRTRU_SDK_EMAIL=[paste from Virtru Control Center]
export VIRTRU_SDK_HMAC_TOKEN=[paste from Virtru provisioning email]
export VIRTRU_SDK_HMAC_APP_SECRET=[paste from Virtru provisioning email]

The HMAC token & secret pair can be used to create a Virtru client and make all other SDK calls:

// Authentication by HMAC Token & Secret
const Virtru = require("virtru-sdk");

// Set the environment variables:
//   VIRTRU_SDK_HMAC_TOKEN:
//       A generated ID for your organization's applications and services
//   VIRTRU_SDK_HMAC_APP_SECRET:
//       The corresponding secret
//   VIRTRU_SDK_EMAIL:
//       Email address to be associated with any policies. User must be a
//       member of the organization associated with the above token pair.

const email = process.env.VIRTRU_SDK_EMAIL;
const hmacToken = process.env.VIRTRU_SDK_HMAC_TOKEN;
const hmacSecret = process.env.VIRTRU_SDK_HMAC_APP_SECRET;

if (!email || !hmacToken || !hmacSecret) {
  console.error(
    "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_HMAC_TOKEN\n- VIRTRU_SDK_HMAC_APP_SECRET"
  );
  process.exit(1);
}

const client = new Virtru.Client({ email, hmacToken, hmacSecret });
if (!client) {
  console.error("Virtru client failed to initialize");
  process.exit(1);
}

console.log("Ready to protect!");


Did this page help you?