Build with the Virtru Developer Hub

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

Try the Demo          Learn More     

How to Add Authentication

Remember!

Please be sure to protect your credentials and secrets. Follow best practices. It is your responsibility.

Basics

You can apply encryption and protections by authenticating on either the client-side (browser or mobile), or on the server-side.

  • Client-side authentication is performed using identity federation or an email code loop. Typically this is included via a widget in your website or app, but the SDK also exposes the underlying methods if you'd prefer to roll your own.
  • Server-side authentication is performed using credentials provisioned from Virtru. The most common method is to self-serve generate a temporary appId to construct the SDK client with. Longer-lived hmac credentials can be provisioned by contacting Virtru directly.

These authentication schemes are mutually exclusive, Virtru credential usage is disallowed in the browser and federated identity and email code usage are disallowed when not in a browser context.

The following is a deeper dive on each authentication scheme.

Browser-based Auth

  1. Auth Widget. This is the recommended browser-based auth scheme to start with.
  2. Email Code Loop. This is a browser based auth scheme.
  3. Federation using Google and O365. This is a browser based auth scheme.

Server-side Auth

  1. AppId Token Downloaded from Virtru Dashboard. This is a non-browser based auth scheme.
  2. HMAC Token and Secret. This is a server (or trusted) environment auth scheme.

Browser Auth Schemes

These auth schemes are suitable for interactive platforms such as web browsers and mobile apps.

1. Auth Widget

Virtru provides a prepackaged auth widget which subsumes the other browser auth schemes (federated identity and email code). Once included with the SDK, this widget walks the user through authenticating via one of the supported methods and fires off a callback when authentication has been completed successfully.

<!DOCTYPE html>
<html>
<head>
    <title>Virtru SDK for JavaScript - Sample Application</title>
    <!-- Include the widget and SDK with the following three lines. -->
    <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">
    // Define the callback.
    async function afterAuth(email) {
      // Run all SDK code from here now that
      // the user is authenticated.
    }
    // Set up the auth widget.
    Virtru.AuthWidget('virtru-auth-widget-mount', {afterAuth});
  </script>
</body>
</html>

For developers getting started with the Virtru SDK, we strongly recommend starting with the widget to get up and running faster with authentication.

2. Email Code Loop

Email Code Loop authenticates your end users by sending a temporary alphanumeric code to their email address, then asking them to validate it. When the end user authenticates using this strategy, they will be marked as "owners" of the key, and policy on any objects they encrypt. To implement Email Code Loop Auth use the following code:

Email Code Loop Step 1: First ask the end user to enter their email address via a UI control. Let's say they entered alice@example1.com. Now, you can have Virtru send a code to their email address like this:

Virtru.Auth.sendCodeToEmail({ email: 'alice@example.com' })

Email Code Loop Step 2: Now ask the end user to enter the code they received into a text box. Let's say the code they entered from their email is V-12345678. Now execute this:

 Virtru.Auth.activateEmailCode({ email: 'alice@example.com', code: 'V-12345678' });

This validates the user-entered code against Virtru's authentication services. If the entered code was correct, the end user is authenticated with Virtru and a valid AppId token is sent to the browser. This AppId token will be used by Virtru JS SDK for subsequent encryption or decryption operations.

Warning

Be sure to call Virtru.Auth.isLoggedIn() after these steps to verify login was successful.

3. Federation Using Google, O365 and Outlook

Federation flow with Virtru

Federation flow with Virtru

Step 1: End user initiates OAuth authentication (see code below) with Virtru's Federated Identity Service.

Step 2: Virtru's Federated Identity Service receives the authentication request and redirects the end user to authenticate to one of the popular OAuth providers.

Step 3: End user successfully authenticates with OAuth provider of choice and authorizes Virtru to use this identity.

Step 4: OAuth provider redirects the end user back to Virtru's Federated Identity Service. Virtru's Federated Identity Service activates the token that's returned back to end user's browser for subsequent requests to Virtru's Key Management Service. Virtru's Federated Identity Service returns the user to the customer's site, provided the site is whitelisted.

In order to leverage this OAuth-based authentication methods, you must be running on a domain whitelisted by Virtru. By default https://local.virtru.com is whitelisted for development purposes, see here for a detailed walkthrough of setting up your development environment for federated auth.

Register Your Domain with Us

Using this scheme requires that you register your domain with us first. Click here to see instructions on how to do that.

