Build with the Virtru Developer Hub

It's Your Data. Protect It. Control It. Everywhere.

Try the Demo          Learn More     

Getting Started: JS - Browser

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.

For more detailed information, please see the comprehensive SDK documentation.

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., sample.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/latest/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

Open the sample HTML file to run it in a browser. 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!

Step 3: Start Integrating Into Your App

Now you can use the Virtru JS SDK in your pages to protect content. See our JavaScript Demo Applications and how-to guides 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.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/latest/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

Step 3: Run a Local https Server

There are myriad ways to do this but here's a simple example with npm's http-server.

npm install http-server -g

# create a directory to serve files from
mkdir sample
mv sample.html sample/index.html

# generate a self-signed cert and keypair for local testing
openssl req  -nodes -new -x509  -keyout key.pem -out cert.pem

# run the server
http-server sample/ --ssl

Step 4: Navigate to the Webapp in Your Browser

Navigate to https://local.virtru.com:8080 and you'll be able to use federated identity auth!

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.

Getting Started: JS - Browser


Suggested Edits are limited on API Reference Pages

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