DEPRECATED

This browser proxy library is deprecated in favor of new Keycloak OIDC flows - current TDF SDKs/KAS do not use this. Things that depend on this library should either be updated to use that flow or are themselves deprecated.

Virtru SDK Proxy ·

What is this?

The Virtru SDK Proxy is a forked implementation of XDomain whose purpose is to enable customers of the Virtru SDK to embed the SDK on their own site under any domain. This allows the protection of files as well as appIds being exposed via XSS and other vulnerabilities while

a.) allowing Virtru to maintain Origin restrictions on backend services, and b.) ~allowing the customer to use the SDK without requiring Virtru intervention~ Virtru requires whitelisting of domains c.) allowing all AppIds to be secure behind same-origin policies and replacing them with shared secrets

How does it work?

From a high level, the proxy workflow is as follows:

1. The Virtru SDK initiates a proxy url (proxy.html for Production) that is hosted by Virtru, and hooks all XHR requests to Virtu's servers from the user's domain to use this proxy.
2. The Virtru-hosted proxy.html uses XDomain to create an iframe in the user's browser.
3. The Virtru SDK then makes requests to Virtru servers from any domain using XHR, and that XHR traffic is captured and proxied through the iframe via postMessage.
4. The proxy code behind the iframe processes and forwards these requests to Virtru's backend services.
5. If needed, the proxy also filters or reformats data before sending it back to the Virtru SDK.

Additional Protections

The Virtru SDK uses virtru-client-oauth for both email loop as well as Oauth authentication with Virtru accounts, and as such the utility stores Virtru appIds in browser local storage for easy storage and retrieval.

Due to the insecure nature of a customer hosting their own SDK implementation on an untrusted domain, this appId could be potentially compromised via malicious scripts executing on that domain. This issue is addressed by the proxy as follows:

1. The Virtru SDK hosted from, say, example.com makes an authentication request.
2. Once the account using the SDK is authenticated, the response from Virtru accounts is intercepted via the Virtru-hosted proxy (proxy.html).
3. The proxy, in its own iframe under the sdk.virtru.com domain, creates a random "shared secret" and uses this secret, in conjunction with the example.com domain, as a local storage key and stores the appId in local storage. Only scripts running under the sdk.virtru.com domain would be able to access this appId.
4. The proxy then returns as a response to the SDK (virtru-client-oauth), the "shared secret".
5. The "shared secret" is then stored in the user's local storage under the example.com domain.
6. Further requests to Virtru's backend services are handled by the Virtru SDK via construction of an Authorization header using the "shared secret". This shared secret is extracted via the proxy, and the proxy replaces it with the correct appId. Finally, the proxy forwards this request to the Virtru backend service.

Add client domain to whitelist

To protect the Virtru ecosystem a whitelist has been enabled for the proxy. Follow these steps to add a new client domain:

1. Checkout repo and create a new branch identifying the change (i.e. feature/NOREF-add-mydomain.com
2. Run npm i to install the dependencies
3. Add the client to whitelist-clients.json
4. Run make bump
5. Update the changelog.md bumping the version and identifying the change
6. Create the PR

A good example PR is #25. After your PR is approved merge it in and notify maintainers.

Maintainer Steps

Maintainer will need to go to buildkite and push to production.

Testing

To run tests

npm run test

Local testing

The testserver folder contains an express server that enables local development of the TDF3 JS SDK and proxy.

1. Clone virtru-tdf3-js locally and build it using npm run build:local.
2. Copy the resulting script packaged for the web at dist/virtru-sdk.web.js into this repo at testserver/public
3. In this repo, add demos.developer.virtru.com as a valid request URL by updating the isValidRequestUrl function found in src/lib/virtru.js:

if (currentHostnameEnv === 'demos.developer.virtru.com') {
  return true;
}

4. Build the proxy with npm run build, which should produce proxy.html in the dist folder.
5. Set your /etc/hosts to redirect demos.developer.virtru.com to localhost (127.0.0.1). This URL works because our backend has whitelisted it for CORS.
6. Run node testserver/index.js to start the express server
7. Open the testing file at https://demos.developer.virtru.com/