Once running on a suitable domain, you can use the Virtru.Auth.login* methods to authenticate from various identity providers. For instance, the following line will attempt to authenticate a user with their Google account.

Virtru.Auth.loginWithGoogle({email: 'alice@example.com'});

Server Side Auth Schemes

1. AppId Token Downloaded

Need to Download an AppId Token?

Click here to see how you can self-service download an AppId Token

This is a simple yet powerful auth scheme that is meant for you (the developer) to get going with Virtru SDKs immediately. Just download the AppId Token to start using Virtru SDKs. No need to configure anything. While this scheme is perfect for getting started quickly, please note that the downloaded AppId Token:

  • Expires in 360 days.
  • Is tied to your (the developer's) identity and cannot be used to encrypt/decrypt objects on behalf of your app's end users.
  • Will not work in the browser, but is well suited to use in CLI apps or server-side apps.
// Simply paste the AppId Token downloaded from Virtru Dashboard.
// Please note, the identity is tied to the identity that downloaded the AppId Token (dev_email@example.com)

const clientDev = new Virtru.Client({ email: 'dev_email@example.com', appId: '12345678-1234-1234-1234-123456789012' });
                                      
// the `clientDev` can now be used to encrypt/decrypt data.
from virtru_tdf3_python import Client

# Simply paste the AppId Token downloaded from Virtru Dashboard.
# Please note, the identity is tied to the identity that downloaded the AppId Token (dev_email@example.com)
clientDev = Client(owner = "dev_email@example.com",
                     app_id = "12345678-1234-1234-1234-123456789012")

# the `clientDev` can now be used to encrypt/decrypt data.
#include <virtru_client.h>

// Simply paste the AppId Token downloaded from Virtru Dashboard.
// Please note, the identity is tied to the identity that downloaded the AppId Token (dev_email@example.com)

Client clientDev {"dev_email@example.com", "12345678-1234-1234-1234-123456789012"};

# the `clientDev` can now be used to encrypt/decrypt data.

Handling Credentials

Although in this and the following example we include a hardcoded appId for clarity, in general we strongly recommend against checking in code with credentials. Instead, consider storing the key securely on your local filesystem as in this example.

2. HMAC Token And Secret

These are long-lived credentials intended for a service account authentication. These credentials are scoped to your domain. That is, credentials issued to your domain can be only used to encrypt/decrypt files on behalf of users in your domain. For example, if you own the domain example.com, then with these credentials you encrypt a file on behalf of any user in the domain.

Consider the scenario where you have a server side application to which bob@example.com logs in. Your server is configured with example.com's HMAC Token and Secret. With these credentials, you can encrypt a file on behalf of bob@example.com. This will mark bob@example.com as "owner" of the key and policy.

Next, if alice@example.com logs into the same application, the same HMAC Token and Secret will be used to encrypt a file on behalf of alice@example.com.

// This example shows authentication with HMAC Token/Secret sent by your Virtru Rep 

// You can get your org's HMAC token/secret by contacting your Virtru Rep.
const token = "12345678-1234-1234-1234-123456789012@tokens.virtru.com"
const secret = "somesecret=="
const clientAlice = new Virtru.Client({ email:"alice@example1.com", hmacToken: token, hmacSecret: secret });

// the `clientAlice` can now be used to encrypt/decrypt data on behalf of 'alice@example1.com'.
from virtru_tdf3_python import Client

# authenticate and create a client for 'alice@example1.com'.
# You can get your org's HMAC token/secret by contacting your Virtru Rep.
clientAlice = Client(owner="alice@example1.com",
                api_key="12345678-1234-1234-1234-123456789012@tokens.virtru.com",
                secret="someSecret==")
# the `clientAlice` can now be used to encrypt/decrypt data on behalf of 'alice@example1.com'.
#include <virtru_client.h>

// Create an instance of Virtru client.
// You can get your org's HMAC token/secret by contacting your Virtru Rep.
Client clientAlice {"alice@example1.com", // Owner
               "12345678-1234-1234-1234-123456789012@tokens.virtru.com", // token
               "someSecret=="}; // secret

// the `clientAlice` can now be used to encrypt/decrypt data on behalf of 'alice@example1.com'

Provisioning HMAC credentials

HMAC credentials cannot be generated self-service as appIds are. Instead, please contact Virtru for information on provisioning.

How to Add Authentication


Suggested Edits are limited on API Reference Pages

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