JWT token generation and verification in Node.js - Deep Dive

Overview - JWT token generation and verification

What is it?

JWT stands for JSON Web Token. It is a way to securely send information between two parties as a JSON object. This token can be used to verify the identity of a user or share data safely. JWT tokens are often used in web applications to manage user login sessions without storing session data on the server.

Why it matters

Without JWT tokens, web applications would need to store user session data on the server, which can be slow and hard to scale. JWT tokens let servers trust the client by verifying the token's signature, making authentication faster and more scalable. This improves user experience and security in apps like online stores or social media.

Where it fits

Before learning JWT, you should understand basic JavaScript, JSON format, and how HTTP requests work. After mastering JWT, you can learn about OAuth, OpenID Connect, and advanced security practices for web apps.

Mental Model

Core Idea

A JWT is a secure, signed package of information that proves who you are without needing to check a database every time.

Think of it like...

Imagine a concert ticket with a special stamp that proves it's real. You show it at the door, and they trust it without calling the ticket office. JWT is like that ticket for your identity on the web.

Header.Payload.Signature
  │      │        │
  │      │        └─ Signature created by signing header and payload with secret
  │      └─ Payload contains user info and claims
  └─ Header describes token type and signing method

Build-Up - 6 Steps

1

Foundation

Understanding JWT Structure Basics

Concept: Learn the three parts of a JWT and what each part does.

A JWT has three parts separated by dots: header, payload, and signature. The header tells what type of token it is and how it is signed. The payload carries the data like user ID or expiration time. The signature is created by combining the header and payload and signing them with a secret key.

Result

You can identify and decode each part of a JWT token string.

Knowing the token's parts helps you understand how data and security are combined in one package.

2

Foundation

Installing and Using jsonwebtoken Library

Concept: Use a Node.js library to create and verify JWT tokens easily.

Install the 'jsonwebtoken' package with npm. Use jwt.sign() to create a token by passing a payload and a secret key. Use jwt.verify() to check if a token is valid and get the original data back.

Result

You can generate a JWT token string and verify it in your Node.js app.

Using a library saves time and avoids mistakes in the complex signing process.

3

Intermediate

Adding Expiration and Custom Claims

🤔Before reading on: Do you think JWT tokens expire automatically or do you have to add expiration manually? Commit to your answer.

Concept: Learn how to add expiration time and extra data to tokens for better control.

When creating a token, you can add an 'exp' claim to set when the token expires. You can also add custom claims like user roles or permissions in the payload. This helps control how long a token is valid and what the user can do.

Result

Tokens now expire after a set time and carry extra user info.

Expiration prevents old tokens from being used forever, improving security.

4

Intermediate

Verifying Tokens and Handling Errors

🤔Before reading on: If a token is expired, do you think jwt.verify() throws an error or returns false? Commit to your answer.

Concept: Understand how to check tokens and handle cases like expiration or tampering.

Use jwt.verify() with a try-catch block to catch errors like token expiration or invalid signature. Handle these errors by asking users to log in again or rejecting requests. This keeps your app secure and user-friendly.

Result

Your app can safely reject invalid or expired tokens and prompt users accordingly.

Proper error handling prevents security holes and improves user experience.

5

Advanced

Using Asymmetric Keys for Signing

🤔Before reading on: Do you think JWT signing always uses the same secret key for signing and verifying? Commit to your answer.

Concept: Learn how to use public/private key pairs to sign and verify tokens for stronger security.

Instead of a shared secret, use RSA or ECDSA keys. Sign tokens with a private key and verify with the public key. This allows verification without exposing the private key, useful in distributed systems or third-party verification.

Result

Tokens are signed with private keys and verified with public keys, improving security.

Asymmetric signing separates signing and verification duties, reducing risk of secret leaks.

6

Expert

Avoiding Common Security Pitfalls in JWT

🤔Before reading on: Is it safe to store sensitive user data directly inside JWT payload? Commit to your answer.

Concept: Understand what not to do with JWTs to keep your app secure.

Never store sensitive info like passwords in JWT payload because it is only base64 encoded, not encrypted. Always validate tokens on the server side. Beware of token replay attacks and use HTTPS to protect tokens in transit. Rotate secrets regularly and keep token expiration short.

Result

Your JWT implementation avoids common security mistakes and stays robust.

Knowing JWT limits and risks helps prevent serious security breaches.

Under the Hood

JWT tokens are base64url encoded strings composed of header, payload, and signature. The signature is created by hashing the header and payload with a secret or private key using algorithms like HMAC SHA256 or RSA. When verifying, the server recalculates the signature and compares it to the token's signature to ensure integrity and authenticity. The payload is not encrypted, so anyone can decode it, but they cannot change it without invalidating the signature.

