JWTs Explained: Tokens vs. Sessions

The Anatomy of a JSON Web Token (JWT)

Where a session ID is an opaque, random string, a JWT (pronounced "jot") is a structured, self-contained token. It's a long string, but it's not random. It's composed of three distinct parts, separated by dots (.).

header.payload.signature

Let's examine each part.

As you just read, the components are:

1. Header (Metadata): A JSON object that specifies the token type (typ, which is "JWT") and the signing algorithm used (alg, e.g., "HS256"). This header is then Base64Url encoded to form the first part of the JWT.

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

2. Payload (The Claims): A JSON object containing the "claims"—statements about the user and the token itself. This is where you put the data needed for authentication and authorization. Claims include:

   • Registered Claims: Standardized claims like sub (subject, e.g., user ID), exp (expiration time), and iat (issued at).
   • Custom Claims: Any other data you want to include, like role: "admin" or name: "John Doe".
     This payload is also Base64Url encoded to form the second part of the JWT.

   {
     "sub": "user123",
     "role": "admin",
     "exp": 1678886400
   }
   

   Critical Security Point: Base64Url encoding is not encryption. It's a reversible encoding scheme. Anyone who intercepts a JWT can easily decode the header and payload and read their contents. You must never store sensitive information (like passwords or credit card numbers) in a JWT payload.

3. Signature (The Verification): This is the key to a JWT's security. To create the signature, you take the encoded header, the encoded payload, a secret key known only to the server, and sign them with the algorithm specified in the header.

   HMACSHA256(
     base64UrlEncode(header) + "." +
     base64UrlEncode(payload),
     your-256-bit-secret
   )
   

   This signature ensures that the token is authentic (it was issued by your server) and that its contents have not been tampered with. If an attacker changes even a single character in the payload (e.g., changing their role from "user" to "admin"), the signature will no longer be valid.

Now, let's watch a video that walks through this structure and the token authentication flow visually.

Session-Based vs. Token-Based Authentication: The Trade-Offs

Now that we understand both mechanisms, we can compare them. This isn't a matter of one being universally "better"; it's about choosing the right tool for the job based on your application's architecture and requirements. The decision hinges on a series of trade-offs.

Here is a fantastic diagram and table that summarize the differences in flow and features.

Let's use a more detailed table to break down the most important points of comparison.

Here's an expanded breakdown of those key differences:

To hear these points discussed with more nuance, let's watch the comparison segments from two excellent videos.

When to Use Which? The Hybrid Approach

Given the trade-offs, the choice becomes clearer:

• Use Sessions when:

  • You're building a traditional, server-rendered web application (a monolith).
  • Immediate and guaranteed session revocation is a high-priority security requirement (e.g., financial applications, admin panels).
  • You prefer to keep all user data securely on the server.

• Use Tokens (JWTs) when:

  • You're building a stateless API for a Single-Page Application (SPA), mobile app, or third-party service.
  • Your architecture is based on microservices, and you need a way for services to trust each other's authentication requests.
  • Horizontal scalability is a primary concern.

The Modern Hybrid: Access Tokens + Refresh Tokens

The biggest drawback of JWTs is the difficulty of revocation. The modern solution to this is a hybrid approach that gives you the best of both worlds:

1. Access Token: A standard JWT with a very short expiry (e.g., 5-15 minutes). This is used to authenticate API requests. Because it expires quickly, the window of opportunity for an attacker with a stolen token is small.
2. Refresh Token: A long-lived, opaque, random string. This token is stored securely by the client (ideally in an HttpOnly cookie) and is sent only to a special /token/refresh endpoint when the access token expires.
3. Server-Side Logic: The server does store and manage refresh tokens in a database. When it receives a valid refresh token, it issues a new, short-lived access token. If a user needs to be logged out, the server simply invalidates their refresh token in the database, preventing them from getting any new access tokens.

This model combines the stateless scalability of JWT access tokens with the server-side control and revocation capabilities of sessions.

Conclusion

You now have a robust mental model for both stateful and stateless authentication. You understand not just what a JWT is, but why it's structured the way it is and the specific architectural problems it solves—and creates.

Key Takeaways:

• JWT Structure: A JWT consists of a header, payload, and signature, separated by dots. The payload contains claims but is only Base64Url encoded, not encrypted. The signature guarantees integrity, not confidentiality.
• Stateful vs. Stateless: Session-based authentication is stateful (server remembers the user), while token-based authentication is stateless (the token itself is the proof of identity).
• The Core Trade-Off: The primary trade-off is control vs. scalability. Sessions offer easy, instant revocation (control) but are harder to scale. Tokens scale effortlessly but are difficult to revoke before expiration.
• Security Context: Sessions are primarily vulnerable to CSRF, while JWTs stored in browser localStorage are vulnerable to XSS. Using HttpOnly cookies is a powerful defense for both session IDs and refresh tokens.
• The Mental Model:
  • Sessions: The server gives you a ticket and remembers who you are.
  • Tokens: You carry a detailed, signed ID card that you must show everywhere.

Preview of the Next Lesson

Theory is essential, but practice makes it concrete. In the next lesson, we will put this knowledge to work. We will: Implement JWT authentication in a Django application, including token generation and validation middleware. You'll write the Python code to issue a JWT upon login and build the middleware to protect API endpoints by validating incoming tokens.