You're using JWT wrong! Using tokens securely

Web security is a concern that should be everyone’s priority, especially those working on software development projects. For developers, it’s far more worrying to build systems that don’t follow security rules, because any malicious action can escalate very quickly.

If you’ve read my content before, you know I’m a big fan of the RFC7519 standard, the famous JWT. In fact, quite a while ago I wrote an article about how it all works and explaining all the details of implementing that type of token.

The problem is that this implementation is inherently insecure, and I’ll tell you why.

GitHub - khaosdoctor/secure-jwt-tokens: Simple repository to show how to store JWT tokens in a secure waySimple repository to show how to store JWT tokens in a secure way - GitHub - khaosdoctor/secure-jwt-tokens: Simple repository to show how to store JWT tokens in a secure waykhaosdoctor

The problem#

Throughout the entire time JWT tokens have existed, they’ve been targets of various controversies, many of which say that tokens are subject to a specific type of attack called XSS Attack.

If you still don’t know what an XSS attack is, I’ll leave this video I made in partnership with Código Fonte TV

In most applications, when we receive a JWT token from the server, we typically think:

“Where am I going to store this token to avoid having to log the user in every time?” — Pretty much everyone

And, most of the time, LocalStorage is the chosen place. It’s an API that’s extremely simple to use, stores data between sessions and across tabs, so as long as the tab is on the same domain, the browser will store the token and allow it to be used. It’s one of the most efficient ways to do login.

The biggest problem is that it can be easily accessed via JS, so any site with an XSS vulnerability, that is, the ability to execute a malicious script on the domain, will make the token automatically insecure, because anyone can read that token using scripts.

The solutions#

There are a number of solutions to work around this problem. Let’s explore some of them.

Token in memory#

To work around this problem, we can use another technique. Instead of storing the token directly in LocalStorage, we can keep it only in memory, meaning we never store it anywhere. For example:

1
const _token = null
2

3
fetch('/login', {
4
    method: 'POST',
5
    headers: { 'Content-Type': 'application/json' },
6
    body: JSON.stringify({ username: 'usuario', password: 'senha' })
7
})
8
.then(data => data.json())
9
.then(token => { _token = token })

Doing this makes the token virtually invisible to any script since it’s not in the same scope as another script and only lives in memory. Even though it’s still accessible with a memory dump, for that the attacker would need access to the victim’s computer.

However, we have a pretty strong downside. If the user refreshes the page or switches tabs, we won’t have the token saved in that new environment, so we’d need to ask the user to log in every moment, which isn’t excellent UX.

There’s a way to work around this obstacle by using long-duration tokens. We’ll talk about them later.

HttpOnly cookies#

To level up knowledge about cookies, a cookie is a piece of information up to 4kb that’s saved in the browser across tabs as long as they’re on the same domain. It’s another way to persist data even when the user’s session ends, because even if the user closes the browser, the cookies will still be there for future use.

Cookies are often used in those “Remember me” checkboxes during user logins.

The other option here would be to store the access token in a cookie with the httpOnly flag enabled. Cookies with this property are not accessible by JavaScript, only by the browser and requests.

1
const express = require('express');
2
const app = express();
3

4
// middleware setup and so on...
5

6
app.post('/login', (req, res) => {
7
  // performs login...
8
  res.cookie('token', '12345', { maxAge: 5*60*1000, httpOnly: true, sameSite: 'strict' });
9
  res.send('OK')
10
})

By the standard way browsers work, they send back to the server all cookies set by that same domain on every request. So in all subsequent calls to our backend, we would have a cookie with our user token there, and then we could validate through them instead of using an Authorization: Bearer header like it’s common.

The problem is that JWT tokens can store a lot of information and often these tokens exceed the 4kb limit, so it’s a bit risky to use these Cookies to store access tokens. Plus they’re saved on the user’s computer and, although they’re not targets of XSS, they could be victims of another type of attack called Cross Site Request Forgery or CSRF.

CSRF can be mitigated and prevented by using other anti-CSRF tokens, which is a topic for the next article.

A mix of ideas#

