A correct JWT verifier does eight things. Most production verifiers I have read do four or five of them. The other three or four get skipped because the library defaults aren't loud about them, the docs gloss over them, or someone copied a "it works" snippet from Stack Overflow circa 2018.
Here is the full eight-check list, what each one prevents, and what it looks like to implement them with structured error codes — the kind that survive a midnight 401 incident with a clear remediation path.
1. Signature
Verify the cryptographic signature against a public key from the issuer's JWKS endpoint, scoped to the kid (key id) in the JWT header.
Fails if: signature is forged, key has been rotated and your cache is stale, or the JWKS endpoint is unreachable. The bug class is anything that lets a token through without signature verification — the alg=none family, or libraries that accept the token's own alg claim instead of an explicit allowlist.
Failure code: SIGNATURE_INVALID or KID_NOT_FOUND.
2. Issuer (iss)
Match the token's iss claim against your expected issuer URL, exactly. No prefix-substring tricks. No "starts with https://login." — that lets https://login.attacker.com through.
Fails if: the token came from a different issuer, the issuer rebranded its hostname (acquisition, region split), or your config has a typo. The third case is the silent failure mode — your tests pass against your test issuer, but production talks to a different one and you never noticed.
Failure code: ISSUER_MISMATCH.
3. Audience (aud)
Match the token's aud claim against your service's expected audience, exactly. The audience names which service the token is intended for. Skipping this check is the difference between "we have authentication" and "we have authorization" — without it, a token issued for api://billing will authenticate against api://reporting because both trust the same issuer.
Fails if: the token was issued for a different service, or your config doesn't pin the audience at all. The "doesn't pin" case is the most common production bug. New endpoints get added; the audience check stays missing.
Failure code: AUDIENCE_MISMATCH.
4. Algorithm allowlist (alg)
Specify allowed algorithms explicitly. Reject everything else. If you only ever issue HS256, your verifier must reject HS512, RS256, PS512, none, and every other algorithm — even though they are valid JWT algorithms.
This is the check that prevents the alg=none bug class and the RS256→HS256 confusion attack (where an attacker re-signs a token with the public key as if it were a shared secret). Both attacks are eleven years old and still in production.
Fails if: the token's alg is not in your allowlist, or the allowlist is too permissive (e.g., includes both RS256 and HS256 with the same key material).
Failure code: ALGORITHM_NOT_ALLOWED.
5. Time (exp, nbf, iat)
Check that:
-
exp(expiration) is in the future, -
nbf(not before) is in the past or absent, -
iat(issued at) is plausible (not 5 years ago, not in the future).
Allow a small clock skew (typically 60 seconds) to handle the inevitable NTP drift across nodes. Larger skew is a smell — it usually means someone hit "valid token rejected because clock drift" once and over-corrected.
Fails if: the token is expired, not yet valid, or backdated implausibly.
Failure code: TOKEN_EXPIRED, TOKEN_NOT_YET_VALID, IAT_IMPLAUSIBLE.
6. Required claims
Beyond the standard claims, your service may require certain custom claims to be present. A sub (subject) is almost always required. A tenant_id claim might be required for multi-tenant systems. A scopes claim might gate access to specific endpoints.
Required-claim checks are not built into JWT libraries — they are a contract between your verifier and your issuer. The contract has to be written down somewhere, and the verifier has to enforce it.
Fails if: a required claim is missing or has the wrong type.
Failure code: REQUIRED_CLAIM_MISSING, CLAIM_TYPE_MISMATCH.
7. JWKS reachability
The verifier needs to fetch the JWKS endpoint to get public keys. If the endpoint is unreachable — DNS failure, certificate expired, 5xx response, network partition — you have a binary choice: fail closed (reject all tokens until JWKS is fetchable) or fail open (accept tokens with cached keys, eventually run out of cache).
Most libraries fail open. That means a JWKS endpoint outage on the issuer side gives you minutes-to-hours of "tokens still verify, but we have no idea if they're still valid keys." This is fine for short outages. It is a security incident for long ones.
Fails if: JWKS endpoint returns 5xx, has TLS issues, or DNS-resolves to something unexpected.
Failure code: JWKS_UNREACHABLE, JWKS_TLS_ERROR, JWKS_DNS_FAILURE.
8. OIDC discovery integrity
If you trust the OIDC discovery document (/.well-known/openid-configuration) to tell you the issuer, JWKS URI, and supported algorithms, you need to verify that the discovery document is consistent with what your verifier expects. The most common drift modes:
- The issuer changes hostnames. Tokens carry the new hostname, your verifier expects the old one.
- The supported algorithms change. The issuer deprecates RS256 in favor of ES256.
- The JWKS URI moves. Your cached JWKS goes stale because the polling URL no longer returns keys.
Pin the discovery document. Re-validate against it on every deploy, not on first call.
Fails if: discovery document fields don't match your verifier's pinned config, or have moved without your config catching up.
Failure code: DISCOVERY_DRIFT, JWKS_URI_MISMATCH, ALG_POLICY_DRIFT.
What this looks like in production
A correct verifier returns structured findings, not boolean true/false. For each check, emit:
{
"valid": false,
"statuses": {
"signature": "pass",
"issuer": "pass",
"audience": "fail",
"algorithm": "pass",
"time": "pass",
"required_claims": "pass"
},
"findings": [
{
"code": "AUDIENCE_MISMATCH",
"severity": "high",
"message": "Token audience 'api://reporting' does not match expected 'api://billing'",
"remediation": "Update verifier config to accept 'api://reporting' OR reject this token"
}
]
}
The structured output is what makes JWT bugs debuggable. A boolean rejection tells you a token failed. A structured rejection tells you which check failed, why, and what to do about it.
Skip-the-implementation option
If you do not want to wire all eight checks yourself, this is what jwtshield's /v1/validate/jwt endpoint runs on every call. Pass a token and a policy; get a structured VerifyResult back. The endpoint runs all eight checks every time, with consistent failure codes across all your services.
In CI, drop the GitHub Actions wrapper into any workflow:
- uses: redbullhorns/jwtshield-ci@v1
with:
issuer: https://login.example.com
audience: api://backend
allowed-algs: RS256
fail-on-severity: high
api-key: ${{ secrets.JWTSHIELD_API_KEY }}
Five lines. Eight checks. Structured findings. Free tier covers 200 verifies per month.
Discuss on: Hacker News · dev.to · Hashnode · Mastodon
Related:
