Ping SDKs

Prepare for Token Vault

To integrate the Token Vault into your app you need to make some changes to your environment.

Install the Token Vault

Install the Token Vault by using npm:

npm install @forgerock/token-vault

Configure your module bundler

You need to implement the Token Vault Interceptor component as a service worker in your main application.

To maximize cross-browser compatibility, we recommend that the Token Vault Interceptor is unified and down-levelled into a single output file.

To achieve this, you should create a separate bundler configuration dedicated to the Token Vault Interceptor. This configuration should produce a single file without using ES Module syntax. For example, Webpack version 5 and earlier can do this by default.

In addition, the Token Vault Proxy needs to have its own module bundler configuration as it must be separate from your main application.

Configure your web servers

You must serve the Token Vault Proxy from a different origin than your main application, but using the same parent domain.

To achieve this, we recommend that the Token Vault Proxy uses a dedicated web server. Your main application can then embed the Token Vault Proxy within an iframe to implement origin isolation for your tokens.

If you are testing locally, you can use different port numbers to ensure the origins differ.

In addition, you must configure the web server for the main application to avoid rewriting incoming URLs. The redirections back to your app from the authorization server contain query parameters that must be preserved and read by the SDK.

URL rewriting can cause timeout issues related to /authorize requests. For example, even though it succeeds and redirects back to your app with the code and state query parameters, the request to /access_token is not made. This can be caused by your web server rewriting the URL after receipt to only / and stripping the query parameters. This can cause the OAuth 2.0 flow to fail to resolve correctly leading to failures.

Structure your codebase

To help you integrate the Token Vault into your apps successfully, we recommend a codebase structure such as the following, which uses the Vite development environment:

root
├── .env (1)
├── package.json (2)
├── app/ (3)
|   ├── public/
|   |   └── <static files>
|   ├── src/
|   |   ├── main.js
|   |   └── <app files>
|   ├── interceptor/ (4)
|   |   └── interceptor.js
|   ├── index.html
|   ├── package.json
|   ├── vite.config.js (5)
|   └── vite.interceptor.config.js (6)
└── proxy/ (7)
    ├── src/
    |   └── proxy.js
    ├── index.html
    ├── package.json
    └── vite.config.js (8)
1 You could store shared configuration properties in an .env file
2 You could use npm workspaces
3 Main app folder
4 Separate Token Vault Interceptor code from your main app code
5 Vite configuration file to build your main app
6 Dedicated Vite configuration file to build the Token Vault Interceptor
7 Separate folder for the Token Vault Proxy
8 Separate Vite configuration to build the Token Vault Proxy

The structure of some of these files might resemble the following:

  • index.html

  • main.js

  • interceptor.js

  • proxy.js

<!DOCTYPE html>
<html lang="en">
  <head></head>

  <body>
    <!-- Root div for mounting app -->
    <div id="root"></div>

    <!-- Root div for mounting Token Vault Proxy (iframe) -->
    <div id="token-vault"></div>

    <!-- Import main app -->
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
import { Config, TokenManager } from '@forgerock/javascript-sdk';
import { client } from '@forgerock/token-vault';

const register = client({ /* global config */ });

register.interceptor();
register.proxy(document.getElementById('token-vault'));

const tokenVaultStore = register.store();

Config.set({ /* {sdk_name} config */});
import { interceptor } from '@forgerock/token-vault';

interceptor({ /* config */ });
import { proxy } from '@forgerock/token-vault';

proxy({ /* config */ });

Next steps

When you have set up your project, you can proceed to Implement Token Vault code.