Understanding JWT Tokens: A Developer's Guide

What is a JWT?

A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe token format used to securely transmit information between parties as a JSON object. JWTs are widely used for authentication and authorization in modern web applications, particularly in Single-Page Applications (SPAs) and REST APIs.

Unlike session-based authentication where the server stores session data, JWTs are stateless — the token itself contains all the information needed to verify the user's identity, eliminating the need for server-side session storage.

JWT Structure

A JWT consists of three parts separated by dots (.):

header.payload.signature

// Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header

The header typically specifies the signing algorithm (e.g., HS256, RS256) and the token type:

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

2. Payload (Claims)

The payload contains claims — statements about the user and metadata. There are three types of claims:

• Registered claims: Standard fields like sub (subject), iat (issued at), exp (expiration).
• Public claims: Custom fields defined by the application (e.g., role, email).
• Private claims: Custom fields shared between specific parties.

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "[email protected]",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516242622
}

3. Signature

The signature is created by encoding the header and payload, then signing the result with a secret key (or private key for asymmetric algorithms):

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

The signature ensures that the token has not been tampered with. If anyone modifies the payload, the signature verification will fail.

Signing Algorithms

How JWT Authentication Works

1. User sends login credentials (username/password) to the server.
2. Server verifies credentials and generates a JWT containing the user's claims.
3. JWT is sent back to the client (usually stored in localStorage or an HTTP-only cookie).
4. Client includes the JWT in the Authorization: Bearer <token> header for subsequent requests.
5. Server verifies the JWT signature and extracts claims to authorize the request.

Security Best Practices

• Always set an expiration: Use short-lived tokens (15-60 minutes) with refresh tokens for long sessions.
• Use HTTPS: Never transmit JWTs over unencrypted connections.
• Don't store sensitive data in the payload: The payload is Base64-encoded, not encrypted. Anyone can decode it.
• Validate the algorithm: Always verify the alg header matches your expected algorithm to prevent algorithm confusion attacks.
• Use strong secrets: For HMAC algorithms, use a secret of at least 256 bits.
• Prefer HTTP-only cookies: Store JWTs in HTTP-only, Secure, SameSite cookies to prevent XSS attacks.

When to Use (and Not Use) JWTs

Use JWTs for:

• Stateless authentication in REST APIs
• Single Sign-On (SSO) across multiple services
• Information exchange between trusted parties

Avoid JWTs for:

• Storing session data that changes frequently (revocation is complex)
• Applications requiring immediate token revocation (use session-based auth instead)
• Passing large amounts of data (tokens become unwieldy)