Understanding JWT: structure, claims and safe verification

A JWT is three base64url-encoded segments joined by dots: header, payload, signature. Nothing in the header or payload is encrypted — it is only encoded, so anyone with the token can read its contents.

The three parts

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMiLCJleHAiOjE3MDAwMDAwMDB9.signature

• **Header** — the algorithm (`alg`) and token type. `{"alg":"HS256","typ":"JWT"}`.
• **Payload** — the claims: arbitrary key-value pairs plus a handful of registered ones.
• **Signature** — computed over the header and payload, proving they were not modified by anyone who does not hold the signing key.

Registered claims worth knowing

• `sub` — subject, usually a user ID.
• `iat` — issued-at, a Unix timestamp.
• `exp` — expiry, also Unix time. A token past this is invalid regardless of signature validity.
• `nbf` — not-before, the token is invalid until this time.
• `iss` — issuer, who created the token.
• `aud` — audience, who the token is intended for.

None of these are enforced by the format itself — they are conventions the verifying party must check explicitly.

Decoding is not verifying

Pasting a token into a decoder and reading the payload tells you what the token claims, not whether it is genuine. Verification requires:

1. Recomputing the signature with the same algorithm and the correct key. 2. Comparing it to the signature segment using a constant-time comparison. 3. Checking `exp`, `nbf`, and usually `iss`/`aud` against expected values.

Skipping step 1 and only checking the payload's claims is a bug that has bitten real production systems — an attacker can forge any payload they like as long as nobody validates the signature.

HS256 vs RS256

• **HS256** — HMAC-SHA256 with a single shared secret. Whoever can verify a token can also mint one, so the secret must stay server-side only.
• **RS256** — RSA signature with a private/public key pair. The private key signs, the public key verifies. This is the right choice when a third party needs to verify tokens without being trusted to issue them.

A well-known vulnerability class is accepting `alg: none` or letting an attacker switch `RS256` to `HS256` and sign with the (public) verification key as if it were an HMAC secret. Always pin the expected algorithm on the verifying side instead of trusting the `alg` field in the token.

Sizing and content

JWTs travel in headers and sometimes URLs, so keep the payload small — user ID, roles, expiry. Do not put anything you would not want logged in plaintext, since the payload is trivially decodable, and avoid putting large or frequently-changing data in there since the token has to be reissued whenever it changes.

A practical checklist

• Set a short `exp` (minutes to a few hours) and use a refresh mechanism for longer sessions.
• Validate `alg` server-side against an allow-list, never trust the header.
• Store secrets and private keys outside source control.
• Prefer RS256/ES256 when the token crosses a trust boundary you do not fully control.
• Never store JWTs containing sensitive claims in `localStorage` if XSS is a realistic risk — an httpOnly cookie is safer for session tokens.