OAuth2 and OpenID Connect

al TLS are appropriate. This section covers the SPA + Backend API pattern using PKCE.

Architecture Decisions

1. PKCE over Implicit/Resource Owner: The implicit flow exposes tokens in browser history and URL fragments. PKCE binds the authorization request to the token exchange, neutralizing authorization code interception attacks.
2. Backend Token Validation: ID tokens must never be trusted on the client alone. The backend validates the signature, issuer, audience, expiration, and nonce before establishing a session.
3. Session Isolation: After validation, the backend issues a short-lived, HTTP-only session cookie. Access tokens are exchanged for API calls and never persisted beyond the request lifecycle.
4. Scope Separation: openid profile email triggers ID token issuance. Resource scopes (read:data, write:orders) are reserved for access tokens.

Step-by-Step Implementation

1. Client generates PKCE parameters

import { randomBytes, createHash } from 'crypto';

function generatePKCE() {
  const codeVerifier = randomBytes(32).toString('base64url');
  const codeChallenge = createHash('sha256')
    .update(codeVerifier)
    .digest('base64url');
  return { codeVerifier, codeChallenge };
}

2. Redirect to Authorization Endpoint

const { codeVerifier, codeChallenge } = generatePKCE();
const authUrl = new URL('https://auth.example.com/authorize');
authUrl.searchParams.set('client_id', process.env.OIDC_CLIENT_ID);
authUrl.searchParams.set('redirect_uri', process.env.OIDC_REDIRECT_URI);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');
authUrl.searchParams.set('state', randomBytes(16).toString('hex'));
authUrl.searchParams.set('nonce', randomBytes(16).toString('hex'));

// Redirect user to authUrl.toString()

3. Backend exchanges code and validates ID token

import { importPKCS8, jwtVerify } from 'jose';
import axios from 'axios';

async function handleCallback(code: string, state: string, verifier: string) {
  // Verify state matches session
  if (state !== sessionStorage.get('auth_state')) {
    throw new Error('Invalid state parameter');
  }

  // Exchange code for tokens
  const tokenResponse = await axios.post('https://auth.example.com/token', null, {
    params: {
      grant_type: 'authorization_code',
      client_id: process.env.OIDC_CLIENT_ID,
      code,
      redirect_uri: process.env.OIDC_REDIRECT_URI,
      code_verifier: verifier,
    },
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  });

  const { id_token, access_token, refresh_token, expires_in } = tokenResponse.data;

  // Fetch provider JWKS
  const jwksResponse = await axios.get('https://auth.example.com/.well-known/jwks.json');
  const jwks = jwksResponse.data;

  // Validate ID token
  const { payload, protectedHeader } = await jwtVerify(id_token, async (protectedHeader) => {
    const key = jwks.keys.find(k => k.kid === protectedHeader.kid);
    if (!key) throw new Error('Unknown key');
    return importPKCS8(key.pem, protectedHeader.alg as any);
  });

  // Enforce claims
  const now = Math.floor(Date.now() / 1000);
  if (payload.iss !== 'https://auth.example.com/') throw new Error('Invalid issuer');
  if (payload.aud !== process.env.OIDC_CLIENT_ID) throw new Error('Invalid audience');
  if (typeof payload.exp === 'number' && payload.exp < now) throw new Error('Token expired');
  if (payload.nonce !== sessionStorage.get('auth_nonce')) throw new Error('Nonce mismatch');

  // Establish backend session
  const sessionId = randomBytes(24).toString('hex');
  await redis.set(`session:${sessionId}`, JSON.stringify({
    sub: payload.sub,
    issuedAt: now,
    refresh_token,
    access_token_expires: now + (expires_in || 3600),
  }), { EX: 86400 });

  return { sessionId, access_token };
}

4. API middleware validates access tokens

import { jwtVerify } from 'jose';

export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) return res.status(401).json({ error: 'Missing token' });

  const token = authHeader.split(' ')[1];
  try {
    const { payload } = await jwtVerify(token, async (header) => {
      const jwks = await fetchJWKS();
      const key = jwks.keys.find(k => k.kid === header.kid);
      return importPKCS8(key!.pem, header.alg as any);
    });

    if (payload.exp! < Math.floor(Date.now() / 1000)) {
      return res.status(401).json({ error: 'Access token expired' });
    }

    req.user = { sub: payload.sub, scopes: payload.scope?.split(' ') || [] };
    next();
  } catch {
    res.status(403).json({ error: 'Invalid token' });
  }
}

Rationale: This architecture enforces cryptographic separation between identity and access. The ID token validates who the user is; the access token validates what they can do. PKCE eliminates code interception. Backend validation ensures tokens cannot be forged or replayed. Session cookies isolate authentication state from token lifecycles, enabling secure refresh rotation without exposing credentials to the browser.

Pitfall Guide

1. Using OAuth2 Scopes for Authentication Scopes define resource access, not identity. Relying on scope=openid without validating the ID token leaves authentication unverified. Always treat openid as a trigger for ID token issuance, not as an authentication guarantee.

2. Storing Tokens in localStorage or sessionStorage Client-side storage is vulnerable to XSS. Access tokens, ID tokens, and refresh tokens should never reside in browser storage. Use HTTP-only cookies for session state and keep tokens in backend memory or secure vaults.

3. Validating Only the JWT Signature A valid signature proves issuance, not authorization. Failing to check iss, aud, exp, and nonce allows token replay, audience confusion, and expired token acceptance. Signature verification is the first step, not the complete validation pipeline.

4. Using the Implicit Flow The implicit flow returns tokens in the URL fragment, exposing them to browser history, referrer leaks, and malicious extensions. It is deprecated in OIDC 1.0 and explicitly discouraged by OAuth2 Security Best Current Practice (RFC 6819 updates).

5. Mixing ID Tokens and Access Tokens ID tokens contain user identity claims and are meant for the client. Access tokens contain authorization scopes and are meant for resource servers. Swapping them breaks trust boundaries and exposes identity data to APIs that should only see authorization context.

6. Ignoring Refresh Token Rotation Static refresh tokens enable indefinite session hijacking. Implement rotation: issue a new refresh token on every use, revoke the previous one, and enforce sliding expiration. Detect reuse to trigger session termination.

7. Skipping Redirect URI Validation Open redirectors enable authorization code phishing. Strictly whitelist redirect URIs in the provider console and validate them server-side. Never accept dynamic or user-supplied redirect parameters.

Production Best Practices:

• Enforce strict Content Security Policy headers to mitigate XSS-driven token theft.
• Implement token binding via cnf (confirmation) claims when supported by the provider.
• Monitor token validation failures and rate-limit /token endpoints.
• Use short-lived access tokens (5–15 minutes) with secure refresh rotation.
• Log authentication events with correlation IDs for audit trails.

Production Bundle

Action Checklist

• Enable PKCE for all public clients: Generate code_verifier/code_challenge before authorization requests.
• Configure strict redirect URI allowlist: Reject any URI not explicitly registered in the provider console.
• Implement backend claim validation: Verify iss, aud, exp, nonce, and signature on every ID token.
• Replace localStorage token storage: Migrate to HTTP-only, Secure, SameSite=Strict session cookies.
• Enable refresh token rotation: Issue new refresh tokens on use, revoke previous, detect reuse.
• Separate scope definitions: Reserve openid for identity, assign resource-specific scopes to access tokens.
• Add token validation monitoring: Track failed signature checks, expired tokens, and audience mismatches.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
SPA / Frontend-Heavy App	Authorization Code + PKCE	Prevents code interception, aligns with modern browser security models	Low (standard library support)
Service-to-Service API	Client Credentials + mTLS	Eliminates user context, enforces mutual authentication at transport layer	Medium (certificate management)
Legacy Monolith Migration	OIDC with Backend-for-Frontend	Centralizes token validation, avoids refactoring client auth logic	High (initial BFF setup)
Mobile Native App	Authorization Code + PKCE + App Link/Deep Link	Bypasses browser token leakage, leverages OS credential storage	Low-Medium (platform-specific routing)

Configuration Template

// oidc.config.ts
export const OIDCConfig = {
  issuer: process.env.OIDC_ISSUER || 'https://auth.example.com/',
  clientId: process.env.OIDC_CLIENT_ID,
  redirectUri: process.env.OIDC_REDIRECT_URI,
  postLogoutRedirectUri: process.env.OIDC_POST_LOGOUT_URI,
  scopes: ['openid', 'profile', 'email'],
  tokenEndpoint: '/token',
  authorizationEndpoint: '/authorize',
  jwksUri: '/.well-known/jwks.json',
  userinfoEndpoint: '/userinfo',
  endSessionEndpoint: '/logout',
  clockToleranceSeconds: 30,
  requireHttps: process.env.NODE_ENV === 'production',
  cookieOptions: {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 86400,
    path: '/',
  },
  validation: {
    checkIssuer: true,
    checkAudience: true,
    checkExpiration: true,
    checkNonce: true,
    allowedAlgorithms: ['RS256', 'ES256'],
  },
};

Quick Start Guide

1. Register Application: Create a new client in your OIDC provider. Set redirect URI to http://localhost:3000/auth/callback, enable PKCE, and request openid profile email scopes.
2. Install Dependencies: Run npm install jose axios cookie-parser. These handle cryptographic validation, HTTP exchanges, and secure session management.
3. Configure Environment: Export OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_REDIRECT_URI. Point the issuer to your provider's base URL (e.g., https://auth.example.com/).
4. Initialize Flow: Generate PKCE parameters, redirect to /authorize, capture the callback code, exchange it server-side, validate the ID token, and set an HTTP-only session cookie.
5. Verify: Access a protected route. The middleware should extract the session cookie, validate the bound access token, and return user context or a 401 challenge.