The Complete Guide to JSON Web Tokens (JWT): Header, Payload, Signature & Security Best Practices

Introduction to JSON Web Tokens (RFC 7519)

JSON Web Tokens (JWT) are a compact, URL-safe means of representing claims to be transferred between two parties. Defined in RFC 7519, JWTs have become the standard mechanism for stateless authentication, federated single sign-on (SSO), and API authorization across modern microservices.

Unlike stateful session identifiers stored in centralized data stores like Redis or relational databases, a JWT is self-contained. It packages identity attributes, authorization scopes, and an expiration timestamp directly into an encoded string that any client or backend can verify mathematically without an expensive database lookup.

Anatomy of a JSON Web Token

Every standard JWT consists of three separate parts delimited by period (.) characters: the Header, the Payload, and the Signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsZXgiLCJpYXQiOjE1MTYyMzkwMjJ9.4z9rW...

1. The Header

The header typically contains two fields: the cryptographic algorithm used (such as HS256 or RS256) and the token type (JWT):

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

This JSON object is Base64Url-encoded to form the first part of the token string.

2. The Payload (Claims)

The payload contains statements about an entity (typically, the authenticated user) and additional metadata known as claims. Claims fall into three categories:

• Registered Claims: Predefined recommended claims including iss (issuer), exp (expiration time), sub (subject), and aud (audience).
• Public Claims: Custom claims defined by application developers or registered in the IANA JSON Web Token Registry to avoid collisions.
• Private Claims: Custom claims agreed upon between sharing parties, such as user roles or tenant IDs.

{
  "sub": "user_98745",
  "name": "Jane Developer",
  "role": "admin",
  "exp": 1799884800,
  "iss": "auth.devdeskapp.com"
}

3. The Signature

The signature verifies that the sender of the JWT is who it claims to be and ensures that the message was not tampered with along the wire. To generate the signature for an HMAC-SHA256 token, the system combines the base64-encoded header and payload with a shared secret:

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

Critical JWT Security Pitfalls & How to Avoid Them

1. The "None" Algorithm Exploit

Early JWT libraries allowed the header {"alg": "none"}, instructing backends to accept tokens without verifying a cryptographic signature. Malicious actors could forge arbitrary administrator tokens simply by setting alg to none and stripping the signature. Mitigation: Always enforce an explicit algorithm whitelist in your verification middleware (e.g., allow only RS256 or HS256) and reject any token claiming alg: none.

2. Weak HMAC Secrets

Because tokens are public and sent across every client request, attackers can capture a valid token and run offline brute-force attacks against the HMAC secret using tools like Hashcat or John the Ripper. If your secret is short (e.g., secret123), it will be cracked in seconds. Mitigation: Always use at least 256 bits (32 bytes) of cryptographically random entropy for symmetric secrets, or migrate to asymmetric RSA/ECDSA key pairs.

3. Storing Sensitive Data in Unencrypted Claims

A fundamental misconception among junior engineers is that JWTs provide confidentiality. Standard JWTs are signed, not encrypted. Any user or intermediary can decode the Base64Url string in their browser console or via our JWT Parser and view the claims in cleartext. Never store passwords, API secrets, or PII (Personally Identifiable Information) in a standard JWS.

Summary Checklist for Production JWTs

1. Keep token lifetimes short (10–15 minutes) and pair them with secure, rotating refresh tokens stored in HTTP-only, SameSite cookies.
2. Always validate the exp (expiration), nbf (not before), and iss (issuer) claims on every single request.
3. Use asymmetric cryptography (RS256 / ES256) when microservices only need to verify tokens issued by a centralized identity provider.