JWTs Explained: Structure, Claims, and Debugging

Overview

A JSON Web Token (JWT) is a compact way to carry claims between parties. The common form has three Base64URL segments separated by dots: header, payload, and signature. The header describes the algorithm; the payload holds claims; the signature binds them so tampering can be detected when verification is implemented correctly.

JWTs are convenient for APIs and session-like flows, but they are easy to misuse. A decoded payload is not proof of authenticity—only a successful signature (or encryption) verification is. Treat `none` algorithms, weak secrets, and oversized tokens as production risks, not curiosities.

When debugging, decode with Dockzio’s JWT Decoder to read header and claims, use Base64 Encode & Decode if you need to inspect a single segment, and remember that Hash Generator helps you understand digest building blocks—not replace proper JWT verification libraries.

Step-by-step

1. 1. Read the three segments separately

   Split on `.`. The first segment is a JSON header (typ/alg). The second is a JSON payload of claims. The third is the signature (or message authentication code) bytes, Base64URL-encoded.

   Decode header and payload to JSON for inspection. Do not expect the signature segment to be meaningful JSON.

2. 2. Understand registered claims

   `iss` (issuer), `sub` (subject), `aud` (audience), `exp` (expiration), `nbf` (not before), and `iat` (issued at) are common registered claims. Applications add private claims for roles, tenant IDs, and similar data.

   Always check time claims in the verifier, not only in your head while reading a decoded payload.

3. 3. Separate “decode” from “verify”

   Anyone can decode an unencrypted JWT. Verification checks the signature with the correct key and algorithm, then enforces claims. Debugging UIs decode so you can see content; your server must verify before trusting it.

   Never implement crypto from scratch for production auth. Use a maintained JWT library and pin allowed algorithms explicitly.

4. 4. Connect signatures to hashing concepts

   HMAC-based JWTs (for example HS256) combine a secret with a hash-based MAC over `header.payload`. Asymmetric algorithms sign with a private key and verify with a public key.

   A general hash generator is useful for learning digests, but JWT verification also includes encoding details and algorithm agility rules. Prefer purpose-built verification.

5. 5. Debug failures systematically

   If a token fails: confirm it is not truncated, check `exp`/`nbf` clock skew, confirm the verifier uses the same algorithm and key as the issuer, and ensure you are not mixing Base64 with Base64URL.

   Paste the token into the JWT Decoder to read claims, then fix the verification configuration—not the token—unless you are the issuer recreating it.

6. 6. Keep tokens small and purposeful

   Put stable authorization data in claims; keep bulky profile data behind an API. Large JWTs waste bandwidth and can hit header size limits. Prefer short lifetimes and rotation strategies appropriate to your threat model.

Common mistakes

• Trusting decoded claims without verification. A modified payload still “decodes.” Without signature checks, an attacker can mint claims. Decode for debugging only.
• Storing sensitive secrets in the payload. Unencrypted JWT payloads are readable by anyone who obtains the token. Do not put passwords, raw PANs, or unnecessary PII in claims.
• Accepting alg=none or unexpected algorithms. Algorithm confusion attacks exploit verifiers that trust the header’s `alg` blindly. Allow-list algorithms in configuration.
• Confusing opaque session IDs with JWTs. Not every Bearer token is a JWT. If there are not three dot-separated segments, use the right introspection path instead of a JWT decoder.