There are other possible solutions that I’ll talk about at the end of this article and also explore in more detail in future articles. But what if we used a mix of the two solutions I proposed before?

The idea is that we do user login, we store the access token directly in memory, no one will have access to it. But how do we deal with the question of maintaining logins?

Refresh Tokens#

One of the ways we have to deal with the case of volatile tokens like in-memory storage is the so called refresh tokens. The idea is that an access token is short-lived (at most 15 minutes) while a refresh token has a longer duration (a few hours or days).

A refresh token’s purpose is only to give you a new access token, so it has no internal information, and shouldn’t. That’s why it’s an extremely lightweight token that can be stored in a Cookie.

Basically, if we had a route like this, any valid refresh token could create a new access token:

1
router.post('/refresh', withRefreshAuth, (_, res) => {
2
  const accessToken = createAccessToken(user)
3
  const refreshToken = createRefreshToken(user)
4

5
  setRefreshCookie(res, refreshToken)
6
  res.json({ accessToken })
7
})

Note that we’re also recreating the refresh token to avoid having another endpoint for it. So when we rotate one, we rotate both.

This solution still isn’t ideal because we still have a token that can produce other tokens. The biggest difference is that we can maintain greater control over the access tokens that were created and we can reduce the attack surface by having these tokens with a much shorter duration.

Fingerprinting#

One way we can keep refresh tokens safe is by using what we call fingerprints. They look a lot like CSRF tokens. The idea is to have a unique value that’s generated on the server side and stored as a secure Cookie.

Additionally, the fingerprint is included in the token, so that it can’t be altered without invalidating the token.

When the user makes a request to refresh, the fingerprint will go along with the refresh token. We can then decode the token and check if the fingerprint of the token is the same as the Cookie’s. If for some reason the Cookie’s fingerprint is different from the one in the token, we’ll have invalid access.

Additionally, we can create a hash of our refresh token and store that hash in a temporary database (like Redis) so we can invalidate sessions or compromised tokens as an additional protection measure.

To not make this article too long, I’ll write another one just about how the fingerprinting process was done.

Implementation#

To implement a solution like this, we’ll simulate an app that performs user searches. We’ll have some users in a local database and we’ll use two different tokens to be able to perform authentication. The code for this repository is on my GitHub:

Backend#

We’ll start with the backend. To simulate an application in the browser, I built a small app using only JavaScript and HTML so it’s much easier to see what happens under the hood.

Note: Remember that in this example, I’m intentionally leaving out some best practices for the sake of clarity.

Note 2: I won’t describe the basic files (package.json, tsconfig.json, etc.) You can go to the repository to copy them.

For this application we’ll use some libraries as direct dependencies, so run the install command:

1
npm i cookie-parser dotenv express jsonwebtoken

I installed some development libraries, mainly for using TypeScript:

1
npm i -D @types/cookie-parser @types/node @types/express @types/jsonwebtoken copyfiles rimraf ts-node ts-node-dev typescript

In my package.json I also created some scripts to facilitate development. The file looked like this:

1
{
2
  "name": "jwt",
3
  "version": "0.0.1",
4
  "description": "",
5
  "main": "dist/backend.js",
6
  "scripts": {
7
    "dev": "tsnd src/index.ts",
8
    "build": "rimraf ./dist && tsc && copyfiles -u 1 \"./src/frontend/**/*.*\" ./dist",
9
    "start": "node dist/index.js"
10
  },
11
  "keywords": [],
12
  "author": "Lucas Santos <hello@lsantos.dev> (https://lsantos.dev/)",
13
  "license": "MIT",
14
  "dependencies": {
15
    "cookie-parser": "^1.4.6",
16
    "dotenv": "^16.0.1",
17
    "express": "^4.18.1",
18
    "jsonwebtoken": "^8.5.1"
19
  },
20
  "devDependencies": {
21
    "@types/cookie-parser": "^1.4.3",
22
    "@types/express": "^4.17.13",
23
    "@types/jsonwebtoken": "^8.5.8",
24
    "@types/node": "^18.7.3",
25
    "copyfiles": "^2.4.1",
26
    "rimraf": "^3.0.2",
27
    "ts-node": "^10.9.1",
28
    "ts-node-dev": "^2.0.0",
29
    "typescript": "^4.7.4"
30
  }
31
}

