Adding JSON Web Token API Keys to a DenyList

tl;dr: If you understand why and how to support blacklisting JWTs, then skip to the code.

In a previous post, we proposed an approach to using JSON Web Tokens as API Keys, going over some of the benefits of doing so and also providing some examples based on our API v2 scenarios. This post follows up by explaining an aspect that was not covered before: how to add JWT API keys to a DenyList so they are no longer valid.

If you need an in-depth introduction to JSON Web Tokens, check out the free ebook below.

Interested in getting up-to-speed with JWTs as soon as possible?

Download the free ebook

A Real World Example

Let's for a second assume that GitHub used JSON Web Tokens as API Keys and one of them was accidentally published on the web. You would want to make sure an app can no longer access your information by revoking that token:

Framing the Problem

Providing support for blacklisting JWTs poses the following questions:

1. How are JWTs individually identified?
2. Who should be able to revoke JWTs?
3. How are tokens revoked?
4. How do we avoid adding overhead?

This blog post aims to answer the previous questions by leveraging our experience from implementing this feature in our API v2.

1. How are JWTs individually identified?

To revoke a JWT we need to be able to tell one token apart from another one. The JWT spec proposes the

jti

As a quick reminder, this is how the claims section of one of our JWT API tokens looks like:

The tokens accepted by our API use the

aud

(aud, jti)

Similarly, if a token does not include the

jti

2. Who should be able to revoke JWTs?

If anyone could revoke our API keys then unfortunately they wouldn't be of much use. We need a way of restricting who can revoke a JWT.

“If anyone could revoke our API keys then unfortunately they wouldn't be of much use.”

Tweet This

The way we solved it in our API is by defining a specific scope (permission) that allows blacklisting tokens. If you generate a JWT like the one shown in the next figure you will be able to revoke JWTs:

Notice the

blacklist

action nested inside the

scopes

object.

3. How are tokens revoked?

To blacklist/revoke a token, you need a JWT API key (referred to as

JWT_API_KEY

POST

/api/v2/blacklists/tokens

curl -H "Authorization: Bearer {JWT_API_KEY}"
-X POST
-H "Content-Type: application/json"
-d '{"aud":"u6nnAxGVjbBd8etXjj554YKGAG5HuVrp","jti":"test-token"}'
https://login.auth0.com/api/v2/blacklists/tokens

The complete documentation for the endpoint is here but basically you need to:

• Send the

  aud

  and

  jti

  claims of the JWT to revoke.
• Send the JWT with the permissions necessary to blacklist tokens in the Authorization header.

To get the revoked tokens you can issue a

GET

/api/v2/blacklists/tokens

4. How do we avoid adding overhead?

You might be thinking:

Wasn't the whole point of using JWTs avoiding a DB query?

Well, that is a benefit, though hardly the whole point. There is a caveat though: that question only applies if you have an application with a single issuer, not a multi-tenant system.

If there is more than one tenant, you don't want all of them to share the same secret. You still have to perform a database query to map the

aud

secret

With that in mind, these are some of the optimizations that you can implement:

• Optimization 1: The aforementioned operation involves I/O so it can be performed in parallel with our query to verify if a token has been revoked.

  Of course, you can also add a caching layer with a reasonable expiration time to avoid the DB trips altogether.

• Optimization 2: Skip the expiration check if the

  jti

  claim is not part of the JWT.

• Optimization 3: To reduce the size of the revoked tokens store you could automatically remove JWTs from it once their

  exp

  is reached (assuming there is one).

Implementation

We have shipped version 1.3.0 of the open source express-jwt with support for multi-tenancy and blacklisted tokens. We also put together a sample that shows everything working together. The sample is based on our API v2 implementation.

The following code snippets use show the core sample parts:

Securing the endpoint

The first thing we have is an API that we would like to protect. The

express-jwt

• secret

  • A function in charge of retrieving the secret.

• isRevoked

  • A function in charge of checking if a JWT is revoked.

var expressJwt = require('express-jwt');
// to protect /api routes with JWTs
app.use('/api', expressJwt({
  secret: secretCallback,
  isRevoked: isRevokedCallback
}));

Handling multi-tenancy

The implementation for the

secretCallback

If the data layer provides an encrypted tenant secret, it needs to be decrypted before calling

done

var LRU = require('lru-cache');

var secretsCache = LRU({ /* options */ });

var secretCallback = function(req, payload, done){
  var audience = payload.aud;
  var cachedSecret = secretsCache.get(audience);

  if (cachedSecret) { return done(null, cachedSecret); }

  data.getTenantByIdentifier(audience, function(err, tenant){
    if (err) { return done(err); }
    if (!tenant) { return done(new Error('missing_secret')); }

    var secret = utilities.decrypt(tenant.secret);
    secretsCache.set(audience, secret);
    done(null, secret);
  });
};

Supporting revoked JWTs

Similarly, the

isRevokedCallback

(aud, jti)

jti

var jtiCache = LRU({ /* options */ });

var isRevokedCallback = function(req, payload, done){
  var tokenId = payload.jti;
  if (!tokenId){
    // if it does not have jti it cannot be revoked
    return done(null, false);
  }

  var tokenIdentifier = payload.aud + ':' + payload.jti;
  var blacklisted = jtiCache.get(tokenIdentifier);
  if (typeof blacklisted !== 'undefined') { return done(null, blacklisted); }

  data.getRevokedTokenByIdentifier(tokenIdentifier, function(err, token){
    if (err) { return done(err); }
    blacklisted = !!token;
    jtiCache.set(tokenIdentifier,blacklisted)
    return done(null, blacklisted);
  });
};

Conclusion

Most of the aforementioned content applies to blacklisting JWTs in general, not just JWT API keys.

Hopefully this blog post has provided some useful ideas on how to tackle this problem.

If you have any comments or questions don't hesitate to post them!

You an also get involved in express-jwt!

auth0.getUser