DEV Community: Tom Mount

Zero Trust at the Edge (part 4)

Tom Mount — Mon, 24 Feb 2025 22:44:36 +0000

Incorporating JWKS into your JWT Validation Middleware

Build a full-featured signing and validating server.

Recap

In Parts 1 and 2, we looked at what a JWT is and built some Express middleware that we could use to validate JWTs. In Part 3, we learned about JSON Web Key Sets (JWKS) and considered how they allow us to sign JWTs with multiple private keys and rotate those private keys without having to worry much about any sort of mismatch when we validate those JWTs.

Important Warning ⚠️

In Part 2, recall that I said you should not roll your own validator from scratch because there are libraries already available that do this, and those libraries are maintained by people who are paid good money by large companies to maintain them. Once again, I warn you not to roll your own JWKS suite. Auth0 (not a sponsor, but, I mean, call me?) has a very serviceable free tier if you want to deploy a solution like this publicly. The code you're going to find in this post is really for illustration and learning ONLY and you should definitely not take it and simply deploy it somewhere and rely on it to provide adequate security.

Again, you have been warned.

Generating the JWKS

In Part 3 we looked at how to use Let's Encrypt and certbot to generate a 2048-bit RSA private key, and how to extract the public key from that private key.

To start, we'll go into the express-jwt project and add a dev dependencies on Cisco's node-jose:

$ npm install -D node-jose

We'll create a utility class to abstract away some of the more esoteric functions of the key store. Create a new file called src/JWKS.js and paste in the following:

const jose = require('node-jose')
const crypto = require('node:crypto')
const fs = require('node:fs/promises')

class JWKS {
  /** The underlying keystore. */
  #store = jose.JWK.createKeyStore()

  /** Whether or not this store can sign tokens. */
  #canSign = false

  constructor() {
    //
  }

  /**
   * Indicates whether the store is capable of signing a payload.
   * @returns {boolean} True if the store can sign, false otherwise.
   */
  get canSign() {
    return this.#canSign
  }

  /**
   * Add a certificate and chain to the store.
   * @param {string} pathToKey The path to the key in PEM format. Can be a public or private key, but only private keys can sign requests.
   * @param {string} pathToCertChain The path to the certificate chain in PEM format.
   * @returns {Promise<jose.JWK.key>}
   */
  async add(pathToKey, pathToCertChain) {
    const key = await fs.readFile(pathToKey)
    const chain = await fs.readFile(pathToCertChain)

    const keyAsText = key.toString()
    const chainAsText = chain.toString()

    // If we're uploading a private key, or we already have, allow this instance to sign payloads.
    this.#canSign = this.#canSign || keyAsText.startsWith('-----BEGIN PRIVATE KEY-----')

    // Parse the chain for the required x5c values.
    const begin = '-----BEGIN CERTIFICATE-----'
    const end = '-----END CERTIFICATE-----'
    const certsPem = chainAsText.split(end)
      .map(cert => cert.trim())
      .filter(cert => cert)
      .map(cert => `${cert}${end}`)

    const certsDer = certsPem.map(certPem =>
      certPem.replace(begin, '')
        .replace(end, '')
        .replace(/[\n\r]/gm, '')
    )
    const thumbprints = certsDer.map(certDer => {
      let sha1 = crypto.createHash('sha1')
      sha1.update(certDer)
      return sha1.digest('base64')
    })

    return this.#store.add(key, 'pem', {
      use: 'sig',
      alg: 'RS256',
      x5c: certsDer,
      x5t: thumbprints[0]
    })
  }

  /**
   * Remove a key from the store by its ID.
   * @param {string} kid The Key ID to remove.
   */
  remove(kid) {
    const toRemove = this.#store.get(kid)
    if (toRemove) this.#store.remove(toRemove)
    // TODO: if we removed our only remaining private key, then we need to change #canSign.
  }

  /**
   * The JWKS object suitable for pasting into a JWKS endpoint.
   * @param {boolean} includePrivate Include private key information in the JWKS. NOT RECOMMENDED.
   * @returns {any}
   */
  asJWKS(includePrivate = false) {
    return this.#store.toJSON(includePrivate)
  }

  /**
   * Get the PEM-formatted public key for a given Key ID.
   * @param {string} kid The Key ID to retrieve.
   * @returns {string}
   */
  publicKeyAsPem(kid) {
    const key = this.#store.get(kid)
    if (!key) {
      throw new Error(`Key with ID ${kid} not found.`)
    }
    return key.toPEM(false)
  }
}

module.exports = {
  JWKS
}

As in Part 2, I made as many comments as I could to explain what is going on throughout the code, so I won't go into much detail here.

If you're wondering when I'm going to get to fullchain.pem, it's up next. You'll notice the add method references pathToKey (that's the public or private key) and pathToCertChain - that's the certificate chain for signed certs. You'll notice it's required, even if you're pushing up only a public key. This is by design - the x5c portion of the JWKS assumes a certificate chain, even for public certs (eagle-eyed viewers will notice that it's an array, not a single string), and to generate a properly-formed JWKS, we need the chain.

We can test this out pretty easily by creating a quick test file and running it. Create a file called src/testJWKS.js and drop in the following:

const { JWKS } = require("./JWKS.js");