Skipping the basic app creation, we’ll create a src folder and inside it we’ll start creating our user database:

1
export type User = {
2
  username: string
3
  name: string
4
  age: number
5
  social: string
6
  password: string
7
}
8

9
export const users: User[] = [
10
  {
11
    name: 'Lucas Santos',
12
    age: 27,
13
    social: 'twitter.lsantos.dev',
14
    username: 'lsantosdev',
15
    password: '123456'
16
  },
17
  {
18
    name: 'Rosa Barnett',
19
    age: 33,
20
    social: 'http://ko.st/wa',
21
    username: 'rosabarnett',
22
    password: '123456'
23
  },
24
  {
25
    name: 'Russell Spencer',
26
    age: 66,
27
    social: 'http://egki.tp/ecbu',
28
    username: 'russellspencer',
29
    password: '123456'
30
  }
31
]

Now, we’ll create our entry point for our application, which will be the index.ts file. We’ll start by importing everything we need to use and defining global middlewares:

We’ll use cookie-parser to be able to parse the Cookie headers that the browser will send back to us, otherwise we won’t have the req.cookies key
To parse the request body (for the login route), I’m using express.json()

1
import path from 'path'
2
import dotenv from 'dotenv'
3
import express from 'express'
4
import cookieParser from 'cookie-parser'
5

6
dotenv.config()
7

8
const app = express()
9
app.use(express.json())
10
app.use(cookieParser())

First we’ll load our variables from our .env file which should be at the root of our application and has the following content:

1
ACCESS_TOKEN_SECRET=secret_access_token
2
REFRESH_TOKEN_SECRET=secret_refresh_token
3
ACCESS_TOKEN_DURATION_MINUTES=5
4
REFRESH_TOKEN_DURATION_MINUTES=120

This file is also in the repository, but remember that it’s not a best practice to send environment variables to a public repository. Additionally, the secrets for each token should be much more secure than the ones I put here.

To make it easier to understand, I’ll separate the handlers for each route into another file called handlers.ts, which we’ll create later, but we can already import it here too:

1
import path from 'path'
2
import dotenv from 'dotenv'
3
import express from 'express'
4
import cookieParser from 'cookie-parser'
5

6
import { apiRoutes } from './handlers'
7

8
dotenv.config()
9

10
const app = express()
11
app.use(express.json())
12
app.use(cookieParser())

Our frontend needs to be on the same domain as our application, so I’ll use express itself to serve the HTML files through express.static(). We’ll put the entire site behind a /site path to separate it from the API:

1
// Previous code
2

3
app.use('/site',
4
  express.static(
5
      path.resolve(__dirname, './frontend'),
6
      { cacheControl: false }
7
  )
8
)

Then we’ll use a Router to bring in our API routes:

1
app.use('/api', apiRoutes)

And finally we’ll listen on port 3000:

1
app.listen(3000, () => console.log('JWT example listening on port 3000!'))

Now we’ll create a new file called handlers.ts where we’ll create all our logic. First, we’ll import the functions we’re going to use:

1
import { createHmac } from 'crypto'
2
import {
3
  NextFunction,
4
  Request,
5
  RequestHandler,
6
  Response,
7
  Router
8
} from 'express'
9
import jwt, { JwtPayload } from 'jsonwebtoken'
10
import { User, users } from './users'

Then, if you’re using TypeScript, we’ll extend two interfaces. The first one will be Express’s own Response so we can add typing to the res.locals object, which is an object where we can include any information to pass to the next middlewares.

In our case, we’ll have an object that will contain our user (which is already typed in our “database”) and the hash of our refresh token:

1
interface ExtendedResponse extends Response<any, { user: Partial<User>; refreshHash: string }> {}

We’ll create another type that will be the payload of our token, which is the entire user object excluding the password and username (which is in the sub key):

