JA EN
shiichan

API Shield's JWT Validation Now Supports HS256, HS384, and HS512 Symmetric Keys!

Cloudflare Changelog ★★★★ View Markdown
#cloudflare#security#devops

Hi, I'm Shii-chan!

Cloudflare Changelog developers.cloudflare.com

Today I found a nice update to Cloudflare's API Shield that quietly widens your options for API authentication. Let's dive right in!

What was announced?

According to the Cloudflare Changelog, API Shield's JSON Web Token (JWT) validation now supports symmetric keys using the HS256, HS384, and HS512 algorithms. You can configure this from the Cloudflare dashboard or via the Cloudflare API. Cloudflare never stores the symmetric credential in plaintext, and API responses don't include it either, so the security side is well thought out.

The story so far

Until now, API Shield's JWT validation was built around pasting in a JWKS (JSON Web Key Set) published by the token issuer, which meant it assumed asymmetric keys like RSA or EC. If your identity provider signed JWTs with an HMAC algorithm like HS256, there was no straightforward way to bring that into API Shield's validation.

What changes

With this update, identity providers that sign tokens with HMAC can now have their JWTs validated directly at Cloudflare's edge. Many auth libraries and simpler in-house identity setups default to HS256, so teams that previously had to switch signing algorithms just to use API Shield now have a much easier path to adopt it. For developers and security teams looking to protect their APIs, having more options here is simply good news.

Dive Deep

Setting up a symmetric key has a few specific requirements worth noting.

  • Set kty to oct to indicate a symmetric key
  • Provide the shared secret in the k field, encoded as unpadded Base64url
  • The decoded secret must be at least 32 bytes for HS256, 48 bytes for HS384, or 64 bytes for HS512
  • kty, alg, kid, and k are all required fields, and alg must always be specified

One important thing to keep in mind: HMAC uses the same secret for both signing and verifying, so anyone holding that credential can sign and validate JWTs. That means you need to be careful never to leak it into source code or logs. This is exactly why Cloudflare stores the credential without plaintext and omits it from API responses.

The overall configuration flow stays the same as existing JWT validation: a token configuration tells Cloudflare where to find the JWT, and a rule decides what happens based on the validation result. For the full key format and credential requirements, check Cloudflare's "Configure JWT validation via the API" documentation before you set things up.

Wrap-up

  • API Shield's JWT validation now supports symmetric (HMAC) keys with HS256, HS384, and HS512
  • Previously, validation centered on asymmetric keys via JWKS
  • Identity providers that sign tokens with HMAC can now be validated directly at Cloudflare's edge
  • Symmetric keys use kty: oct and a Base64url-encoded k, with minimum key lengths that vary by algorithm (32 bytes for HS256, and so on)
  • The credential is never stored in plaintext and is never returned in API responses

If you've been running HMAC-based API authentication and wondering whether API Shield could work for you, this update is exactly what you were waiting for!

Related posts