Auth Implementation

Comprehensive guide for implementing authentication and authorization in web applications. Covers session-based auth, JWT, OAuth 2.0, SSO, API keys, RBAC/ABAC, and security hardening across all major frameworks and libraries.

Decision Matrix

Use this table to pick the right approach and library for your stack:

Implementation Workflow

Follow these 5 steps for any auth implementation:

Step 1: Detect Stack

Read package.json, requirements.txt, go.mod, composer.json, or framework config to identify:

• Framework and version (Next.js 14+, Express, Django, FastAPI, Laravel, Go, SvelteKit)
• Database and ORM (Prisma, Drizzle, SQLAlchemy, GORM, Eloquent)
• Existing auth code (check for auth middleware, session config, JWT imports)

Step 2: Choose Approach

Use the Decision Matrix above. Key factors:

• Server-rendered app → session-based (cookies)
• SPA + API → JWT (access + refresh tokens) or BFF pattern
• Mobile + API → JWT with secure token storage
• Multiple providers needed → Auth.js, Better Auth, or Passport.js
• Enterprise / compliance → managed provider (Clerk, Auth0) or OIDC
• Maximum control → Lucia or custom JWT

Step 3: Database Schema

Set up auth tables. See [DATABASE-SCHEMAS.md](references/DATABASE-SCHEMAS.md) for full schemas.

Core tables needed:

• users — id, email, passwordhash, emailverified, created_at
• sessions — id, userid, expiresat (for session-based)
• accounts — id, userid, provider, provideraccount_id (for OAuth)

Step 4: Implement

Use the relevant reference file for step-by-step implementation. Install dependencies, configure auth, add routes, protect endpoints.

Step 5: Harden

Apply [SECURITY-CHECKLIST.md](references/SECURITY-CHECKLIST.md). At minimum:

• CSRF protection enabled
• Cookies: HttpOnly, Secure, SameSite=Lax
• Password hashing: argon2id or bcrypt
• Rate limiting on login/register/reset
• Input validation on all auth endpoints

Session-Based Auth (Quick Start)

Session-based auth stores session ID in a cookie. Server holds session data.

When to use: Server-rendered apps, full-stack frameworks, when you need easy revocation.

Express + express-session

import session from 'express-session';
import RedisStore from 'connect-redis';
import { createClient } from 'redis';

const redisClient = createClient({ url: process.env.REDIS_URL });
await redisClient.connect();

app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET!, // min 32 chars, random
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: true,
    sameSite: 'lax',
    maxAge: 1000 * 60 * 60 * 24 * 7, // 7 days
  },
}));

Next.js (iron-session)

// lib/session.ts
import { getIronSession } from 'iron-session';
import { cookies } from 'next/headers';

export async function getSession() {
  return getIronSession<SessionData>(await cookies(), {
    password: process.env.SESSION_SECRET!,
    cookieName: 'app-session',
    cookieOptions: {
      secure: process.env.NODE_ENV === 'production',
      httpOnly: true,
      sameSite: 'lax',
    },
  });
}

JWT Auth (Quick Start)

JWT auth uses signed tokens. Access token (short-lived) + refresh token (long-lived).

When to use: APIs consumed by SPAs, mobile apps, microservices. See [CUSTOM-JWT.md](references/CUSTOM-JWT.md).

Token Architecture

Access Token:  Short-lived (15 min), in memory or Authorization header
Refresh Token: Long-lived (7-30 days), HttpOnly cookie, rotated on use

Node.js (jose library)

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode(process.env.JWT_SECRET);

// Create access token
async function createAccessToken(userId: string, role: string) {
  return new SignJWT({ sub: userId, role })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('15m')
    .sign(secret);
}

// Verify token
async function verifyToken(token: string) {
  const { payload } = await jwtVerify(token, secret);
  return payload;
}

Middleware Pattern

async function authMiddleware(req: Request, next: Function) {
  const token = req.headers.get('Authorization')?.replace('Bearer ', '');
  if (!token) return new Response('Unauthorized', { status: 401 });
  try {
    const payload = await verifyToken(token);
    req.user = payload;
    return next();
  } catch {
    return new Response('Invalid token', { status: 401 });
  }
}