1
interface AccessTokenPayload extends JwtPayload, Omit<User, 'username' | 'password'> {}

Additionally, we’ll simulate a sessions database using a Map, where we’ll store our refresh tokens along with which user they belong to:

1
const refreshTokenDB = new Map<string, string>()

Finally, we’ll create our router to start creating the routes:

1
const router = Router()

Our API will have 3 routes. The first will be the login route, which will be completely open. The idea of this route is that we receive the user and password in the request body, check if the user exists in the database. If so, we’ll generate an access token and a refresh token for that user, set the necessary cookies, and return the access token directly in the response body so it can be saved by the front-end.

1
router.post('/login', (req, res: ExtendedResponse) => {
2
  const { username, password } = req.body
3
  const user = users.find((user) => user.username === username && user.password === password)
4
  if (!user) return res.status(401).send('Unauthorized')
5

6
  const accessToken = createAccessToken(user)
7
  const refreshToken = createRefreshToken(user)
8

9
  setRefreshCookie(res, refreshToken)
10
  res.json({ accessToken })
11
})

I’m using some helper functions to create the tokens. We’ll create them, starting with the token creation functions.

Creating the access token is quite simple. We just sign a new jwt with all the user’s data (except the password) and make it last only 5 minutes:

1
const createAccessToken = (user: User) => {
2
  return jwt.sign(
3
    { sub: user.username, name: user.name, age: user.age, social: user.social },
4
    process.env.ACCESS_TOKEN_SECRET!,
5
    {
6
      audience: 'urn:jwt:type:access',
7
      issuer: 'urn:system:token-issuer:type:access',
8
      expiresIn: `${process.env.ACCESS_TOKEN_DURATION_MINUTES}m`
9
    }
10
  )
11
}

Notice that I’m using audience and issuer with URNs. This is a best practice to identify who’s generating the token and who it’s destined for.

The refresh token is a bit more complicated because we have to add it to our database and create a timeout to expire this token. In databases like Redis, this type of function (called TTL) is already implemented by default.

First we’ll create a signed token. The token’s sub will be the user’s username. The token type is defined in the audience and it lasts 120 minutes:

1
const createRefreshToken = (user: User) => {
2
  const token = jwt.sign({ sub: user.username }, process.env.ACCESS_TOKEN_SECRET!, {
3
    audience: 'urn:jwt:type:refresh',
4
    issuer: 'urn:system:token-issuer:type:refresh',
5
    expiresIn: `${process.env.REFRESH_TOKEN_DURATION_MINUTES}m`
6
  })
7
}

Then we’ll create a hash of our token to save to the database, save the session and create the timeout. After that, we’ll return the token:

1
const createRefreshToken = (user: User) => {
2
  const token = jwt.sign({ sub: user.username }, process.env.ACCESS_TOKEN_SECRET!, {
3
    audience: 'urn:jwt:type:refresh',
4
    issuer: 'urn:system:token-issuer:type:refresh',
5
    expiresIn: `${process.env.REFRESH_TOKEN_DURATION_MINUTES}m`
6
  })
7
  const tokenHash = createHmac('sha512', process.env.REFRESH_TOKEN_SECRET!).update(token).digest('hex')
8

9
  refreshTokenDB.set(tokenHash, user.username)
10
  setTimeout(() => {
11
    refreshTokenDB.delete(tokenHash)
12
    console.log(`Refresh token ${tokenHash} expired`)
13
    console.table(refreshTokenDB.entries())
14
  }, 5 * 60 * 1000)
15

16
  console.table(refreshTokenDB.entries())
17
  return token
18
}

Another function I’m using a lot is a utility just to avoid code repetition for creating cookies. It just creates the Cookie securely:

1
const setRefreshCookie = (res: ExtendedResponse, token: string) => {
2
  res.cookie('refresh-token', token, {
3
    httpOnly: true,
4
    secure: true,
5
    sameSite: 'strict',
6
    expires: new Date(Date.now() + Number(process.env.REFRESH_TOKEN_DURATION_MINUTES) * 60 * 1000)
7
  })
8
}

