authentication-patterns

Reference for implementing secure, production-ready authentication.

WHEN_TO_USE

Apply this skill when implementing authentication in a project, reviewing existing auth flows for security issues, choosing between auth providers, or migrating between auth strategies. Use the security checklist before shipping any auth-related change.

AUTH_APPROACHES

Approach	How It Works	Best For	Drawbacks
Session-based	Server stores session in DB/Redis, client holds session ID cookie	Traditional server-rendered apps, apps needing instant revocation	Requires server-side storage, harder to scale horizontally without shared store
JWT (stateless)	Server signs token, client sends it on each request	API-first apps, microservices, mobile clients	Cannot revoke without blocklist, token size grows with claims
OAuth 2.0 / OIDC	Delegates auth to external provider (Google, GitHub, etc.)	Social login, enterprise SSO, reducing auth responsibility	More complex flow, depends on external provider availability
Passkeys / WebAuthn	Cryptographic key pair, no passwords	High-security apps, passwordless UX	Limited browser support legacy, user education needed

Decision Guide

• Server-rendered app with simple needs → Session-based
• SPA or mobile app calling APIs → JWT with refresh token rotation
• Want social login or SSO → OAuth 2.0 / OIDC
• Greenfield with modern UX goals → Passkeys + OAuth fallback

JWT_BEST_PRACTICES

Token Lifecycle

Login → Access Token (short-lived) + Refresh Token (long-lived, rotated)
  │
  ├─ Access Token: 15 min expiry, sent via httpOnly cookie or Authorization header
  │
  └─ Refresh Token: 7-30 day expiry, stored in httpOnly secure cookie
       │
       └─ On use: issue new access + new refresh token, invalidate old refresh token

Rules

• [P0-MUST] Set short expiry on access tokens (15 minutes or less).
• [P0-MUST] Store tokens in httpOnly, Secure, SameSite=Lax cookies — never in localStorage or sessionStorage.
• [P0-MUST] Implement refresh token rotation — each refresh token is single-use.
• [P0-MUST] Maintain a server-side blocklist for revoked refresh tokens.
• [P1-SHOULD] Include only essential claims in JWT payload (sub, iat, exp, role). Keep it small.
• [P1-SHOULD] Use asymmetric signing (RS256 or ES256) for distributed systems; symmetric (HS256) for single-service only.
• [P1-SHOULD] Validate iss, aud, and exp claims on every request.
• [P2-MAY] Use JWE (encrypted JWT) when token payload contains sensitive data.

Token Storage Comparison

Storage	XSS Safe	CSRF Safe	Recommendation
httpOnly cookie	Yes	No (needs CSRF token)	Recommended
localStorage	No	Yes	Never use for auth tokens
sessionStorage	No	Yes	Never use for auth tokens
In-memory (JS variable)	Yes	Yes	OK for SPAs, lost on refresh

PROVIDER_PATTERNS

Comparison

Provider	Type	Best For	Pricing	Key Features
NextAuth / Auth.js	OSS library	Next.js apps wanting full control	Free	80+ providers, DB adapters, self-hosted
Clerk	Managed service	Fast launch, pre-built UI, user management	Free tier, then per-MAU	Drop-in components, user dashboard, org support
Supabase Auth	Managed (part of Supabase)	Apps already using Supabase for DB/storage	Free tier, then per-MAU	Row-level security integration, magic links, SSO
Lucia	OSS library	Full control, minimal abstraction	Free	Session-based, framework-agnostic, type-safe

When to Use Each

• NextAuth / Auth.js: You want provider flexibility, self-hosting, and database session control. Best when you need custom flows.
• Clerk: You want auth done fast with pre-built UI components. Best for MVPs and teams that don't want to build auth UI.
• Supabase Auth: You're already using Supabase. Auth integrates with RLS policies for row-level security.
• Lucia: You want a minimal, type-safe session library without framework lock-in.

NextAuth.js Setup Pattern

// app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    session({ session, user }) {
      session.user.id = user.id;
      return session;
    },
  },
});

SECURITY_CHECKLIST

Before Shipping Auth

• Rate limiting: Login endpoint limited to 5-10 attempts per minute per IP.
• CSRF protection: Anti-CSRF tokens on all state-changing requests (or use SameSite=Lax cookies).
• Password hashing: Using bcrypt (cost 12+) or argon2id — never MD5, SHA-1, or plain SHA-256.
• HTTPS only: All auth endpoints served over TLS. Cookies have Secure flag.
• Input validation: Email format, password length (min 8, max 128), no SQL/NoSQL injection vectors.
• Account enumeration: Login and registration return the same response whether account exists or not.
• Session invalidation: Logout invalidates server-side session/refresh token, not just client cookie.
• MFA support: TOTP (authenticator app) or WebAuthn as second factor for sensitive accounts.
• Password reset: Time-limited tokens (1 hour), single-use, sent over secure channel.
• Audit logging: Log auth events (login, logout, failed attempts, password changes) with timestamp and IP.

Password Hashing

// Using bcrypt
import bcrypt from "bcrypt";

const SALT_ROUNDS = 12;

async function hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, SALT_ROUNDS);
}

async function verifyPassword(password: string, hash: string): Promise<boolean> {
  return bcrypt.compare(password, hash);
}

// Using argon2 (preferred for new projects)
import argon2 from "argon2";

async function hashPassword(password: string): Promise<string> {
  return argon2.hash(password, { type: argon2.argon2id });
}

async function verifyPassword(hash: string, password: string): Promise<boolean> {
  return argon2.verify(hash, password);
}

COMMON_MISTAKES

Mistake	Risk	Fix
Storing JWT in localStorage	XSS can steal tokens	Use httpOnly cookies
Long-lived JWTs (days/weeks)	Stolen token is valid for extended period	15 min access token + refresh rotation
Missing CSRF protection	Attackers can forge requests from other sites	SameSite=Lax cookies + CSRF token
Weak password requirements	Brute force and credential stuffing	Min 8 chars, check against breached password lists
Exposing user existence on login	Account enumeration	Generic "Invalid credentials" message
Not rotating refresh tokens	Stolen refresh token grants indefinite access	Single-use refresh tokens with rotation
Hardcoding secrets in source	Credential leak via git history	Use environment variables, never commit secrets
Missing rate limiting on login	Brute force attacks	5-10 attempts/min per IP, exponential backoff
Rolling your own crypto	Subtle vulnerabilities	Use established libraries (bcrypt, argon2, jose)
Not validating JWT claims	Token misuse across services	Always verify iss, aud, exp