Authentication & Security Architecture

Security is the one area where "it works" is never enough. A working auth flow with a token in localStorage is a data breach waiting to happen. Senior engineers understand the threat model and design defenses in layers — because attackers only need to find one gap.

Authentication Flows

OAuth 2.0 + OIDC

OAuth 2.0 handles authorization (what can you access). OpenID Connect (OIDC) adds authentication (who are you) on top.

┌──────────┐     ┌──────────────┐     ┌──────────────────┐
│  User    │     │  Your App    │     │  Identity Provider│
│ (Browser)│     │  (SPA/BFF)   │     │  (Google, Okta)  │
└────┬─────┘     └──────┬───────┘     └────────┬─────────┘
     │                  │                      │
     │  Click "Login"   │                      │
     │─────────────────▶│                      │
     │                  │  /authorize +        │
     │                  │  code_challenge      │
     │                  │─────────────────────▶│
     │                  │                      │
     │  ◀──────────── Redirect to IdP ────────│
     │                  │                      │
     │  User logs in    │                      │
     │─────────────────────────────────────────▶│
     │                  │                      │
     │  ◀──── Redirect back with auth code ────│
     │                  │                      │
     │  Code to app     │                      │
     │─────────────────▶│                      │
     │                  │  Exchange code +     │
     │                  │  code_verifier for   │
     │                  │  tokens              │
     │                  │─────────────────────▶│
     │                  │                      │
     │                  │◀── access_token ─────│
     │                  │◀── id_token ─────────│
     │                  │◀── refresh_token ────│
     │                  │                      │
     │◀── Session ──────│                      │
     │                  │                      │

PKCE (Proof Key for Code Exchange)

SPAs can't store a client secret. PKCE replaces it with a cryptographic challenge:

async function generatePKCE() {
  const verifier = crypto.randomUUID() + crypto.randomUUID();
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  const challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
 
  return { verifier, challenge };
}
 
// Step 1: Start auth with challenge
const { verifier, challenge } = await generatePKCE();
sessionStorage.setItem('pkce_verifier', verifier);
 
const authUrl = new URL('https://idp.example.com/authorize');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('code_challenge', challenge);
authUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authUrl.toString();
 
// Step 2: Exchange code with verifier
async function handleCallback(code: string) {
  const verifier = sessionStorage.getItem('pkce_verifier');
  const response = await fetch('https://idp.example.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      code_verifier: verifier!,
    }),
  });
  return response.json();
}

Token Storage: The Critical Decision

Where you store tokens determines your threat surface. There is no perfect option — only trade-offs.

Threat Analysis Matrix

Storage	XSS Vulnerable	CSRF Vulnerable	Persists Refresh	Accessible by JS
localStorage	YES	No	Yes	Yes
sessionStorage	YES	No	No (tab only)	Yes
HttpOnly Cookie	No	YES	Yes	No
In-Memory (JS var)	Partial	No	No (lost on refresh)	Yes (same context)
HttpOnly Cookie + CSRF token	No	No	Yes	No

The Recommended Architecture

┌─────────────────────────────────────────────────────┐
│              Token Storage Architecture              │
│                                                     │
│  Access Token: In-memory JavaScript variable        │
│  ├─ Short-lived (5-15 minutes)                     │
│  ├─ Sent via Authorization header                   │
│  ├─ Lost on page refresh (by design)               │
│  └─ Not accessible via XSS (not in storage)        │
│                                                     │
│  Refresh Token: HttpOnly, Secure, SameSite cookie   │
│  ├─ Long-lived (days to weeks)                     │
│  ├─ Sent automatically by browser                   │
│  ├─ Not accessible via JavaScript                   │
│  └─ Protected from CSRF via SameSite=Strict        │
│                                                     │
│  On page load: silent refresh to get new access token│
└─────────────────────────────────────────────────────┘

let accessToken: string | null = null;
 
async function getAccessToken(): Promise<string> {
  if (accessToken && !isExpired(accessToken)) {
    return accessToken;
  }
  return silentRefresh();
}
 
async function silentRefresh(): Promise<string> {
  const response = await fetch('/api/auth/refresh', {
    method: 'POST',
    credentials: 'include',
  });
 
  if (!response.ok) {
    accessToken = null;
    throw new AuthError('Session expired');
  }
 
  const { access_token } = await response.json();
  accessToken = access_token;
  scheduleRefresh(access_token);
  return access_token;
}
 
function scheduleRefresh(token: string) {
  const payload = JSON.parse(atob(token.split('.')[1]));
  const expiresIn = payload.exp * 1000 - Date.now();
  const refreshAt = expiresIn - 60_000; // refresh 1 minute before expiry
  setTimeout(silentRefresh, Math.max(refreshAt, 0));
}

JWT Anatomy

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.     ← Header (algorithm, type)
eyJzdWIiOiJ1c2VyXzEyMyIsIm5hbWUiOiJBbGljZSJ9. ← Payload (claims)
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c   ← Signature
 
┌──────────────────────────────────────────┐
│  Header                                  │
│  { "alg": "RS256", "typ": "JWT" }       │
├──────────────────────────────────────────┤
│  Payload (Claims)                        │
│  {                                       │
│    "sub": "user_123",                    │
│    "name": "Alice",                      │
│    "email": "alice@example.com",         │
│    "roles": ["admin", "editor"],         │
│    "iat": 1711900800,                    │
│    "exp": 1711901700,                    │
│    "iss": "https://auth.example.com"     │
│  }                                       │
├──────────────────────────────────────────┤
│  Signature                               │
│  RS256(                                  │
│    base64(header) + "." + base64(payload),│
│    private_key                           │
│  )                                       │
└──────────────────────────────────────────┘

Frontend verification: The frontend should NOT verify JWT signatures — that's the backend's job. The frontend can decode the payload to read claims (user info, roles, expiration) but should never trust the JWT without server validation.

function decodeJwtPayload(token: string): JwtPayload {
  const payload = token.split('.')[1];
  return JSON.parse(atob(payload));
}
 
function isExpired(token: string): boolean {
  const { exp } = decodeJwtPayload(token);
  return Date.now() >= exp * 1000;
}

Token Refresh Patterns

Silent Refresh (Recommended for SPAs)

┌──────────┐                          ┌──────────┐
│  Client  │                          │  Server  │
│          │                          │          │
│ Access token expired                │          │
│          │── POST /auth/refresh ───▶│          │
│          │   (HttpOnly cookie)      │          │
│          │                          │ Validate │
│          │                          │ refresh  │
│          │                          │ token    │
│          │◀── New access token ─────│          │
│          │                          │          │
│ Store in memory                     │          │
│ Schedule next refresh               │          │
└──────────┘                          └──────────┘

Refresh Token Rotation

Each time a refresh token is used, the server issues a new one and invalidates the old one. If an attacker steals a refresh token and the legitimate user refreshes first, the attacker's token is invalid:

Legitimate user: refresh_token_v1 → gets refresh_token_v2 (v1 invalidated)
Attacker:        refresh_token_v1 → REJECTED (v1 already used)
                 Server detects token reuse → invalidates ALL tokens for user

RBAC and ABAC

Role-Based Access Control (RBAC)

type Role = 'viewer' | 'editor' | 'admin' | 'superadmin';
 
const permissions: Record<Role, string[]> = {
  viewer:     ['read:posts', 'read:comments'],
  editor:     ['read:posts', 'read:comments', 'write:posts', 'write:comments'],
  admin:      ['read:posts', 'read:comments', 'write:posts', 'write:comments', 'manage:users'],
  superadmin: ['*'],
};
 
function hasPermission(userRole: Role, permission: string): boolean {
  const userPermissions = permissions[userRole];
  return userPermissions.includes('*') || userPermissions.includes(permission);
}

Attribute-Based Access Control (ABAC)

More granular — decisions based on user attributes, resource attributes, and context:

interface Policy {
  effect: 'allow' | 'deny';
  condition: (context: {
    user: User;
    resource: Resource;
    action: string;
    environment: { time: Date; ip: string };
  }) => boolean;
}
 
const policies: Policy[] = [
  {
    effect: 'allow',
    condition: ({ user, resource, action }) =>
      action === 'edit' && resource.ownerId === user.id,
  },
  {
    effect: 'allow',
    condition: ({ user, action }) =>
      action === 'edit' && user.roles.includes('admin'),
  },
  {
    effect: 'deny',
    condition: ({ environment }) => {
      const hour = environment.time.getHours();
      return hour < 6 || hour > 22; // deny outside business-adjacent hours
    },
  },
];

Route Protection

Client-Side Guards

function ProtectedRoute({ children, requiredRole }: ProtectedRouteProps) {
  const { user, isLoading } = useAuth();
 
  if (isLoading) return <PageSkeleton />;
  if (!user) return <Navigate to="/login" replace />;
  if (requiredRole && !hasRole(user, requiredRole)) return <Navigate to="/unauthorized" />;
 
  return children;
}
 
// Usage
<Route path="/admin/*" element={
  <ProtectedRoute requiredRole="admin">
    <AdminDashboard />
  </ProtectedRoute>
} />

Critical: Client-side guards are UX features, not security features. A determined user can bypass them. The server must enforce authorization on every API call.

Middleware (Next.js / Server-Side)

// middleware.ts (Next.js)
import { NextRequest, NextResponse } from 'next/server';
 
export function middleware(request: NextRequest) {
  const token = request.cookies.get('session')?.value;
 
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
 
  if (token) {
    const payload = decodeJwtPayload(token);
    if (request.nextUrl.pathname.startsWith('/admin') && !payload.roles.includes('admin')) {
      return NextResponse.redirect(new URL('/unauthorized', request.url));
    }
  }
 
  return NextResponse.next();
}
 
export const config = {
  matcher: ['/dashboard/:path*', '/admin/:path*'],
};

CSRF Protection in SPAs

Cross-Site Request Forgery tricks the browser into making authenticated requests to your API from a malicious site.

The SameSite Cookie Defense

Set-Cookie: session=abc123; HttpOnly; Secure; SameSite=Strict; Path=/

SameSite=Strict prevents the cookie from being sent on cross-origin requests — the primary CSRF vector.

Double-Submit Cookie Pattern

For APIs that need cross-origin support:

// Server sets a CSRF token cookie (readable by JS, NOT HttpOnly)
// Set-Cookie: csrf_token=random123; Secure; SameSite=Lax
 
// Client reads the cookie and sends it as a header
const csrfToken = document.cookie
  .split('; ')
  .find(row => row.startsWith('csrf_token='))
  ?.split('=')[1];
 
fetch('/api/transfer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': csrfToken!,
  },
  credentials: 'include',
  body: JSON.stringify({ amount: 100 }),
});

The attacker can trigger the request (cookie sent automatically) but cannot read the cookie value to set the header.

XSS Prevention Architecture

XSS is the most common web vulnerability. Defense is layered:

Layer 1: Output Encoding

React escapes by default. The danger is dangerouslySetInnerHTML:

// ✅ Safe — React escapes automatically
<div>{userInput}</div>
 
// ❌ Dangerous — raw HTML injection
<div dangerouslySetInnerHTML={{ __html: userInput }} />
 
// ✅ If you must render HTML, sanitize first
import DOMPurify from 'dompurify';
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userInput) }} />

Layer 2: Content Security Policy

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'nonce-abc123';
  style-src 'self' 'unsafe-inline';
  img-src 'self' https://cdn.example.com;
  connect-src 'self' https://api.example.com;
  font-src 'self' https://fonts.googleapis.com;
  frame-ancestors 'none';
  base-uri 'self';
  form-action 'self';

What each directive prevents:

Directive	Prevents
`script-src 'self'`	Inline scripts, external script injection
`frame-ancestors 'none'`	Clickjacking (no iframe embedding)
`base-uri 'self'`	Base tag injection
`connect-src 'self'`	Data exfiltration to external domains

Layer 3: Sanitize User Input

const ALLOWED_TAGS = ['p', 'b', 'i', 'em', 'strong', 'a', 'ul', 'ol', 'li', 'br'];
const ALLOWED_ATTRS = { a: ['href', 'title'] };
 
function sanitizeUserContent(html: string): string {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS,
    ALLOWED_ATTR: Object.values(ALLOWED_ATTRS).flat(),
  });
}

Subresource Integrity (SRI)

Ensure CDN-hosted scripts haven't been tampered with:

<script
  src="https://cdn.example.com/vendor.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8w"
  crossorigin="anonymous"
></script>

If the file's hash doesn't match, the browser refuses to execute it.

Secure Headers Checklist

┌──────────────────────────────────────────────────────────────┐
│  Header                         │ Purpose                    │
│─────────────────────────────────┼────────────────────────────│
│  Content-Security-Policy        │ XSS, injection prevention  │
│  Strict-Transport-Security      │ Force HTTPS (HSTS)         │
│  X-Content-Type-Options         │ Prevent MIME sniffing      │
│  X-Frame-Options                │ Clickjacking prevention    │
│  Referrer-Policy                │ Control referrer leakage   │
│  Permissions-Policy             │ Restrict browser features  │
│  Cross-Origin-Opener-Policy     │ Isolate browsing context   │
│  Cross-Origin-Resource-Policy   │ Prevent cross-origin reads │
└──────────────────────────────────────────────────────────────┘

Implementation (Next.js)

// next.config.js
const securityHeaders = [
  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'X-XSS-Protection', value: '0' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
  { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
];
 
module.exports = {
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};

Security Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                  Security Layers                             │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Browser Layer                                        │  │
│  │  CSP │ SRI │ CORS │ SameSite Cookies │ HSTS          │  │
│  └──────────────────────────┬───────────────────────────┘  │
│                             │                              │
│  ┌──────────────────────────▼───────────────────────────┐  │
│  │  Application Layer                                    │  │
│  │  Input Sanitization │ Output Encoding │ CSRF Tokens  │  │
│  │  Route Guards │ Token Management │ Error Handling     │  │
│  └──────────────────────────┬───────────────────────────┘  │
│                             │                              │
│  ┌──────────────────────────▼───────────────────────────┐  │
│  │  Network Layer                                        │  │
│  │  HTTPS │ Certificate Pinning │ API Gateway │ WAF      │  │
│  └──────────────────────────┬───────────────────────────┘  │
│                             │                              │
│  ┌──────────────────────────▼───────────────────────────┐  │
│  │  Server Layer                                         │  │
│  │  Auth Middleware │ Rate Limiting │ Input Validation   │  │
│  │  RBAC/ABAC │ Audit Logging │ Token Verification      │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

The Interview Framing

When asked about auth and security in a system design interview, structure your answer as:

Authentication flow — "I'd use OAuth 2.0 + PKCE since this is an SPA. No client secret storage needed."
Token storage — "Access token in memory, refresh token in HttpOnly Secure SameSite cookie."
Session lifecycle — "Silent refresh before expiry, refresh token rotation for theft detection."
Authorization — "RBAC for route protection client-side, enforced server-side on every API call."
XSS prevention — "CSP headers, DOMPurify for user-generated content, no dangerouslySetInnerHTML."
CSRF prevention — "SameSite=Strict cookies. If cross-origin needed, double-submit pattern."

Security isn't one feature. It's a posture — a set of layered defenses where each layer assumes the others might fail. That's defense in depth. That's what architects build.