To make it easier, I’ll describe the objects we’re using to configure the cookies:

httpOnly: Prevents the token from being accessible by JS
secure: Prevents the use of the cookie outside HTTPS environments
sameSite: Cookies can only be used on the same domain
expires: Token expiration date

Refresh#

The next route we need to create is the refresh route, which will receive the cookie with the refresh token and perform the logic to create a new access token. But this route can only be accessible if the refresh token is present, so for that I’ll create an authentication middleware.

The idea of this middleware is that we first get the Cookie from inside the request and check if it exists. If not, we’ll return an error:

1
const withRefreshAuth = (req: Request, res: ExtendedResponse, next: NextFunction) => {
2
  const token = req.cookies['refresh-token']
3
  if (!token) return res.status(401).send('Unauthorized')
4
}

After that, we’ll see if the token is valid. To do this, we’ll use the jwt.verify function which, at the same time, validates and decodes the token. If the process was successful, we should fall into our try. If not, we’ll return an invalid token error. Notice that I’m passing the audience to the verifier so it can also attest to the validity of this token:

1
const withRefreshAuth = (req: Request, res: ExtendedResponse, next: NextFunction) => {
2
  const token = req.cookies['refresh-token']
3
  if (!token) return res.status(401).send('Unauthorized')
4
  try {
5
    jwt.verify(token, process.env.ACCESS_TOKEN_SECRET!, {
6
      audience: 'urn:jwt:type:refresh'
7
    })
8
  } catch (error) {
9
    return res.status(401).send('Unauthorized')
10
  }
11
}

Inside our success block, we’ll then generate a hash of this token and include it inside res.locals:

1
const withRefreshAuth = (req: Request, res: ExtendedResponse, next: NextFunction) => {
2
  const token = req.cookies['refresh-token']
3
  if (!token) return res.status(401).send('Unauthorized')
4
  try {
5
    jwt.verify(token, process.env.ACCESS_TOKEN_SECRET!, {
6
      audience: 'urn:jwt:type:refresh'
7
    })
8
    const tokenHash = createHmac('sha512', process.env.REFRESH_TOKEN_SECRET!).update(token).digest('hex')
9
    res.locals.refreshHash = tokenHash
10
    next()
11
  } catch (error) {
12
    return res.status(401).send('Unauthorized')
13
  }
14
}

Now we can create our route with the authentication middleware:

1
router.post('/refresh', withRefreshAuth, (_, res) => {})

The idea of the route is simple. We’ll do the following steps:

We’ve already validated the token, so we need to check if it exists in our database
If it does, we’ll find the user it’s related to
We generate a new access token and a new refresh token
We send the refresh token via cookie and return the access token

The final code looks like this:

1
router.post('/refresh', withRefreshAuth, (_, res) => {
2
  const username = refreshTokenDB.get(res.locals.refreshHash)
3
  const user = users.find((user) => user.username === username)
4
  if (!username || !user) return res.status(403).send('Could not find user for this refresh token')
5

6
  const accessToken = createAccessToken(user)
7
  const refreshToken = createRefreshToken(user)
8

9
  setRefreshCookie(res, refreshToken)
10
  res.json({ accessToken })
11
})

A protected route#

Now we’ll create our user route, the route that will be protected by our JWT token. It will return one of our users from the database, but it needs to be protected by the access token (not the refresh one). We’ll create another middleware for it.

The idea is even simpler. We just need to get the token from inside the Authorization header and, if it’s valid, we can decode it and create a user object inside res.locals:

1
const withAccessAuth = (req: Request, res: ExtendedResponse, next: NextFunction) => {
2
  const token = req.headers['authorization']?.split('Bearer ')[1]
3
  if (!token) return res.status(401).send('Unauthorized')
4
  try {
5
    const { sub, name, age, social } = jwt.verify(token, process.env.ACCESS_TOKEN_SECRET!, {
6
      audience: 'urn:jwt:type:access'
7
    }) as AccessTokenPayload
8

9
    res.locals.user = { username: sub!, name, age, social }
10
    next()
11
  } catch (error) {
12
    return res.status(401).send('Unauthorized')
13
  }
14
}

