Build advanced token security in a JavaScript single-page app

Due to the fact that pieces of our system will be running on different origins (scheme, domain, and port), we need to configure CORS in the server to allow our web app to make requests. Use the following values:

Rather than domain aliases and self-signed certificates, we will use localhost as that is a trusted domain by default. The main application will be on the 5173 port, and the proxy will be on the 5175 port. Because the proxy also make calls to the PingAM server, its origin must also be allowed.

For more information about CORS configuration, refer to the following:

Within the server, create two OAuth 2.0 clients: one for the React web app and one for the Node.js resource server.

Why two? It’s conventional to have one OAuth 2.0 client per app in the system. For this case, a public OAuth 2.0 client for the React app provides our app with OAuth 2.0 or OIDC tokens. The Node.js server validates the user’s Access Token shared via the React app using its own confidential OAuth 2.0 client.

Create a test user, or identity, in your server within the realm you will be using.

Select the environment you are using for instructions on how to create a demo user:

First, clone the forgerock-sample-web-react-ts repo to your local computer, cd (change directory) into the project folder, check out the branch for this guide, and install the needed dependencies:

First, open the .env.example file in the root directory. Copy this file and rename it .env. Add your relevant values to this new file as it provides all the important configuration settings to your applications.

Here’s a hypothetical example .env file:

We are using Vite for our client apps' build system and development server, so by using the VITE_ prefix, Vite automatically includes these environment variables in our source code. Here are descriptions for some of the values:

Next, we’ll need to create a third application, the Token Vault Proxy.

Follow this structure when creating the new directory and its files:

To ease some of the dependency management and script running, add this new "workspace" to our root package.json, and then add a new script to our scripts:

Create a new directory at the root named token-vault-proxy, then create a package.json file:

Now, create the Vite config file:

What does the above do? Good question! Let’s review it:

Now, create the index.html file. This file can be overly simple as all you need is the inclusion of the JavaScript file that will be our proxy:

If you’re not familiar with how Vite works, seeing the .ts extension may look a bit odd in an HTML file but don’t worry. Vite uses this to find entry files, and it rewrites the actual .js reference for us.

Let’s create and configure the Token Vault Proxy according to our needs. First, create the src directory and the index.ts file within it.

The configuration above represents the minimum needed to create the Token Vault Proxy:

With everything set up, build the proxy app and verify it’s being served correctly.

Once the script finishes its initial build and runs the server, you can now check the app and ensure it’s running. Go to http://localhost:5175 in your browser. You should see "Proxy is OK" printed on the screen, and there should be no errors in the Console or Network tab of your browser’s dev tools.

Since the Token Vault Interceptor is a Service Worker, it needs to be bundled separately from your main application code. To do this, write a new Vite config file within the todo-react-app directory/workspace named vite.interceptor.config.ts.

We do not recommend trying to use the same configuration file for both your app and Interceptor.

Now that you have the new Vite config for the Interceptor, import the defineConfig method and pass it the appropriate configuration.

In the above, we provide the Token Vault Interceptor source file as the input, and then explicitly tell Vite to bundle it as an IIFE (Immediately Invoked Function Expression) and save the output to this app’s public directory. This means the Token Vault Interceptor will be available as a static asset at the root of our web server.

It is important to know that bundling it as an IIFE and configuring the output to the public directory is intentional and important. Bundling as an IIFE removes any module system from the file, which is vital to supporting all major browsers within the Service Worker context. Outputting it to the public directory like a static asset is also important. It allows the scope of the Service Worker to also be available at the root.

For more information, refer to Service Worker scopes on MDN.

Let’s create the new Token Vault Interceptor source file that is expected as the entry file to our new Vite config.

Configure your Token Vault Interceptor with the following variables from your .env file.

The above only covers the minimal configuration needed, but it’s enough to get a basic Interceptor started.

Now that we have the dedicated Vite config and the Token Vault Interceptor entry file created, add a dedicated build command to the package.json within the todo-react-app workspace.

