Token Handler Installation
On this page
The token handler pattern enables single page applications to follow web security best practices. An SPA calls OAuth secured APIs via the token handler, which acts as a Backend for Frontend (BFF) for the SPA. The token handler consists of stateless API components and does not require any backend storage. API requests use HTTP-only cookies and there are no tokens in the browser.
Design Token Handler URLs
The first task is usually to design token handler base URLs, to provide endpoints for SPAs. You should consider both web development URLs and deployed systems.
Same Site Requirement
When designing URLs, make sure the SPA and BFF share the same parent site and use the same scheme (HTTP or HTTPS), so that cookies are same-site and the browser sends them reliably.
Web Development URLs
Start with development base URLs, which might use the following existing values, where a local SPA calls deployed APIs and an authorization server:
| Component | Base URL | Runs Locally? |
|---|---|---|
| SPA | http://localhost:3000 | Yes |
| API | https://api.example.com | No |
| Authorization Server | https://login.example.com | No |
To use the token handler pattern there are no changes to the hosting of the APIs or the authorization server. Instead, add a new base URL that runs token handler components. Some example base URLs are summarized below.
| Component | Base URL | Runs Locally? |
|---|---|---|
| SPA | http://www.demoapp.example:3000 | Yes |
| Token Handler | http://api.demoapp.example | No |
| API | https://api.example.com | No |
| Authorization Server | https://login.example.com | No |
It is possible to run a development setup that uses localhost URLs, but a more productive option for web developers is to switch to a domain based URL during development, such as http://www.demoapp.example:3000. Doing so enables web developers to externalize cookie security to a remote token handler.
Deployed URLs
It is usual to deploy the SPA and token handler to multiple stages of a deployment pipeline. The following table shows some example URLs:
| Stage | SPA Base URL | Token Handler Base URL |
|---|---|---|
| Development | http://www.demoapp-dev.example:3000 | http://api.demoapp-dev.example |
| Testing | https://www.demoapp-test.example | https://api.demoapp-test.example |
| Staging | https://www.demoapp-staging.example | https://api.demoapp-staging.example |
| Production | https://www.demoapp.example | https://api.demoapp.example |
Install the Curity Token Handler
Once there is a known token handler base URL, the next deployment step is to deploy the Curity product and use a license file to activate the token handler feature. The installation provides an administration user interface to configure the system and runtime endpoints that implement the security work.
Install the Curity product on any Linux based platform. Choose one of the options from the following sections to get up and running, and follow the links to tutorials to learn more about the installation mechanics for each platform.
The Install using Docker tutorial explains how to deploy the Curity product using Docker. Run the following example commands to set an admin password and quickly install the token handler on Docker on any Windows, macOS or Linux computer.
export PASSWORD='zIf66A9Wz'docker run -it -e PASSWORD=$PASSWORD -p 6749:6749 -p 8443:8443 curity.azurecr.io/curity/idsvr
Run the First Configuration
After deployment, log in to the Admin UI using the username admin and the configured password. The Admin UI URL is https://localhost:6749/admin for a local Docker deployment. It may have a different host name for other deployments. Next, configure and deploy the token handler so that the SPA can make OAuth and API requests. The First Configuration tutorial explains the configuration steps.
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