Why designed this way?

JWT was designed to be compact and URL-safe for easy transmission in HTTP headers or URLs. Using signatures instead of encryption allows stateless authentication, meaning servers don't need to store session data. This design balances security, performance, and scalability for modern web apps. Alternatives like opaque tokens require server storage, which can be slower and harder to scale.

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Header    │ . │   Payload   │ . │ Signature   │
└─────────────┘   └─────────────┘   └─────────────┘
       │               │                 │
       │               │                 └─ Created by hashing header+payload with secret
       │               └─ Contains claims like user ID, expiration
       └─ Specifies algorithm and token type

Myth Busters - 4 Common Misconceptions

Quick: Does decoding a JWT token mean the data inside is secret? Commit yes or no.

Common Belief: Many think JWT payload is encrypted and private.

Reality: JWT payload is only base64 encoded, which anyone can decode easily.

Why it matters: Storing sensitive data in JWT payload exposes it to anyone who intercepts the token.

Quick: Do you think jwt.verify() can detect if a token is expired? Commit yes or no.

Common Belief: Some believe jwt.verify() only checks signature, not expiration.

Reality: jwt.verify() checks both signature and expiration by default.

Why it matters: Failing to rely on jwt.verify() for expiration can lead to accepting expired tokens.

Quick: Is it safe to use the same secret key for multiple apps? Commit yes or no.

Common Belief: People often reuse the same secret key across different applications.

Reality: Reusing secrets increases risk; if one app is compromised, all are at risk.

Why it matters: A leaked secret key can allow attackers to forge tokens for all apps sharing it.

Quick: Can you trust a JWT token just because it looks valid? Commit yes or no.

Common Belief: Some think any JWT token string is trustworthy if it has the right format.

Reality: Only tokens with valid signatures and unexpired claims are trustworthy.

Why it matters: Accepting unsigned or tampered tokens leads to security breaches.

Expert Zone

1

JWT tokens can be stored in cookies or local storage, but each has security tradeoffs like XSS or CSRF risks.

2

Using 'none' algorithm in JWT header disables signature verification, which is a dangerous legacy feature to avoid.

3

Token revocation is tricky with JWT because tokens are stateless; implementing blacklist or short expiration is necessary.

When NOT to use

JWT is not ideal when you need immediate token revocation or store large session data. In such cases, traditional server-side sessions or opaque tokens with a database are better.

Production Patterns

In production, JWTs are often used with refresh tokens to allow short-lived access tokens and longer-lived refresh tokens. They are combined with HTTPS, secure cookie flags, and proper error handling to build secure authentication flows.

Connections

OAuth 2.0

JWT is often used as the token format within OAuth 2.0 authorization flows.

Understanding JWT helps grasp how OAuth securely delegates access without sharing passwords.

Public Key Cryptography

JWT can use asymmetric keys for signing and verification, relying on public/private key pairs.

Knowing public key cryptography clarifies how JWT tokens can be verified without exposing secrets.

Digital Signatures in Legal Documents

JWT signatures are like digital signatures that prove document authenticity and integrity.

Recognizing this connection shows how JWT ensures data hasn't been altered, similar to signed contracts.

Common Pitfalls

#1 Storing sensitive user data like passwords inside JWT payload.

Wrong approach:

const token = jwt.sign({ username: 'user1', password: 'secret123' }, secretKey);

Correct approach:

const token = jwt.sign({ username: 'user1' }, secretKey);

Root cause:

Misunderstanding that JWT payload is encrypted; it is only encoded and visible to anyone.

#2 Not handling token expiration errors, causing app crashes or security holes.

Wrong approach:

const data = jwt.verify(token, secretKey); // no try-catch

Correct approach:

try { const data = jwt.verify(token, secretKey); } catch (err) { /* handle expired or invalid token */ }

Root cause:

Assuming jwt.verify() always succeeds and ignoring possible exceptions.

#3 Using the 'none' algorithm to sign tokens, disabling signature verification.

Wrong approach:

const token = jwt.sign(payload, '', { algorithm: 'none' });

Correct approach:

const token = jwt.sign(payload, secretKey, { algorithm: 'HS256' });

Root cause:

Not understanding that 'none' algorithm means no signature, which is insecure.

Key Takeaways

JWT tokens are compact, signed JSON objects used to prove identity without server-side sessions.

The token has three parts: header, payload, and signature; only the signature protects data integrity.

Always verify tokens with the correct secret or public key and handle errors like expiration properly.

Never store sensitive data in the payload because it is not encrypted, only encoded.

Use short expiration times and consider asymmetric keys for better security in production.