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.

Components

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.

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.

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 always be in the same site.

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 you may prefer 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.

Token Handler Deployment Scenarios

Hosting for token handler components 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.

Separated Web and API Domains

The most separated deployment for token handler components is to host them on an API domain that is fully independent from your static web content host. For example, if you use a cloud native platform for your API architecture you will already be familiar with API gateway deployments. You should find the work to deploy your SPA and token handler components quite straightforward, with these steps:

• Build the OAuth Agent into a container and configure it to point to your authorization server
• Deploy an OAuth Proxy plugin with your reverse proxy and configure your API routes to use it
• Deploy web static content to a content delivery network (CDN)

In this architecture, the SPA will make occasional lightweight CORS pre-flight requests when calling APIs. The token handler will then call the authorization 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.

Single Web Domain

Alternatively, you can host the web static content in the same domain as token handler components. For example, you can use a reverse proxy with paths similar to those listed below. This is a common form of the Backend for Frontend pattern, though it requires servers or containers to host your web static content. It can be a good choice if you expect to implement more complex code in the web host, or if you have concerns about the overhead of CORS pre-flight requests in a multi-domain setup.

Serverless

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 authorization server
• Configure and deploy a lambda based OAuth Proxy to run within the cloud API Gateway

The OAuth Agent lambdas will then need to call the authorization 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 during web requests, and you can potentially use them to perform token handler work before routing to APIs. This 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 authorization server
• Configure and deploy a worker based OAuth Proxy to run within the CDN before routing to APIs

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

One of your most important deployments will be the setup on development computers. A productive setup will improve the speed at which future work is delivered. When working on an SPA, developers need to serve web static content locally, and the SPA also needs to be issued with secure cookies. An initial investment in deployment is needed when getting started with the token handler pattern. See the Token Handler Development Setup for some recommendations.

Multiple SPAs

When deploying multiple SPAs, you can either isolate or share cookies, depending on your use case.

Cookie Isolation

Each SPA should call APIs using cookies whose underlying access tokens represent access to a business area. You enable this using OAuth Scopes. When multiple SPAs have different business permissions, they should use distinct scopes and you must ensure that each SPA cannot send another SPA's cookies. To ensure this, use distinct web origins and backend for frontend domains for each SPA. Doing so isolates both API privileges and cross-site scripting threats.

An example is shown below, where SPA 2 uses a web origin of https://www.brand2.com so can send cookies to https://api.brand2.com. Other SPAs cannot use these cookies, since they run on independent domains. When required, users can easily navigate across SPAs using Single Sign-On.

Cookie Sharing

Another option is to split a large SPA for code size reasons. This might result in multiple micro-frontends that can be developed by independent developers. In such cases, you can deploy multiple SPAs to the same web domain using paths. Each SPA can then seamlessly share the same OAuth Agent cookies.

Conclusion

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.

The Curity Identity Server comes with an built-in OAuth Agent and Curity provide a number of OAuth Proxy implementations that you can plug in, if required. See the Token Handler Page for details. The Token Handler Deployment Example explains the URL and configuration details, which can then be adapted to other deployment use cases.

This article has been updated on: 2024-06-13Published: 2024-06-13

Gary Archer

Product Marketing Engineer at Curity