(async () => {

  const store = new JWKS()
  // Add the private key and the fullchain certificate.
  const addedKey = await store.add('../certs/jwks01.privkey.pem', '../certs/jwks01.fullchain.pem')

  // Create a JWKS representation and dump it to the console.
  const jwks = store.asJWKS()
  console.log(JSON.stringify(jwks, null, 2))
  console.log('\n*****\n')

  // Using the key ID, retrieve the public key and dump it to the console.
  const { kid } = addedKey
  const publickey = store.publicKeyAsPem(kid)
  console.log(publickey)
  console.log('\n*****\n')

  process.exit()

})()

If everything went well, two things should have been dumped:

The JWKS as JSON, and
The public key in PEM format.

So far so good!

Signing a JWT

Adding the functionality to sign a token is pretty simple with the underlying node-jose library. Within the JWKS class, add another method:

  /**
   * Sign a JWT.
   * @param {any} payload The payload to sign.
   * @returns {Promise<jose.JWS.createSignResult>} The signed JWT.
   */
  async sign(payload) {
    // If we haven't added a private key to the store, don't allow signing.
    if (!this.#canSign) {
      throw new Error('Unable to sign messages with only a public key.')
    }

    // The iss field isn't required but is a good idea.
    if (!('iss' in payload)) {
      payload.iss = 'ExampleJWKS'
    }

    const signer = jose.JWS.createSign({ format: 'compact'}, this.#store.get())
    signer.update(JSON.stringify(payload))
    return signer.final()
  }

In the test file, we can add another block to create a payload and dump the signed JWT:

  if (store.canSign) {
    const payload = {
      sub: '1234567890',
      name: 'John Doe',
      iat: Math.floor(Date.now() / 1000)
    }
    const jwt = await store.sign(payload)
    console.log(jwt)
    console.log('\n*****\n')
  } else {
    console.log('Cannot sign with a public key only. Please add a private key.')
  }

Rerunning the test script, we now see a third piece of information dumped, something that looks remarkably like a JWT. If you copy that token and drop it into https://jwt.io you should see your full token:

Notice that the algorithm in the dropdown shows RS256 and there's a kid claim in the header. You can also see that, without any public key information, the signature is invalid. The output of the test script dumped the public key; copy that and paste it into the first text box, and the page should update to indicate that the signature is valid.

But that was using a defined public key. What if we used the exported JWKS instead? The hint in the text box reads "Public Key in SPKI, PKCS #1, X.509 Certificate, or JWK string format." That last part is interesting - we're dumping the JWKS (remember the "S" stands for "set") but each entry in the keys node is a single JWK. Go back to the console output and grab the first key only, ie. just the curly braces and what's inside them. Back on jwt.io, clear out the PEM certificate from the public key and instead paste in the JSON object. Was your signature verified?

What's handy about using node-jose is that I didn't have to write any code to handle the key IDs, nor did I have to manually insert the ID. Because node-jose knew the private key I'm using, it extracted a fingerprint as the key ID and included it automatically.

But what if I have multiple private keys? Fortunately, it's pretty easy to adjust the JWKS class to handle multiple keys. Let's update the last bit of code in the sign method:

    // The iss field isn't required but is a good idea.
    if (!('iss' in payload)) {
      payload.iss = 'ExampleJWKS'
    }

    // Start editing here...
    let signer
    if (kid) {
      signer = jose.JWS.createSign({ format: 'compact'}, this.#store.get(kid))
    } else {
      signer = jose.JWS.createSign({ format: 'compact'}, this.#store.get())
    }
    signer.update(JSON.stringify(payload))
    return signer.final()

We're relying on the fact that get() by itself will get the first valid signing key, while get(kid) will get a specific key.

On the test script, we'll add a line under const addedKey...:

const legacyKey = await store.add('../certs/jwks00.privkey.pem', '../certs/jwks00.fullchain.pem')

(where jwks00 refers to an older keypair from a different Let's Encrypt operation)

In the signing block, we'll extract the key ID for the legacy key and update the code to also create a JWT using that key:

const jwt = await store.sign(payload, kid)
const legacyKid = legacyKey.kid
const legacyJwt = await store.sign(payload, legacyKid)
console.log(jwt)
console.log('\n*****\n')
console.log(legacyJwt)
console.log('\n*****\n')

Now we're dumping the same payload twice, but each is signed by a different key. We can take the signed token into jwt.io and see that that kid changes based on the token that we pasted. We can also paste in the corresponding JWK object from the dumped JWKS to see that only the matching kid public key will validate the token.

This is all pretty cool stuff but it's still very manual. Let's go back to our express server and see if we can host the whole JWKS.

Hosting the JWKS

Before we start our server, we'll want to import the JWKS class, add our keys, and store the keystore in memory. Edit the src/index.js file and add the following code underneath the last require statement:

// JWKS handling
const { JWKS } = require('./JWKS.js')
const store = new JWKS()

/**
 * Initialize the JWKS store with the certificates.
 */
async function initStore() {
  const basepath = path.join(__dirname, '..', 'certs')
  await store.add(`${basepath}/jwks00.privkey.pem`, `${basepath}/jwks00.fullchain.pem`)
  await store.add(`${basepath}/jwks01.privkey.pem`, `${basepath}/jwks01.fullchain.pem`)
  console.log('JWKS loaded.')
}
initStore().catch(err => {
  console.log(err)
})

This will add the certs once the server starts and notify the console when complete. Finally, add another route for this information:

app.get('/.well-known/openid-configuration', (req, res) => {
  const jwks = store.asJWKS()
  res.json(jwks)
})

The URI path here reflects the same path that Auth0 uses for its autodiscovery service.

In a browser or on a command line, issue a GET request to http://localhost:3000/.well-known/openid-configuration - the complete JWKS should be displayed.

Reading the JWKS and Validating the JWT

The Express application can already handle RS256 tokens, so there's not a huge amount of work needed to update it to handle specific key IDs passed in the token header. At a high level, though, we need to address a few things:

We need to be able to access the JWKS store object within the middleware.
We need to fetch a specific key from the store and present it to the jsrsasign library in a way it understands.

The first point can be handled in a variety of different ways, but in this case, we can either fetch it from the /.well-known/openid-configuration path, or we can fetch it from the in-memory object used to populate that object. There are pros and cons to each but for a simple demonstration (and without getting into async middleware) it's probably easiest to inject the key store into the response object as part of the middleware.

Create a new file, src/middleware/InjectJwks.js, and put in the following:

/**
 * Inject the JWKS store into the request.
 * @param {any} store The JWKS store.
 * @returns The next middleware in the chain.
 */
const injectJwks = (store) => {
  return function (req, res, next) {
    res.locals.store = store
    next()
  }
}

module.exports = injectJwks

This is a pretty simple middleware but the signature is not a normal middleware signature. This is because we're using a wrapper function to handle injecting our store into the request (technically in the response). You can think of this as a more dynamic version of the venerable Express middleware.

Back in src/index.js we'll import the new middleware and add it to the /api/validate route:

const validate = require('./middleware/Validate.js')
// Add this line:
const injectJwks = require('./middleware/InjectJwks.js')

// ...

// And then update this line:
app.post('/api/validate', injectJwks(store), validate, (req, res) => {

Note that instead of simply passing injectJwks we're calling a function that returns another function, this time with the correct signature. This bit of gymnastics will ensure that the key store is injected into a variable accessible for the next middleware component.

The other step in the validation process is updating the middleware to use the store we're now injecting into the response. Open up src/middleware/Validate.js and let's make a few changes.

First, I'm going to tweak slightly how the public key is being generated. Instead of calling KEYUTIL.getKey() directly, I'm going to pull that piece of functionality out into its own function so we can reuse it later:

const fromBase64Url = (str) => Buffer.from(str, 'base64url').toString()

// Add this function:
const getPublicKey = (keyString) => KEYUTIL.getKey(keyString.replace(/[\n\r]+/g, ''))

const jwtSecret = process.env.JWT_SECRET
// And update this line:
const publicKey = getPublicKey(readFile(path.join(__dirname, '..', '..', 'certs', 'pubkey.pem')))

Now, we have a convenience method that takes a PEM string, replaces any newline characters, and generates an RSAKey object from the string. This is important because in this example we're mixing libraries - the jsrsasign library that we're using for validation doesn't handle key objects in quite the same way as the node-jose library that we're using for the JWKS store does. I experimented with a few ways of going back and forth but ultimately using the publicKeyAsPem() method on the store to export a PEM public key seemed to work the best. Inside the validate() method, let's update a little logic:

  const [ header, payload ] = token.split('.')
  // Update this line to extract the key id as well as the algorithm:
  const { alg, kid } = JSON.parse(fromBase64Url(header))

  let validationComponent = null,
      isValid = false

  try {
    if (/^HS/.test(alg)) {
      // HSxxx algorithms use a shared secret.
      validationComponent = jwtSecret
    } else if (/^[REP]S/.test(alg)) {
      // RSxxx, ESxxx, and PSxxx algorithms all use a public key.
      validationComponent = publicKey

      // If there's a kid defined in the header, we can assume for demonstration
      // purposes that we're dealing with a JWKS request.
      if (kid) {
        // Even though we have an endpoint serving the JWKS, we can get some
        // performance benefit by using the in-memory store instead of the endpoint.
        if (res.locals.store) {
          const key = res.locals.store.publicKeyAsPem(kid)
          validationComponent = getPublicKey(key)
        } else {
          // If a kid was specified but not found in the store, throw an error.
          res.status(500).send('No matching KID found')
        }
      }
    } else {
      // Those are the only options; if another one was specified, throw an error.
      console.log(`Invalid algorithm specified: ${alg}`)
      res.status(501).send('Not Implemented')
    }
  } catch (e) {
    console.log(e)
    res.status(500)
  }

The new block of code in the try...catch block first uses the fallback public key that we hardcoded at the top of the file. But then, we check if there's a key ID in the header (if the destructuring didn't find a kid key, the variable will be undefined). If not, we don't do anything; but if so, we do a further check to ensure that we have a JWKS store in res.locals.store. If not, we throw an error and the middleware terminates. Only if there's a kid specified, and we have a valid store, do we extract the public key as a PEM string by kid and pass it to the getPublicKey() convenience method we just added. This will ensure that we have a valid RSAKey object from the jsrsasign library to do our validation. We assign that object to validationComponent, and the rest of the middleware is fine as-is.

Testing everything together

At this point in the project, we have an Express server with a route requiring JWT validation. We've already tested the validation using pre-shared keys (HS256 algorithm) and a single, static public key (RS256 algorithm). Now let's test multiple tokens signed with different keys.

The test script we were using earlier (src/testJWKS.js) will take a single payload and sign it with two different private keys (and therefore the tokens will have different kid values and different public keys). Re-run that script so that we can get two separate tokens. Once you have those tokens, you can run different curl commands:

$ curl -X POST http://localhost:3000/api/validate -H "Authorization: Bearer [jwt 1]"
{"sub":"1234567890","name":"John Doe","iat":1740245256,"iss":"ExampleJWKS"}
$ curl -X POST http://localhost:3000/api/validate -H "Authorization: Bearer [jwt 2]"
{"sub":"1234567890","name":"John Doe","iat":1740245256,"iss":"ExampleJWKS"}

Wrapping Up the Series

JSON Web Tokens (JWTs) are a secure, flexible way to provide additional authorization to your applications at the edge. But they can be tricky to manage at scale, especially if you use a public/private keypair setup to manage the token signing, or you're interfacing with another system that does this. One of the ways to make this process a little less painful is to employ JSON Web Key Sets (JWKS), which is a system to maintain multiple public keys in an automated way, and then use this JWKS file to pick the right public key to validate your JWT.

Parts 1 and 3 dealt with the theory of JWTs and JWKS; parts 2 and 4 provided some very basic code samples that you should definitely not just put into production; hopefully, those samples helped explain the workflow and demonstrated end-to-end what the JWT validation process might look like.

The code for the finished repo is up on Github should you want to look at it all together, clone it, tweak it, etc. It's all open-source, so by all means please take it and learn from it.

I hope this has been helpful!

Zero Trust at the Edge (part 3)

Tom Mount — Mon, 17 Feb 2025 18:19:48 +0000

Working with JSON Web Key Sets

Scale up your JWT validation operation.

Recap

In Part 1 we looked at what a JSON Web Token is, how it's created, and how it's validated. In Part 2 we looked at a simple Express server with JWT validation middleware, with all the usual warnings about not reinventing the wheel.

Defining the Terms (mostly review)

As a popular language learning app says... Before we begin, here are some terms you should know:

JWT - short for JSON Web Token. This is the piece of information that needs to be validated (checked for authenticity) with every request.
Algorithm - in the JWT world, the algorithm is the combination of hashing and signing the token's payload. Comes in two flavors:
- Symmetric - If you see HSxxx in the header, you're dealing with HMAC-SHAxxx signing algorithms. A secret key was used to sign the JWT, and that same secret key will be necessary to validate the signature later.
- Asymmetric - If you see RSxxx, ESxxx, or PSxxx in the header, you're working with asymmetric signing algorithms. Of these, RSxxx is probably the most common and almost certainly the most performant; it uses RSA as the signing method, which requires a public/private keypair. The private key is used to sign the JWT, but it can be validated with the matching public key. ESxxx means Elliptic Curve Digital Signature Algorithm (ECDSA) was used; PSxxx also uses RSA under the hood but uses a newer signature scheme than the older RSxxx tokens use. If that doesn't make any sense whatsoever, that's fine - understanding the ins and outs of hashing and signing algorithms isn't strictly necessary to understand the basic workflow.
JWKS - short for JSON Web Key Set. If you don't know what that is, read on because that's the point of this post.
Public/Private Keypair - A set of two cryptographic certificates that are tied to each other. In (very) short, a private key can be manipulated to extract a public key, but the operation is one-way; that is, the public key cannot be used to generate the corresponding private key. Wikipedia has more information. Key pairs are commonly used to generate SSL certificates for websites, and for enabling passwordless SSH logins.

Scaling Up

In Part 2 we looked at an example repo that could validate either a symmetric algorithm or an asymmetric algorithm, based on the token's header's alg claim and either an environment variable or a public key. In Part 3 we'll consider ONLY asymmetric algorithms, specifically RS256.

One of the advantages of using a private/public keypair is that the verification can be done using a public key without the private key ever needing to leave the signing server. The public key is, after all, meant to be public, and because of the math involved, it's not possible to reverse-engineer the private key from just the public key. This means the public key can be loaded pretty much anywhere, which means the token can be validated pretty much anywhere too. But the downside of using a keypair is that if you rotate the public key every now and then (and you absolutely should do that) there will be some period, however brief, where the certificates won't match: the server will be signing tokens with the new private key, but the validation endpoints will still have the old public key, and the validator will fail. Building infrastructure around the update process can help mitigate the risk of a key mismatch but it's still not completely fail-proof.

JWKS represents a better way to manage your key rotation. When the JWT is signed by the issuing system, a key ID for the private key used to sign the token is stored in the header of the token. The validating system reads both the algorithm used as well as the key ID, and validates the signature based on the public key with the same ID. The JWKS is a serialized array containing one or more public keys with their IDs. The token header will contain just one more claim, the kid claim:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "12345"
}

The kid claim can be any alphanumeric string - GUID, integer, name, they all work just as well, though care should be taken to ensure that the keys being used are not assigned the same ID.

The JWKS itself is a JSON object with a single keys array, which contains key objects:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "174EFCA3923B25163F581A0CB71CAD97B036E0B8",
      "x5t": "F078o5I7JRY_WBoMtxytl7A24Lg",
      "x5c": ["MIIEWzCCA0OgAwIBAgIJAPzw5pQEyIL4MA0GCSqGSIbgZ3..."],
      "e": "AQAB",
      "n": "n1x3isqbPYjG2dUm5d5N1MBk9zKHt5LujgFXJO1SCnCW...",
      "alg": "RS256"
    },
    { ... }
  ]
}

Note that each key has a kid assigned; tokens should include this same kid in the header so that the public key can be loaded.

"But wait," you say, "where's the public key? What is this x5t and x5c and e and n stuff?" You're probably used to seeing public keys that look like this:

-----BEGIN PUBLIC KEY-----
(lots of letters and numbers)
(that go on for lines and lines)
-----END PUBLIC KEY-----

What you see in the JWKS, though, is the raw information necessary to build the public key on the fly. Libraries like jsrsasign (which we used in Part 2) have methods to import the cryptographic information in the JWKS and construct the public key necessary to validate the token. Those libraries also have utilities to do the same thing in reverse - turn the more common certificate format (PEM) into a serialized data object.

Accessing the JWKS

While it's nice to have a serialized format that allows for the storage of multiple keys, it can still be a hassle to update this JWKS if you have to push it to multiple endpoints. A better strategy is to take advantage of autodiscovery and host the key set at a single URI at a well-known location so that consumers can periodically auto-update. For example, Microsoft Azure AD stores its JWKS at https://login.microsoftonline.com/common/discovery/v2.0/keys (you can visit that in your browser and see the JSON structure, though I'd recommend using something that can pretty-print the output as it's minified by default). When Microsoft wants to rotate a key, they simply push the new public key into the set and publish the new JWKS at the same URI. Consuming clients can poll the URI on a regular schedule and get the new public key. After a brief period (long enough that consuming clients have picked up the updated list) they will start signing tokens with the new private key, and any client that gets a new token will have the corresponding public key already loaded into memory.

Special Consideration: Generating the Keypair

Throughout this intro, I've mentioned public/private keypairs. You can generate these yourself, and if you've ever set up remote access to a server using SSH, you probably already have:

$ openssl genrsa -out jwt_signing_cert.pem 2048
$ openssl rsa -in jwt_signing_cert.pem -pubout -out jwt_public_key.pem

This generates a 2048-bit private key using RSA, then extracts the public key and saves it. Once those two commands finish, you'll have two new .pem files, one the private key and the other the public key. You can absolutely use those files for signing and validation...but you probably shouldn't. The reason is that these keys are considered "self-signed" and using self-signed keys in public is generally considered a poor practice. Some cloud vendors and validation packages will not allow you to validate tokens using self-signed certificates.

When I first started using my former employer's JWKS solution, I was stymied by this restriction for a few days while trying to build a demo I could use in sales calls. Generating signed certificates generally costs money, and while I could have probably gotten a reimbursement for this, it was an expense I didn't want to incur. Ultimately, though, I realized that a PEM certificate is a PEM certificate, regardless of what it's used for, and there exists at least one service that was created for the sole purpose of issuing free certificates: Let's Encrypt. The process for doing that ended up being pretty straightforward, though it took a while to piece all the information together.

Before going down this route, you'll want to make sure that certbot is installed and up-to-date. Follow the official instructions if you're not sure.

You'll also need to make sure you have the means of generating your own cert with Let's Encrypt, which means you need access to the DNS settings for a domain.

It's important to note that by default, certbot will use ECDSA as the private key algorithm. It does still support using RSA keys (for now), but you will need to request it specifically. By default when creating RSA keys, certbot uses a 2048-bit key. While you can change this, you probably should not, as some cloud providers only support 2048-bit RSA keys.

To generate a signed 2048-bit RSA private key from Let's Encrypt, use the following command, either as root or using sudo:

$ certbot certonly \
  --manual \
  --preferred-challenges dns-01 \
  --key-type rsa \
  -d jwks01.yourdomain.com

I'm using the manual mode on certbot to specify my preferred challenge method (dns-01 which requires a DNS TXT record to prove ownership) and, critically, specifying the --key-type rsa flag to generate an RSA private key.

Certbot will give you a text record to place at _acme-challenge.jwks01.yourdomain.com (the actual subdomain you use is arbitrary; I chose jwks01 because it's unlikely I would actually host anything there, so I don't have to worry about naming collision, and because when I'm looking at all my _acme-challenge records I've collected over the years, I want to know what that one was for). Once that DNS record is in place and certbot has validated it, it will place four files in its default location; for me, that was /etc/letsencrypt/live/jwks01.yourdomain.com. DO NOT MOVE THESE FILES. We really only care about two of them: privkey.pem (the RSA private key) and fullchain.pem (the certificate signing chain). You'll want to copy those two files into your project directory.

(The other two files there are more relevant if you're setting up SSL for jwks01.yourdomain.com, which is the whole point of Let's Encrypt. However, as I mentioned earlier, a signed RSA private key is a signed RSA private key.)

You can use the commands above to generate the public key from the private key:

$ openssl rsa -in privkey.pem -pubout -out pubkey.pem

And that's all there is to it! You're now the proud owner of a signed RSA private key and its corresponding public key.

"But wait," you say once again, "what about the fullchain.pem file?" Glad you asked! There's one more piece of this puzzle you need to generate an actual JWKS file, but because that's a bit more code-heavy, I'll save that for next week's installment.

Wrapping it Up

In this installment, we looked at what a JSON Web Key Set is and how it helps scale out the adoption of asymmetric RSA signing keys for JSON web tokens. We also took a brief detour into the world of public key cryptography and talked about ways to generate a valid public/private keypair that can be used to sign and validate JWTs.

The final installment will cover how to modify the existing express-jwt example repo introduced in Part 2 to import those keys, serve the JWKS at a well-known URI, and use the JWKS to validate multiple tokens signed by different private keys.

Zero Trust at the Edge (part 2)

Tom Mount — Mon, 10 Feb 2025 17:39:05 +0000

Creating and Validating your own JSON Web Tokens

Take charge of your authorization needs.

Recap

In Part 1 we looked at what a JSON Web Token is, how it's created, and how it's validated. If you need a primer, go back and read that. I'm going to assume you're broadly familiar with JWTs from here on out.

Also, you can roll your own JWT creation and validation code. You definitely should not do that. There are any number of libraries that will do this for you that have been tested, vetted, and tested again, from reputable organizations like Okta, Auth0, etc. These are companies that do authz as a core business and pay people quite comfortably to maintain these packages and respond to security issues. Do not roll your own crypto. You have been warned.

(The featured image for this post comes from Classic Programmer Paintings, a disaster of a scene titled "We rolled our own crypto.")

The process for signing, and later validating, your JWTs is pretty straightforward, such that a reasonably competent JavaScript developer could probably write their own library to do that using only the built-in crypto libraries for either Node or the Web Crypto API. But I'm a firm believer in not reinventing the wheel unless absolutely necessary. When you're building out performant edge-based applications, you should absolutely use a trusted third-party library; but you also should take into account the size of that library and how well it will perform in an edge environment. Most edge compute platforms have restrictions in place around how long any request can go unanswered, how much CPU time and memory can be used by the script, and the response size. When I built out this example for my former employer, those restrictions were very tight and so I ended up using the jsrsasign library instead of the more common express-jwt or jwt-decode libraries from Okta; those libraries were either too big to run properly in my environment, and/or they relied on the Web Crypto API, which was not available in the edge execution environment.

Validation

Setting up a validation middleware (assuming you aren't using express-jwt directly) with jsrsasign is pretty simple. The middleware should do the heavy lifting of parsing the token, and on success, it should put the payload's token into the request bag and allow the request to continue. Any failure (bad algorithm in the header, tampered token, etc.) should short-circuit the request and throw an appropriate error. This middleware can then be imported into your main Express server and applied on any route or routes that require token validation.

The most common ways of sending a token with a request are to use a request cookie or an Authorization header, but those aren't the only ways. For this demo, though, we'll stick to an authorization header in the format Authorization: Bearer [token].

To begin, start off with a basic Express server, along with the jsrsasign library:

npm install express body-parser cors jsrsasign jsrsasign-util

I also use dotenv which automatically loads variables from .env when you enter a directory, and unloads them when you leave the directory. Set up a .env file with a few values:

PORT=3000
JWT_SECRET=your-256-bit-secret

Your express server should look something like this:

const express = require('express')
const path = require('path')
const cors = require('cors')
const bodyParser = require('body-parser')

const app = express()
app.use(express.static(path,join(__dirname, 'public')))
app.use(cors())
app.use(bodyParser.json())

const port = process.env.PORT || 3000
app.listen(port, () => {
  console.log(`Server running on port ${port}`)
})

Let's build out the validation middleware. Create a middleware/Validate.js file. (Most of the critical functionality is in the comments so I won't go into more detail here.)

const { KJUR, KEYUTIL } = require('jsrsasign')
const { readFile } = require('jsrsasign-util')
const path = require('path')

const fromBase64Url = (str) => Buffer.from(str, 'base64url').toString()

const jwtSecret = process.env.JWT_SECRET
const publicKey = KEYUTIL.getKey(readFile(path.join(__dirname, '..', '..', 'certs', 'pubkey.pem')).replace(/[\n\r]+/g, ''))

const validate = function(req, res, next) {
  // Get the token from the Authorization header.
  const token = req.headers['authorization'].replace('Bearer ', '')

  // Alternatively, you can take it from a cookie; here we're looking for one called "jwt".
  // const cookies = req.headers.cookie.split('; ')
  // const token = cookies.find(c => /^jwt=/.test(c)).split('=')[1].trim()

  // Get the token header, payload, and signing algorithm used.
  const [ header, payload ] = token.split('.')
  const { alg } = JSON.parse(fromBase64Url(header))

  let validationComponent = null,
      isValid = false

  try {
    if (/^HS/.test(alg)) {
      // HSxxx algorithms use a shared secret.
      validationComponent = jwtSecret
    } else if (/^[REP]S/.test(alg)) {
      // RSxxx, ESxxx, and PSxxx algorithms all use a public key.
      validationComponent = publicKey
    } else {
      // Those are the only options; if another one was specified, throw an error.
      console.log(`Invalid algorithm specified: ${alg}`)
      res.status(501).send('Not Implemented')
    }
  } catch (e) {
    console.log(e)
    res.status(500)
  }

  // Validate the JWT using the jsrsasign library.
  isValid = KJUR.jws.JWS.verifyJWT(token, validationComponent, { alg: [alg] })

  if (isValid) {
    // Only if the signature is valid, decode the payload and add it to the request.
    req.payload = JSON.parse(fromBase64Url(payload))
    next()
  } else {
    // If the signature is invalid, abort the request with a 401.
    res.status(401).send('Unauthorized')
  }
}

module.exports = validate

Note that for the asymmetric algorithms (basically anything other than HMAC SHA) we need a public key. I chose to add them in a certs directory outside of the Express server's src folder:

For simple testing purposes, I went to https://jwt.io/ and changed the "Algorithm" dropdown to RS512. Towards the bottom of the screen, in the "Verify Signature" area, they include both the public and private keys used to sign their sample JWT. I simply copied both into the privkey.pem and pubkey.pem files you see above.

The middleware here is aware of both the shared secret key and the public key. When invoked, it parses the JWT from whatever part of the request has the JWT, validates it, and if successful, stores the decoded payload in the request. If validation fails for any reason, the middleware cancels the request.

The last thing we need to do is add the middleware to a route. Back in src/index.js, let's create a new API route and protect it with our JWT middleware:

//...
const bodyParser = require('body-parser')
const validate = require('./middleware/Validate.js')

// ...
app.use(cors())
app.use(bodyParser.json())

app.post('/api/validate', validate, (req, res) => {
  res.json(req.payload)
})
//...

We import the middleware from the file we just created, then supply the method as the second argument in our route handler for /api/validate. This will ensure that the middleware is invoked before any code in the handler.

To test, we can use Postman to re-use requests, save token values, etc.; but just for a quick test it's easy to use curl on the command line. Make sure you start your server with node src/index.js, then run the following curl command:

curl -X POST http://localhost:3000/api/validate -H "Authorization: Bearer [token]"

Make sure to replace [token] with a token from jwt.io. If everything is wired up properly, you should get back the payload of the token you sent in the header.

$ curl _X POST http://localhost:3000/api/validate -H "Authorization: Bearer [token]
{"sub":"1234567890","name":"John Doe","admin":true,"iat":1516239022}

Putting it All Together

Now that you have a functioning middleware, you can build out other routes that require authorization. Try creating another API route that returns some other piece of static data, for example using the name portion of the payload in the response (eg. Hello {name}!). Similar to Part 1, perhaps you can update the middleware to add elements from the payload as request headers and then dispatch the request to https://httpbin.org/anything to inspect the final request.

The concept of an inline token validator doesn't have to stop with Express, either. Most modern web frameworks, such as Next.js or Nuxt, have their own concept of middleware. With just a few modifications, this concept can be applied to those frameworks to provide much richer front-end experiences.

Check It Out

The code for this Express server with middleware is on my GitHub at https://github.com/tmountjr/express-jwt. Feel free to clone it, play around with it, etc.!

Zero Trust at the Edge (part 1)

Tom Mount — Mon, 03 Feb 2025 21:11:33 +0000

Using JSON Web Tokens to Validate Requests

Filter your traffic as far away from your origin as possible.

JSON Web Tokens (JWTs) have exploded in popularity over the last few years, and with good reason: implemented correctly, a JWT system can ensure that requests are authorized at every point in the journey from a user's browser to your origin server. A JWT is simply a JSON payload transmitted across the internet along with an encrypted signature that allows the receiver to verify that the payload has not been tampered with.

In Part 1 of this series, we'll review what a JSON Web Token is; how tokens are generated and signed; and how, when, and by whom the tokens should be verified. In Part 2, we'll look at a simple Express server that both signs and validates JWTs. In Part 3, we'll take JWTs one step further and explore JSON Web Key Sets (JWKS).

Defining the Terms

The JWT is made up of three components: the payload is a cleartext JSON object transmitted with a signature (a cryptographically generated representation of the payload) and a header that identifies the type of signing or encryption used to generate the signature. These three components are sent in a single bundle (the token) to the receiving server; the server must then validate the signature from the token before it can trust any claims (the JSON keys) in the payload. Once verified, the server can treat the payload as authoritative information. At any point in the transmission process, any system with simple cryptographic capabilities can validate the signature of the payload and halt the request if the signature does not match.

Source: https://supertokens.com/blog/what-is-jwt

Generating the Token

A token is generally created first at the server. This may happen after a user successfully logs into a service, completes an authentication challenge, etc. The server creates the payload based on the business requirements. Generally, the payload will at minimum include the following claims:

iat: the timestamp of the token creation;
exp: the timestamp when the token will expire.

Other common claims include the sub (the subject of the claim, usually a username or user ID), iss (the issuer of the token), and aud (the audience for whom the token is meant). Any other information can be included as long as it can be serialized into JSON. Note, however, that the payload is sent in clear-text and should not contain any secret information like passwords, PII, etc.

The server will choose an appropriate header. The header should always include an alg claim with a specific value representing the algorithm used to generate the signature. Some algorithms (like HMAC SHA) only require a secret key on the server to generate; others, like RSA SHA, require a signed public/private key pair rather than a simple secret value. Regardless of the algorithm used, the signing data must be kept secret, as a third party with knowledge of the secret key or a copy of the private key could easily generate valid JWTs and spoof authentication.

The signature is generated based on the algorithm chosen. The header and payload are both base64-encoded (separately) and joined with a dot ([encoded_header].[encoded_payload]). This joined text is sent through a hashing function that calculates the hashed and encrypted value of the header and payload; this signature is then appended with a dot. The final format of the token is [encoded_header].[encoded_payload].[signature].

Sending the Token

Generally, the token is returned as a set-cookie header so that the token can be sent with every subsequent request to the server. The token must be revalidated on each request to ensure that the individual request is authorized. One of the most common use cases for JWTs is around authentication: once a user has successfully verified their credentials, the server sends a JWT back with the response that is then used to continually verify that the user is authorized to make those requests. This allows for a more stateless application.

Validating the Token

JWTs should ALWAYS be validated by the origin server; this prevents any sort of man-in-the-middle attack that might occur between a token being validated at the outer edge of the application perimeter and the token being received by the origin server. But there is still value in validating JWTs at the outermost edge of the application. Validation before the origin can help prevent a supply-chain attack against the token. Tokens that are known to be bad can be rejected before going very far into the application stack, sometimes at the very first node that sees the token. And, depending on the application architecture, some requests can be handled without going to the origin if the token has been validated at the edge. In the final two cases, the end result is less traffic going back to the origin server and potentially a more performant application.

Tokens signed with RSA (an asymmetric algorithm) can be validated merely with a public key, which means that the private key used to sign the payload can remain on the signing server and does not need to be stored at any other point where the token would be validated. Tokens using HMAC SHA signing (a symmetric algorithm) will require the secret value in order to generate a comparison hash. In either case, the process is fundamentally the same: the verifying party splits the token into its components (header, payload, and signature), and passes the joined header and payload through a verification algorithm, with either the public key or the shared secret key as an additional argument. The verification algorithm will check to make sure that the header and payload given to it match the signature. If so, the claims in the payload can be trusted; if not, the claims have likely been tampered with and should not be trusted.

Simplified Real World Use Case

I worked on a project a few years ago for a company that wanted to spin up "companion" websites for live-streamed conferences. Attendees at these conferences would have limited access to certain content throughout the site based on the tier ticket they had purchased, for example, gold, silver, or bronze packages. They were expecting tens of thousands of visitors to a WordPress site and wanted to optimize the cache hit capability for as many requests as possible. Two problems immediately leaped out:

Asking WordPress to handle ten thousand simultaneous authorization requests is asking WordPress to crash.
Authenticated content is typically not cached by any CDN to prevent one user's experience on a given page from being cached for all users who visit that page.

JWTs provided an elegant solution to both. Rather than have WordPress handle the user logins, we created a custom authentication page in Google Firebase and redirected new users there. Once they logged in, Firebase returned a JWT with only one critical custom claim: the user's membership level. The WordPress server would be responsible for validating the token, and as long as it was valid, it would impersonate a generic user at that ticket tier, generate the appropriate content for the given URL and membership level, and send the response with a custom response header with that membership level. The caching server would use the custom header as part of a custom cache key for that URL, enabling gold, silver, and bronze versions of all URLs to be cached simultaneously. For subsequent requests, the CDN would first validate the JWT, and if it was valid, it would add the ticket tier into the cache key to look up the unique combination of URL and tier and return the appropriate version of that URL. Only if that combination of URL and tier did not exist would it dispatch the request to WordPress.

Because users could not generate their own JWT to give them access to the content (a signed JWT could only come from Firebase) nor could they change their stored JWT to give them a higher level of access (because the signature would be invalid), this allowed us to serve authenticated content via the CDN and keep the amount of traffic going back to WordPress to a minimum, once the cache had been populated. We recorded a 99% cache hit ratio (the ratio of the number of requests served from the CDN's cache vs. the total number of requests received by the CDN) through the duration of the first event where we implemented this stack, and NewRelic showed that the WordPress instance barely received any traffic at all once the cache had been sufficiently warmed.

DEV Community: Tom Mount

Zero Trust at the Edge (part 4)

Incorporating JWKS into your JWT Validation Middleware

Recap

Important Warning ⚠️

Generating the JWKS

Signing a JWT

Hosting the JWKS

Reading the JWKS and Validating the JWT

Testing everything together

Wrapping Up the Series

Zero Trust at the Edge (part 3)

Working with JSON Web Key Sets

Recap

Defining the Terms (mostly review)

Scaling Up

Accessing the JWKS

Special Consideration: Generating the Keypair

Wrapping it Up

Further Reading

Zero Trust at the Edge (part 2)

Creating and Validating your own JSON Web Tokens

Recap

Validation

Putting it All Together

Check It Out

Zero Trust at the Edge (part 1)

Using JSON Web Tokens to Validate Requests

Defining the Terms

Generating the Token

Sending the Token

Validating the Token

Simplified Real World Use Case

Further Reading