Remember that for this type of protected route, it’s standard to send an Authorization: Bearer <token> header. That’s why we’re splitting the string.

We can already create our protected route:

1
router.get('/users/:username', withAccessAuth, (req, res) => {
2
  const user = users.find((user) => user.username === req.params.username)
3
  if (!user) return res.status(404).send('User not found')
4

5
  res.json(user)
6
})

The idea is simply to find a piece of data in the database and return that data, always validating if the passed token is valid.

With this, we finish creating our routes. We just need to export our router:

1
export const apiRoutes = router

Front end#

Now that we’ve finished the backend of our application, we’ll start working on the frontend. To make it easier, I didn’t use any framework, but created everything from scratch using only Bootstrap for CSS and a JS file where we’ll put our logic.

For the HTML file, it doesn’t make much sense to explain what’s happening in it, especially since it only has the page markup. So I’ll just leave the code that’s in the index.html file inside a src/frontend folder here so we can look at it:

1
<!DOCTYPE html>
2
<html lang="en">
3
  <head>
4
    <meta charset="UTF-8" />
5
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
6
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
    <!-- CSS only -->
8
    <link
9
      href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css"
10
      rel="stylesheet"
11
      integrity="sha384-gH2yIJqKdNHPEq0n4Mqa/HGKIhSkIHeL5AyhkYV8i59U5AR6csBvApHHNl/vI1Bx"
12
      crossorigin="anonymous"
13
    />
14
    <title>Safe JWT</title>
15
  </head>
16
  <body class="m-3">
17
    <div class="container">
18
      <div class="row align-items-center">
19
        <div class="col text-center">
20
          <form id="loginForm" class="input-group mb-3">
21
            <input
22
              required
23
              type="text"
24
              name="username"
25
              class="form-control"
26
              autocomplete="username"
27
              placeholder="Username"
28
              value="lsantosdev"
29
            />
30
            <input
31
              required
32
              type="password"
33
              class="form-control"
34
              autocomplete="current-password"
35
              name="password"
36
              placeholder="Password"
37
              value="123456"
38
            />
39
            <input id="loginAction" class="btn btn-dark" type="submit" value="Login" />
40
          </form>
41
        </div>
42
        <div class="col text-left">
43
          <div class="alert alert-primary show fade" role="alert">
44
            <strong>Message:</strong> <span class="login-result"></span>
45
          </div>
46
        </div>
47
      </div>
48

49
      <div class="row mb-5 align-items-center">
50
        <div class="col-6 text-center"><strong>Raw access token</strong></div>
51
        <div class="col-6 text-center"><code id="rawToken"></code></div>
52
      </div>
53

54
      <div class="row align-items-center">
55
        <div class="col-6 text-center"><strong>Decoded access token</strong></div>
56
        <div class="col-6 text-center"><pre id="decodedToken"></pre></div>
57
      </div>
58

59
      <div class="row align-items-center mt-5 mb-5">
60
        <div class="col-12 text-center"><button type="button" class="btn btn-primary" id="refreshAction" disabled>Force token Refresh</button></div>
61
      </div>
62

63
      <div class="row align-items-center">
64
        <div class="col-6 text-center">
65
          <form id="userForm">
66
            <input required type="text" name="username" autocomplete="username" placeholder="Search for username" />
67
            <input id="userAction" type="submit" value="Search" />
68
          </form>
69
        </div>
70
        <div class="col-6 text-left">
71
          <div class="alert alert-info show fade" role="alert">
72
            <strong>Results:</strong>
73
            <pre class="user-result"></pre>
74
          </div>
75
        </div>
76
      </div>
77
    </div>
78

79
    <script src="index.js"></script>
80
    <script
81
      src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/js/bootstrap.bundle.min.js"
82
      integrity="sha384-A3rJD856KowSb7dwlZdYEkO39Gagi7vIsF0jrRAoQmDKKtQBHUuLZ9AsSv4jD4Xa"
83
      crossorigin="anonymous"
