JWT: anatomy, signature and security

The three parts of a JWT

A JWT is a string with three blocks separated by dots: `header.payload.signature`. Each block is a JSON object encoded in base64url, the RFC 4648 §5 variant that swaps `+` for `-`, `/` for `_` and drops the `=` padding, precisely so it fits in URLs and HTTP headers without escaping. The header states which algorithm signs the token (`alg`) and the type (`typ`). The payload carries the claims, the assertions about the user or session. The signature is what binds those first two to a secret key.

// Um JWT real (exemplo didático público, secret = "your-256-bit-secret")
// A real JWT (public didactic example, secret = "your-256-bit-secret")

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9          ← header
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ   ← payload
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c   ← signature

// Header decodificado / decoded:
{ "alg": "HS256", "typ": "JWT" }

// Payload decodificado / decoded:
{ "sub": "1234567890", "name": "John Doe", "iat": 1516239022 }

Signed, not encrypted

The format you see day to day is a JWS, JSON Web Signature, defined by RFC 7515. "Signed" means the issuer computes an authentication code over `header.payload` using a key, and the verifier recomputes it to confirm nothing changed. If an attacker alters a single character of the payload, the signature stops matching. But note: a signature is not a cipher. The content is still plaintext, merely encoded. There is an encrypted JWT, the JWE, from RFC 7516, but it is rare, has five parts instead of three and is another story. When someone says "JWT", they almost always mean a readable JWS.

JWS (RFC 7515)

Signed token. Proves integrity and authorship; the content is readable. The everyday JWT.

JWE (RFC 7516)

Encrypted token. Here the content really is unreadable without the key. Five parts, rarely used.

JWA (RFC 7518)

The catalog of algorithms (HS256, RS256, ES256, none…) the header may declare in `alg`.

The registered claims

The payload is a free JSON object, but RFC 7519 (§4.1) reserves seven claim names with standardized meaning. None of them is mandatory, the RFC itself says "none of the claims defined below are intended to be mandatory to use or implement in all cases". That surprises people who assume a JWT always has an expiry. It does not: a token with no `exp` is valid forever, until the key rotates. It is on you to require the claims your application needs and to validate every one of them.

The three time claims, `exp`, `nbf`, `iat`, are seconds since 1 January 1970 (the Unix epoch). A correct verifier rejects the token if the current time is greater than or equal to `exp`, or less than `nbf`, allowing a small clock skew of a few seconds between servers. Validating `aud` and `iss` matters just as much: a token issued for service A must not be accepted by service B merely because the signature is valid. A valid signature answers "this issuer signed it"; it does not answer "this token was meant for me".

The classic attacks

Almost every JWT attack exploits the same root flaw: the library trusts the token’s header, which the attacker controls, to decide how to verify. RFC 8725 (JWT Best Current Practices, BCP 225) exists precisely to catalog these traps. Three of them show up again and again in real audits.

Notice the common thread: in all three, the server handed the attacker a decision that was the server’s to make. The single, cheap antidote is a server-side allowlist, of algorithm and of key, combined with validating the time claims, `aud` and `iss`. The JWT Decoder verifies an HMAC signature when you supply the secret, which helps you reproduce and understand the RS256/HS256 confusion in a safe place, without sending your token anywhere.

Revocation: the Achilles’ heel

The appeal of JWT is being stateless: the server keeps no session at all, it just checks the signature and trusts what is written. That is also its biggest flaw. A signed token is valid until `exp`, and there is no server-side record to "switch off". If the user logs out, gets banned or changes their password, the token already in their hands keeps working until it expires. There is no button that invalidates an issued JWT, unless you reintroduce state.

The two common ways out are shown above, and both cost something. The denylist hands the server back the state JWT wanted to drop; short tokens with refresh reduce the problem rather than remove it, at the price of more flow complexity. There is no free instant revocation in a genuinely stateless system, it is an engineering choice, not a config detail. If the HMAC secret leaks, the dilemma vanishes: you rotate the key and every token falls at once. Generate a long, random HS256 secret with the hash generator and guard it the way you would a master password.

Secure validation and when NOT to use JWT

• Validate `alg` against a server-side allowlist; reject `none` and any algorithm not on the list.
• Bind the key to the expected algorithm: an RSA key verifies RS256, never HS256. Never let the token pick the key type.
• Check `exp` and `nbf` (with a small clock skew) and verify `aud` and `iss` against the values your application expects.
• Never trust `kid`, `jku` or `x5u` to fetch the key; use a key set configured on the server.
• Use long, random secrets for HMAC; no dictionary words or short reused strings.
• Never put sensitive data in the payload, it is only base64url, readable by anyone.

With the security lesson done, here is the most honest and least-asked question: do you actually need JWT? For a user’s session in a web app with your own backend, the answer is almost always no. An opaque session cookie, a random id pointing to a session record on the server, is simpler and safer: revocation is deleting the row, there is no algorithm-confusion surface, no risk of leaking data in the payload and the cookie is tiny. JWT shines elsewhere: authorization across services, when several backends must validate the token without sharing a session store, in identity federation and in short-lived signed assertions. If your case is "the user logs in and browses my site", prefer the opaque session.