Decoding JSON Web Tokens (JWT): Architecture, Signature Verification & Common Security Pitfalls

JSON Web Tokens (JWTs) underpin modern distributed authentication across microservices, single-page applications, and mobile APIs. Yet, despite their ubiquity, they remain one of the most misunderstood and insecurely implemented specifications in web development. From junior engineers assuming tokens are encrypted to senior architects mishandling key rotation, JWT security blunders regularly expose production environments to catastrophic privilege escalation attacks.

Worse still is the daily debugging workflow: developers routinely copy sensitive production tokens containing user identifiers, roles, and internal metadata, pasting them into public third-party formatters that log, index, or cache payloads on remote servers. In this comprehensive engineering guide, we dissect the internal anatomy of RFC 7519, analyze common cryptographic vulnerabilities, and demonstrate how to safely inspect tokens using the 99tools In-Browser JWT Debugger without transmitting secrets over the wire.

The Anatomy of a JSON Web Token (RFC 7519)

At its core, a compact serialized JWT is simply a string composed of three distinct sections separated by dots (.):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYiLCJuYW1lIjoiQWxleCBNb3JnYW4iLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3NDkyNjQwMDB9.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

These three parts correspond to the Header, the Payload, and the Signature.

┌─────────────────────────────────┐
│  HEADER: Algorithm & Token Type │ ──► Base64UrlEncode({ "alg": "HS256", "typ": "JWT" })
└─────────────────────────────────┘
                 │  [ . ]
┌─────────────────────────────────┐
│  PAYLOAD: Claims & Metadata     │ ──► Base64UrlEncode({ "sub": "usr_99", "role": "admin" })
└─────────────────────────────────┘
                 │  [ . ]
┌─────────────────────────────────┐
│  SIGNATURE: Integrity Seal      │ ──► HMACSHA256(Base64Url(Header) + "." + Base64Url(Payload), secret)
└─────────────────────────────────┘
	

1. The Header: Metadata & Algorithm Declaration

The header specifies the token type and the cryptographic algorithm used to generate the signature:

{
  "alg": "HS256",
  "typ": "JWT"
}

Common signing algorithms include symmetric HMAC algorithms (HS256, HS384, HS512) and asymmetric public/private key algorithms (RS256, ES256, EdDSA).

2. The Payload: Registered, Public, and Private Claims

The payload contains the statement claims about the user or entity. The IETF specification establishes several standard registered claims:

• iss (Issuer): The identity of the authority that issued the token (e.g., https://auth.99tools.in).
• sub (Subject): The unique identifier of the principal (e.g., user ID).
• aud (Audience): The recipient microservice or system the token is intended for.
• exp (Expiration Time): Unix timestamp beyond which the token must be rejected.
• nbf (Not Before): Unix timestamp before which the token must not be accepted.
• iat (Issued At): Timestamp when the token was signed.

3. The Signature: Mathematical Integrity Verification

The signature proves that the sender of the JWT is who it claims to be and that the message was not tampered with along the wire. When using HMAC-SHA256, the signature is computed as:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  server_secret_key
)

Critical Architectural Misconceptions

Misconception 1: “JWTs Are Encrypted”

Standard JSON Web Signatures (JWS) are signed, not encrypted. The header and payload are merely Base64Url-encoded. Anyone who intercepts the token can decode the payload in a split second using tools like atob() or the 99tools Base64 Converter.

Golden Rule: Never store sensitive credentials, database passwords, unhashed tokens, or sensitive Personally Identifiable Information (PII) inside a standard JWT payload. If encryption is required, you must use JSON Web Encryption (JWE).

Misconception 2: “Pasting Tokens into Public Debuggers is Safe”

Developers frequently copy active Bearer tokens from their browser network inspector and paste them into random online debugging utilities. Many of these portals pass the token string to backend API endpoints for server-side parsing. If the site operator logs request payloads or suffers a database breach, your production access tokens are compromised.

The 99tools JWT Debugger mitigates this risk by performing all Base64Url string splits and JSON parsing completely on the client side. No data is ever transmitted to a backend server.

Top 3 JWT Security Vulnerabilities in Production

1. The “None” Algorithm Attack

RFC 7519 allows for unsecured tokens where "alg": "none". Early JWT parsing libraries naively read the alg header from the untrusted incoming token. If an attacker modified an existing token to change "role": "user" to "role": "admin", set "alg": "none", and stripped the signature, vulnerable backends verified the token as valid.

Prevention: Hardcode acceptable algorithms in your server verification logic. Never rely on the token’s header to determine what algorithm to use:

// Correct verification in Node.js
jwt.verify(token, publicKey, { algorithms: ['RS256'] }); // Explicitly whitelist algorithms!

2. The Asymmetric-to-Symmetric Key Confusion Attack

When an API uses RSA (RS256), the server verifies tokens using a public key. In a key confusion attack, an attacker obtains the server’s public key (which is publicly accessible via JWKS endpoints), crafts a fraudulent token, changes the algorithm to symmetric HS256, and signs the token using the server’s public key string as the HMAC shared secret.

If the backend does not enforce algorithm separation, the library executes HMAC-SHA256(data, publicKeyString) and accepts the malicious admin token as legitimate!

3. Weak Secrets and Brute-Force Attacks

When using symmetric HMAC (HS256), developers frequently use short or predictable secret strings like "supersecret" or "my-company-jwt-key". Because JWT verification is mathematically deterministic and fast, modern GPU hash crackers (such as Hashcat) can brute-force weak secrets at billions of guesses per second.

Prevention: Always use cryptographically random secrets with at least 256 bits of entropy generated via the 99tools Password & Secret Generator.

Comparison: Signed JWT vs. Encrypted JWE vs. Server Sessions

Best Practices for Engineering Teams

1. Keep Payloads Lean: Tokens are sent with every single HTTP request via the Authorization: Bearer header. Storing extensive user claims inflates network payload sizes and impacts page load performance.
2. Use Short Expiration Windows: Access tokens should expire in 10 to 15 minutes. Pair short-lived access tokens with long-lived, securely stored Refresh Tokens (HttpOnly, Secure cookies).
3. Enforce Audience and Issuer Validation: Always validate that the iss matches your authentication provider and aud matches the specific service processing the request.
4. Debug Securely: Never paste sensitive production tokens into arbitrary third-party web debuggers. Bookmark the client-side 99tools In-Browser JWT Debugger for safe, offline-capable token inspection.

Frequently Asked Questions

Karen Johnson

Senior Systems Architect & Technical Writer at 99tools. Specializing in WebAssembly, browser performance, networking diagnostics, and privacy-first web utilities.