84
    ></script>
85
  </body>
86
</html>

At the end, this HTML and CSS should give us a page like this (I’m not that good with design):

Inside the same frontend folder we’ll create an index.js file and do some setup.

First, to work more easily, I created a function to update error messages in the app:

1
function updateMessage(message, selector = '.login-result') {
2
  const infoBox = document.querySelector(selector)
3
  infoBox.innerHTML = message
4
}

Then, we’ll create a secure environment to store our access token. I know it’s tempting to put this information on the document object, but unfortunately that’s a global object that’s accessible by any script on the page. We’ll try to keep it more restricted.

Additionally, it would be a nice idea that when this token was updated, the screen was automatically updated too. That’s why we’ll use a Proxy along with a Symbol.

We’ll start by creating the Symbol:

1
const tokenSymbol = Symbol.for('accessToken')

Now we’ll create a Proxy. The Proxy is an object that intercepts calls to other objects. Since it doesn’t work on primitives (like strings), we’ll create an object and use the Symbol as the key to access our access token:

1
const internalToken = new Proxy({ [tokenSymbol]: null }, {})

The initial value will be null, and the second object will be our Proxy’s settings. The first one will be the getter setting, which is when someone tries to get the value of this object.

Since I’m working with the token object, I can’t return the proxy itself. So I’ll use the Reflection API to get the property that’s being called. If it’s a function, we’ll return it already with the correct this. If not, we’ll just return the value:

1
const internalToken = new Proxy({ [tokenSymbol]: null }, {
2
    get(target, prop) {
3
      const primitive = Reflect.get(target, tokenSymbol)
4
      const value = primitive[prop]
5
      return typeof value === 'function' ? value.bind(primitive) : value
6
    },
7
})

The next is the setter, which is where we’ll do the magic:

1
const internalToken = new Proxy(
2
  { [tokenSymbol]: null },
3
  {
4
    get(target, prop) {
5
      const primitive = Reflect.get(target, tokenSymbol)
6
      const value = primitive[prop]
7
      return typeof value === 'function' ? value.bind(primitive) : value
8
    },
9
    set(target, _, value) {
10
      document.querySelector('#rawToken').innerHTML = value
11

12
      const header = atob(value.split('.')[0])
13
      const payload = JSON.parse(atob(value.split('.')[1]))
14
      document.querySelector(
15
        '#decodedToken'
16
      ).innerHTML = `<strong>Header:</strong>${header}<br>---<br><strong>Payload</strong>: ${JSON.stringify(
17
        payload,
18
        null,
19
        2
20
      )}<br> <b>Expires at ${new Date(payload.exp * 1000).toLocaleTimeString()}</b>`
21
      document.querySelector('#refreshAction').disabled = false
22
      return Reflect.set(target, tokenSymbol, value)
23
    }
24
  }
25
)

Basically, what we’re doing is updating our page with the information we receive and, in the end, we’re using the Reflection API again, this time to set the value of the Symbol with the new token.

We’ll do the login action when clicking the button. To do this, we’ll add an event listener that will convert our form data into FormData and then into JSON so we can use fetch to send it to our route:

1
document.querySelector('#loginForm').addEventListener('submit', async (e) => {
2
  e.preventDefault()
3
  updateMessage('Logging in...')
4

5
  const form = new FormData(e.target)
6
  const data = Object.fromEntries(form.entries())
7
  const result = await fetch('/api/login', {
8
    method: 'POST',
9
    headers: { 'Content-Type': 'application/json' },
10
    body: JSON.stringify(data)
11
  })
12
})

After receiving the response, we’ll handle the result and update the token variable with our access token:

1
document.querySelector('#loginForm').addEventListener('submit', async (e) => {
2
  e.preventDefault()
3
  updateMessage('Logging in...')
4

5
  const form = new FormData(e.target)
6
  const data = Object.fromEntries(form.entries())
7
  const result = await fetch('/api/login', {
8
    method: 'POST',
9
    headers: { 'Content-Type': 'application/json' },
10
    body: JSON.stringify(data)
11
  })
12

13
  updateMessage(result.ok ? 'Login successful' : `Login failed with ${result.status}`)
14
  if (result.status === 200) {
15
    const response = await result.json()
16
    internalToken[tokenSymbol] = response.accessToken
17
  }
18
})

