Quick Start: Client-side JavaScript

The Virtru JavaScript SDK allows you to protect your application's content in both browser and server-side contexts. In this guide, we'll walk through a sample webapp that demonstrates encrypting and downloading a file using the SDK in the browser.

Step 1: Save the Sample App as an HTML File

Copy the following HTML snippet into your favorite editor and save as .html (e.g., virtru-sdk-js.html).

<!DOCTYPE html>
<html>
<head>
    <title>Virtru SDK for JavaScript - Sample Application</title>
    <link href="https://sdk.virtru.com/js/latest/auth-widget/index.css" rel="stylesheet"/>
    <script src="https://sdk.virtru.com/js/latest/auth-widget/index.js"></script>
    <script src="https://sdk.virtru.com/js/1.6.11/virtru-sdk.min.js"></script>
</head>

<body>
  <div id="virtru-auth-widget-mount"></div>
  <script type="text/javascript">
    async function afterAuth(email) {
      // Run all client code from here. 
      // This will only be called when the user is successfully authenticated.
      const client = new Virtru.Client({email});
      const yourString = prompt('Type a string to encrypt: ', 'Hello, world!');
      const encryptParams = new Virtru.EncryptParamsBuilder()
        .withStringSource(yourString)
        .withDisplayFilename('hello.txt')
        .build();
      const ct = await client.encrypt(encryptParams);
      await ct.toFile('hello.html');
    }
    // Set up the auth widget.
    Virtru.AuthWidget('virtru-auth-widget-mount', {afterAuth});
  </script>
</body>
</html>

Step 2: Run the Sample App

Because the Virtru JavaScript SDK respects strong security practices like CORS, you’ll need to run a basic web server for your first app. Running JavaScript in a local HTML file will not work.

We recommend Parcel as a convenient method to spin up a server:

npm -g install parcel
parcel --https virtru-sdk-js.html

# Or you can run parcel without installing it globally:
# npx parcel --https virtru-sdk-js.html

Open the URL Parcel suggests.

A TDF-encrypted file named hello.html will be downloaded automatically after running through the authentication wizard and entering a string to encrypt. Open this file anytime and anywhere to securely authenticate, decrypt, and read your content!

UI after successfully authenticating with the Auth Widget

UI after successfully authenticating with the Auth Widget

UI after decrypting the sample file

UI after decrypting the sample file

Step 3: Start Integrating Into Your App

Now you can use the Virtru JS SDK in your pages to protect content. See our JavaScript Sample Apps and the following pages for details on implementing encryption, decryption, and access control.

Let's Break it Down

Let's take a bottom-up look at how the Virtru SDK is integrated into this webapp.

const encryptParams = new Virtru.EncryptParamsBuilder()
  .withStringSource(yourString)
  .withDisplayFilename('hello.txt')
  .build();
const ct = await client.encrypt(encryptParams);

Encryption is a core operation of the SDK, so we'll look at this section first. Here we specify the content to encrypt using withStringSource(), and then we execute the encrypt() using the SDK client.

We also set the filename to display in Secure Reader using withDisplayFilename(). This optional configuration is solely to give Secure Reader a readable name to display and ensure the decrypted content is rendered in-browser as plaintext (using .txt).

await ct.toFile('hello.txt.tdf3.html');

In this line we take the returned ciphertext, in TDFCiphertextStream form, and write it out to a local file using the toFile() helper function.

Note that the local filename is independent of the display filename from the previous step. For novice users we recommend an .html suffix so the file can easily opened using the browser.

async function afterAuth(email) {
  const client = new Virtru.Client({email});
  // ...
}
Virtru.AuthWidget('virtru-auth-widget-mount', {afterAuth});

In this section we initialize the auth widget and the SDK client.

First we define a method, afterAuth(), which is called automatically once the user has successfully authenticated. This function initializes the SDK client, for which authentication is a prerequisite in the browser context.

We kick off the webapp by calling Virtru.AuthWidget(), initializing the auth widget with a mount point (DOM id) and the afterAuth() business logic callback. The widget will automatically attach itself and begin running the user through the auth wizard.

<link href="https://sdk.virtru.com/js/latest/auth-widget/index.css" rel="stylesheet"/>
<script src="https://sdk.virtru.com/js/latest/auth-widget/index.js"></script>
<script src="https://sdk.virtru.com/js/1.6.11/virtru-sdk.min.js"></script>

Finally, the SDK and auth widget are included via <script> tags pointed at a Virtru CDN. These scripts can be loaded in any order, but must both be loaded by the time Virtru.AuthWidget() is called.

Enabling Authentication Using Federated Identities

By default, the only supported method of authentication is email code entry. In order to authenticate using federated Google, Outlook, or O365 identities, you must run the webapp on a whitelisted domain.

For production and more advanced use-cases you can submit a whitelist request on the Virtru dashboard to verify and add your domain.

For local development you can use https://local.virtru.com with the following steps.

Step 1: Open Your /etc/hosts File

sudo nano /etc/hosts

Step 2: Add a Loopback Entry for local.virtru.com

##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1       localhost
255.255.255.255 broadcasthost
::1             localhost
127.0.0.1       local.virtru.com  # Local Virtru SDK testing

Run a Local https Server

Try the Parcel instructions above.

Step 3: Navigate to the Webapp in Your Browser

Open your app in the browser and you'll be able to use federated identity auth!

UI of federated authentication options in the Auth Widget

UI of federated authentication options in the Auth Widget

Getting Help

There are many ways to get help:

  • You can join Virtru Developer Hub Community Slack channel to get your questions answered.
  • You can open a support ticket here.

Updated about a month ago


Quick Start: Client-side JavaScript


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.