Token Handler Deployment Patterns

Token Handler Deployment Patterns

Using the Token Handler Pattern provides an optimal Single Page Application (SPA) architecture, as described in the Overview article. The separation of concerns leads to the simplest application code and the design can then be scaled across multiple SPAs and APIs. It does however add deployment complexity, so companies will need to design a solution based on their platform.


The token handler pattern uses two new components that need to be deployed to serve the SPA, called an OAuth Agent and an OAuth Proxy. A logical representation is shown below, and in this article we will describe some different ways in which the setup can be made more concrete.

Token Handler

OAuth Agent

The OAuth Agent is used to perform OpenID Connect related work on behalf of the SPA. It is only called occasionally, when the SPA needs to perform operations such as authenticating the user or asking the backend for user info. It is best implemented as an API, since its behavior may need to be customised as new OpenID Connect options become available.

OAuth Proxy

Meanwhile the OAuth Proxy executes on every request from the SPA to API, so needs to perform well and avoid additional HTTP requests. It is best implemented in a reverse proxy that can efficiently deal with cookie based concerns, then routing requests with JWT access tokens to APIs. Once deployed and reliable, this component should not need to change.

API Flow

URL Design

The critical requirement when using the token handler pattern is to ensure that the browser always receives first-party cookies. This is done by ensuring that the SPA's web origin and the API endpoints for token handler components share the same parent domain. Calls from the SPA to the OAuth Agent, and to APIs via the OAuth Proxy, will most commonly be both SameSite and Cross Origin.

Web Content Delivery

When using the token handler pattern your web backend will be simply static content, therefore it should not require container or server based hosting, though of course this is still possible. Instead it is often preferred to use a cloud Content Delivery Network (CDN) to push resources such as images and Javascript bundles to many global locations, to ensure good web performance across the globe.

API Scenarios

Hosting for microservices is less clear-cut, since there are many possible API architectures. The token handler pattern can potentially work with any of these, so we will look at some popular options in this section.

Cloud Native

Cloud native platforms such as Kubernetes typically provide a back end with the most advanced capabilities, but require more work related to deployment and availability. Application components are deployed via Docker containers, to run in a cluster, e.g, using Kubernetes, and can then be hosted on multiple cloud platforms.

Companies using cloud native are also likely to use existing cloud native reverse proxies or gateways hosted in front of APIs. This means the work to deploy token handler components is fairly straightforward and involves only these steps:

  • Build an OAuth Agent API into a Docker Container and configure it to point to your Identity Server
  • Deploy an OAuth Proxy plugin with your reverse proxy and configure your API routes to use it

Cloud Native Flow

In this architecture, the token handler can call the Identity Server with high performance inside the cluster. This also means you may be able to avoid exposing certain OAuth endpoints to the internet, to reduce the security attack surface.


Some companies prefer Serverless technology for APIs, due to the reduced infratructure management. Since the OAuth Agent is just a utility stateless API, with no need for back end storage, a lambda implementation is a good fit. Meanwhile the OAuth Proxy can run as a plugin within the Cloud API Gateway. Deployment steps are now slightly different:

  • Configure and deploy a lambda based OAuth Agent API that points to your Identity Server
  • Configure and deploy a lambda based OAuth Proxy to run within the cloud API Gateway

Serverless Flow

The OAuth Agent lambdas will then need to call the Identity Server, which could be managed in various ways, e.g., via internet endpoints, or via a cloud private network. Not all cloud API gateways have mature support for plugins, but if you ever run into blocking issues you can usually switch to a more specialist option via a cloud managed service, e.g, NGINX Plus.

CDN Based Routing

Some cloud platforms provide CDNs with the ability to run some kind of lambda or worker, and you can potentially route to APIs in this manner. One benefit of this is that there is no need for the SPA to issue pre-flight HTTP OPTIONS requests, and it may also be useful for companies who do not yet host a reverse proxy in front of APIs. One possible setup is illustrated below, and involves these deployment steps:

  • Configure and deploy a worker based OAuth Agent that points to your Identity Server
  • Configure and deploy a worker based OAuth Proxy to run within the CDN before routing to APIs

CDN Flow

This might be a convenient option but may not provide the cleanest separation of web and API concerns. One possible issue is that routing to APIs may have restrictions such as short timeouts and small message sizes, so check your CDN provider's capabilities in this area. The OAuth Agent only uses small messages, whereas larger API requests and responses will be routed through the OAuth Proxy.

Web Development Setups

Using the token handler pattern can add complexity to developer setups, due to additional components. Microservice teams will likely already have approaches for running just the component under development. One possible setup for web developers is to point to a deployed token handler, so that they only need to run a web host and browser locally:

Developer Flow

In the diagram, a local web host serves static content on http://localhost:8080 and token handler components to support development are deployed to a dedicated API domain, at To make the SPA use the same site as the deployed API domain, localhost could then be aliased to via the hosts file: localhost
:1        localhost

The SPA could then be run in the browser using The web and API domains are considered in the same site even if ports are different, though the scheme, http or https, must be the same for both.

When deploying SPAs it is vital to ensure that cookies are isolated between applications. The standard way to manage this in any web cookie based architecture is to use different API routes per web app, all of which forward to the actual APIs, which can be hosted anywhere.

When using the token handler pattern, the cleanest option is to use separate API domains or subdomains per app, each with their own OAuth Agent and OAuth Proxy Plugin. One possible setup that provides the required isolation is shown below:

Multiple SPAs

Spinning up new domains or subdomains, such as or, is straightforward when using cloud hosting, but may be more of a challenge when using on-premise hosting. It also works quite well in multi-team setups, where each app's developers should be responsible for the reliability of their own API routes. Adopting the token handler pattern will then have no impact on microservices or the teams who build them.


The token handler pattern is focused on separating web and API concerns for the best architecture. It can be deployed in many setups, as summarized in this article, and the option you choose will depend on your preferred architecture.

Curity provide a number of OAuth Agent and OAuth Proxy implementations that you can plug in, or adapt if required. See the OAuth for Web Home Page for details and links to tutorials. The Token Handler Deployment Example explains the URL and configuration details, which can then be adapted to other deployment use cases.