Silent Refresh#

Another technique that’s widely used with refresh tokens is silent refresh. It’s the act of refreshing the access token before it expires. So let’s say our access token lasts 5 minutes. Every 4.5 minutes we’ll silently make a request to the /refresh endpoint and it will give us a new access token as well as a new refresh token.

To do this it’s quite simple. We just use our login action to set an interval that will call a function that will refresh the tokens. Let’s change our login code to include two more lines:

1
document.querySelector('#loginForm').addEventListener('submit', async (e) => {
2
  e.preventDefault()
3
  updateMessage('Logging in...')
4

5
  const form = new FormData(e.target)
6
  const data = Object.fromEntries(form.entries())
7
  const result = await fetch('/api/login', {
8
    method: 'POST',
9
    headers: { 'Content-Type': 'application/json' },
10
    body: JSON.stringify(data)
11
  })
12

13
  updateMessage(result.ok ? 'Login successful' : `Login failed with ${result.status}`)
14
  if (result.status === 200) {
15
    const response = await result.json()
16
    internalToken[tokenSymbol] = response.accessToken
17
    setInterval(refreshToken, refreshIntervalMinutes)
18
    updateMessage('Next refresh at ' + new Date(Date.now() + refreshIntervalMinutes).toLocaleTimeString())
19
  }
20
})

And let’s add a new variable at the top of the file to say when we want to do the refresh:

1
const refreshIntervalMinutes = 4.5 * 60 * 1000

And we’ll take the opportunity to create the refresh function that will just make a fetch call:

1
function refreshToken() {
2
  updateMessage('Refreshing token...')
3
  fetch('/api/refresh', {
4
    method: 'POST'
5
  })
6
    .then((res) => res.json())
7
    .then(({ accessToken }) => {
8
      internalToken[tokenSymbol] = accessToken
9
      updateMessage('Next refresh at ' + new Date(Date.now() + refreshIntervalMinutes).toLocaleTimeString())
10
    })
11
}

Searching for the user#

To make the user search call, we’ll use the same technique, sending the form data to our protected route with an Authorization header:

1
document.querySelector('#userForm').addEventListener('submit', async (e) => {
2
  e.preventDefault()
3
  if (!internalToken) return updateMessage('Login first', '.user-result')
4
  updateMessage('Searching user...', '.user-result')
5

6
  const form = new FormData(e.target)
7
  const data = Object.fromEntries(form.entries())
8
  const result = await fetch(`/api/users/${data.username}`, {
9
    headers: {
10
      Authorization: `Bearer ${internalToken}`
11
    }
12
  })
13
  updateMessage(result.ok ? 'User found' : `Search failed with ${result.status}`, '.user-result')
14
  if (result.status === 200) {
15
    const response = await result.json()
16
    updateMessage(JSON.stringify(response, null, 2), '.user-result')
17
  }
18
})

Force refresh#

The last step is to bring the force refresh button to life, which is basically calling our refresh function that we created before:

1
document.querySelector('#refreshAction').addEventListener('click', refreshToken)

Result#

The result can be seen when we click the login button:

We’ll have the access token data available to JavaScript through memory, but we can’t get the refresh token unless we open DevTools on the application tab:

You can also see that we made the request that returned the cookie to us:

On the server side, we can see that the tokens are being set and expiring as time passes:

See how the final animated result turned out:

Conclusion#

This saga isn’t over yet! We’re going to explore much more about how we can store and use tokens securely in future articles! Two readings I highly recommend are the ones from the Hasura blog about tokens and this really cool article by Ryan Chenkie.

Don’t forget to come back to see and subscribe to the newsletter for new and exclusive content!

The code used in this example can be found on my GitHub ↩
The code for this example is in the fingerprinting branch of the GitHub repository. Check the handlers.ts and index.js files for the differences ↩