It’s worth noting that the Token Vault Interceptor will only be rebuilt at the start of the command and not rebuilt after any change thereafter as there’s no watch command used here for the Token Vault Interceptor itself. Once this portion of code is correctly set up, it should rarely change, so this should be fine.

Your main app will still be rebuilt and "hot-reloading" will take place.

Enter npm run build:interceptor -w todo-react-app to run the new command you just wrote above in the todo-react-app workspace. You can see the resulting interceptor.js built and placed into your public directory.

Since we haven’t implemented the Token Vault Interceptor yet in the main app, we can’t really test it; however, we can at least make sure the file is accessible in the browser as we expect. To do this, run the following command:

After the command starts the server, using your browser, visit http://localhost:5173/interceptor.js.

You should plainly see the fully built JavaScript file. Ensure it does not have any import statements and looks complete. It should contain more code than just the original source file you wrote above.

When we initiate the Token Vault Proxy, it needs a real DOM element to mount to. The easiest way to ensure we have a proper element is to add it to the index.html directly.

First, import the client module and remove the TokenStorage module from the SDK import.

Second, call the client function with the below minimal configuration. This is how we "glue" the three entities together within your main app. This function returns an object that we use to register and instantiate each entity.

Remember, the file reference within the interceptor object needs to point to the built Token Vault Interceptor file, which will be located in the public directory as a static file but served from the root, not the source file itself.

This function ensures the app, Token Vault Interceptor and Token Vault Proxy are appropriately configured.

Now that we’ve initialized and configured the client, we now register the Token Vault Interceptor, the Token Vault Proxy, and the token vault store just under the newly added code from above:

Registering the Token Vault Interceptor is what requests and registers the Service Worker. Calling register.interceptor returns the ServiceWorkerRegistration object that can be used to unregister the Service Worker, as well as other functions, if that’s needed. We won’t be implementing that in this tutorial.

Registering the Token Vault Proxy constructs the iframe component and mounts it do the DOM element passed into the method. It’s important to note that this must be a real, available DOM element, not a Virtual DOM element. This results in the Token Vault Proxy being "registered" as a child frame and, therefore, accessible to your main app.

Calling register.proxy also returns an optional reference to the DOM element of the iframe that can be used to manually destroy the element and the Token Vault Proxy, if needed.

Finally, registering the store provides us with the object that replaces the default token store within the SDK. There are some additional convenience methods on this store object that we’ll take advantage of later in the tutorial.

You will see a few errors in the console, but don’t worry about those at the moment. The next steps will resolve them.

Within the existing SDK configuration, pass the tokenStore object we created in the previous step to the set method to override the SDK’s internal token store.

This configures the SDK to use the Token Vault Store, which is within the Token Vault Proxy, and that it needs to manage the tokens internally.

Currently in our application, we check for the existence of stored tokens to provide a hint if our user is authorized. Now that the main app doesn’t have access to the tokens, we have to ask the Token Vault Proxy if it has tokens.

To do this, replace the SDK method of TokenStorage.get with the Token Vault Proxy has method:

Note that this doesn’t return the tokens as that would violate the security of keeping them in another origin, but the Token Vault Proxy will inform you of their existence. This is enough to hint to our UI that the user is likely authorized.

Make sure your dedicated Vite configuration is correct.

Also, check the actual file output for the interceptor.js file. If the built file has ES Module syntax in it, or it looks incomplete, then it can cause this issue — Service Workers in some browsers, even the latest versions, don’t support the same ES version or features as the main browser context.

Open up your browser’s dev tools and ensure the following:

Make sure you have both origins listed in your CORS configuration.

Additionally, it’s best if you use the Ping SDK template when creating a new CORS config in your server.

If both origins are listed, make sure you have no typos in the allowed methods. The methods like GET and POST are case-sensitive. Also, check the headers, which are NOT case-sensitive.

Allow Credentials must be enabled.