OAuth 2.0 / Social Login (Quick Start)

OAuth lets users sign in with existing accounts (Google, GitHub, etc.).

Flow: Authorization Code + PKCE (recommended for all clients):

1. Client generates code_verifier + code_challenge
2. Redirect to provider: /authorize?response_type=code&code_challenge=...
3. User authenticates with provider
4. Provider redirects back with authorization code
5. Server exchanges code + code_verifier for tokens
6. Server creates session or issues own JWT

See [OAUTH-OIDC.md](references/OAUTH-OIDC.md) for provider-specific setup.

Provider Quick Reference

Database Schema Essentials

See [DATABASE-SCHEMAS.md](references/DATABASE-SCHEMAS.md) for full schemas.

Prisma (Core Tables)

model User {
  id            String    @id @default(cuid())
  email         String    @unique
  passwordHash  String?
  emailVerified DateTime?
  name          String?
  role          String    @default("user")
  sessions      Session[]
  accounts      Account[]
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
}

model Session {
  id        String   @id @default(cuid())
  userId    String
  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  expiresAt DateTime
  createdAt DateTime @default(now())
  @@index([userId])
}

model Account {
  id                String @id @default(cuid())
  userId            String
  user              User   @relation(fields: [userId], references: [id], onDelete: Cascade)
  provider          String
  providerAccountId String
  accessToken       String?
  refreshToken      String?
  expiresAt         Int?
  @@unique([provider, providerAccountId])
  @@index([userId])
}

Middleware & Route Protection

Next.js App Router — middleware.ts

import { NextRequest, NextResponse } from 'next/server';

const protectedPaths = ['/dashboard', '/settings', '/api/protected'];
const authPaths = ['/login', '/register'];

export function middleware(request: NextRequest) {
  const sessionToken = request.cookies.get('session-token')?.value;
  const { pathname } = request.nextUrl;

  const isProtected = protectedPaths.some(p => pathname.startsWith(p));
  const isAuthPage = authPaths.some(p => pathname.startsWith(p));

  if (isProtected && !sessionToken) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  if (isAuthPage && sessionToken) {
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*', '/api/protected/:path*', '/login', '/register'],
};

Express Middleware

function requireAuth(req, res, next) {
  if (!req.session?.userId) {
    return res.status(401).json({ error: 'Authentication required' });
  }
  next();
}

function requireRole(...roles: string[]) {
  return (req, res, next) => {
    if (!roles.includes(req.session.role)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  };
}

// Usage
app.get('/admin', requireAuth, requireRole('admin'), adminHandler);

RBAC Quick Start

See [RBAC-ABAC.md](references/RBAC-ABAC.md) for full patterns.

Simple Role Check

// Define roles and permissions
const PERMISSIONS = {
  admin: ['read', 'write', 'delete', 'manage_users'],
  editor: ['read', 'write'],
  viewer: ['read'],
} as const;

function hasPermission(role: string, permission: string): boolean {
  return PERMISSIONS[role]?.includes(permission) ?? false;
}

// Middleware
function requirePermission(permission: string) {
  return (req, res, next) => {
    if (!hasPermission(req.user.role, permission)) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    next();
  };
}

Security Checklist (Condensed)

See [SECURITY-CHECKLIST.md](references/SECURITY-CHECKLIST.md) for full details.

Common Pitfalls

MFA / 2FA Overview

TOTP (Time-based One-Time Password)

// Libraries: otpauth (Node.js), pyotp (Python)
import { TOTP } from 'otpauth';

const totp = new TOTP({
  issuer: 'MyApp',
  label: user.email,
  algorithm: 'SHA1',
  digits: 6,
  period: 30,
  secret: generateSecret(),
});

// Generate QR code URI
const uri = totp.toString(); // otpauth://totp/MyApp:[email protected]?...

// Verify code
const isValid = totp.validate({ token: userCode, window: 1 }) !== null;

WebAuthn / Passkeys

Use @simplewebauthn/server + @simplewebauthn/browser for passwordless auth. See [SECURITY-CHECKLIST.md](references/SECURITY-CHECKLIST.md) for implementation steps.

References Index