OAuth 2.0 Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: oauth2 for comprehensive documentation.

Authorization Code Flow (Recommended)

1. User clicks "Login with Google"
2. Redirect to provider:
   GET https://accounts.google.com/oauth/authorize
     ?client_id=xxx
     &redirect_uri=https://app.com/callback
     &response_type=code
     &scope=openid email profile
     &state=random_state

3. User authorizes, provider redirects:
   GET https://app.com/callback?code=xxx&state=random_state

4. Backend exchanges code for tokens:
   POST https://oauth2.googleapis.com/token
     client_id=xxx
     client_secret=xxx
     code=xxx
     grant_type=authorization_code
     redirect_uri=https://app.com/callback

5. Receive tokens:
   { "access_token": "...", "refresh_token": "...", "id_token": "..." }

Implementation

// Step 1: Generate auth URL
function getAuthUrl(): string {
  const params = new URLSearchParams({
    client_id: process.env.GOOGLE_CLIENT_ID,
    redirect_uri: `${process.env.APP_URL}/callback`,
    response_type: 'code',
    scope: 'openid email profile',
    state: generateRandomState(),
  });
  return `https://accounts.google.com/oauth/authorize?${params}`;
}

// Step 2: Handle callback
async function handleCallback(code: string) {
  const tokens = await exchangeCodeForTokens(code);
  const userInfo = await getUserInfo(tokens.access_token);
  const user = await findOrCreateUser(userInfo);
  return generateSessionToken(user);
}

When NOT to Use This Skill

• Simple JWT authentication - Use jwt skill for custom token-based auth
• NextAuth.js integration - Use nextauth skill for Next.js projects
• Internal authentication - Use traditional username/password with JWT
• API-to-API communication - Use API keys or mTLS

Common Flows

Flow	Use Case
Authorization Code	Web apps (server-side)
Authorization Code + PKCE	SPAs, mobile apps
Client Credentials	Machine-to-machine
Refresh Token	Long-lived sessions

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
No state parameter	Vulnerable to CSRF attacks	Always generate and validate state
PKCE without S256	Weak code challenge	Use S256 (SHA-256), not plain
Storing tokens in localStorage	XSS vulnerability	Use httpOnly cookies or secure storage
Ignoring provider errors	Silent failures	Handle all error codes properly
Hardcoded redirect URLs	Security risk	Use environment variables
No nonce validation	ID token replay attacks	Validate nonce for OpenID Connect

Quick Troubleshooting

Issue	Cause	Solution
"Invalid redirect_uri"	URL mismatch with provider	Exact match required, check protocol/trailing slash
"Invalid state"	CSRF token mismatch	Verify state cookie exists and matches
"Invalid code"	Code expired or used twice	Codes expire in ~10 minutes, can only be used once
"Invalid client"	Wrong client_id/secret	Verify credentials from provider console
CORS errors	Same-origin policy	Use backend proxy for token exchange
"Invalid grant"	Code verifier mismatch	Ensure code_verifier matches code_challenge

PKCE Extension

// For SPAs - no client_secret needed
const codeVerifier = generateRandomString(64);
const codeChallenge = base64url(sha256(codeVerifier));

// Add to auth URL
params.set('code_challenge', codeChallenge);
params.set('code_challenge_method', 'S256');

// Include in token exchange
body.code_verifier = codeVerifier;

Production Readiness

Security Configuration

// Secure state parameter (CSRF protection)
import { randomBytes, createHash } from 'crypto';

function generateState(): string {
  return randomBytes(32).toString('hex');
}

// Store state in httpOnly cookie before redirect
res.cookie('oauth_state', state, {
  httpOnly: true,
  secure: true,
  sameSite: 'lax', // Required for OAuth redirects
  maxAge: 10 * 60 * 1000, // 10 minutes
});

// Validate state on callback
function validateState(receivedState: string, storedState: string): void {
  if (!receivedState || !storedState || receivedState !== storedState) {
    throw new Error('Invalid state parameter - possible CSRF attack');
  }
}

PKCE Implementation (Required for SPAs/Mobile)

// Generate PKCE parameters
function generatePKCE(): { verifier: string; challenge: string } {
  const verifier = randomBytes(32)
    .toString('base64url')
    .replace(/[^a-zA-Z0-9]/g, '')
    .substring(0, 64);

  const challenge = createHash('sha256')
    .update(verifier)
    .digest('base64url');

  return { verifier, challenge };
}

// Store verifier securely (server-side session or encrypted cookie)
const { verifier, challenge } = generatePKCE();
session.codeVerifier = verifier;

// Include in authorization URL
const authUrl = new URL('https://provider.com/oauth/authorize');
authUrl.searchParams.set('code_challenge', challenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

// Include in token exchange
const tokenResponse = await fetch('https://provider.com/oauth/token', {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    code_verifier: session.codeVerifier,
    client_id: process.env.OAUTH_CLIENT_ID!,
    redirect_uri: process.env.OAUTH_REDIRECT_URI!,
  }),
});

Token Handling

// Secure token storage and refresh
async function handleTokens(tokens: OAuthTokens) {
  // Encrypt tokens before storing
  const encryptedAccess = encrypt(tokens.access_token);
  const encryptedRefresh = encrypt(tokens.refresh_token);

  // Store in database with user association
  await db.oauthTokens.upsert({
    where: { userId_provider: { userId, provider: 'google' } },
    create: {
      userId,
      provider: 'google',
      accessToken: encryptedAccess,
      refreshToken: encryptedRefresh,
      expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
    },
    update: {
      accessToken: encryptedAccess,
      refreshToken: encryptedRefresh,
      expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
    },
  });
}

// Auto-refresh expired tokens
async function getValidAccessToken(userId: string): Promise<string> {
  const stored = await db.oauthTokens.findUnique({
    where: { userId_provider: { userId, provider: 'google' } },
  });

  if (!stored) throw new Error('No OAuth tokens found');

  // Refresh if expired or expiring soon
  if (stored.expiresAt < new Date(Date.now() + 5 * 60 * 1000)) {
    const newTokens = await refreshOAuthToken(decrypt(stored.refreshToken));
    await handleTokens(newTokens);
    return newTokens.access_token;
  }

  return decrypt(stored.accessToken);
}

Provider Verification

// Verify ID token (for OpenID Connect)
import * as jose from 'jose';

async function verifyIdToken(idToken: string, provider: string): Promise<jose.JWTPayload> {
  const JWKS = jose.createRemoteJWKSet(
    new URL('https://www.googleapis.com/oauth2/v3/certs')
  );

  const { payload } = await jose.jwtVerify(idToken, JWKS, {
    issuer: 'https://accounts.google.com',
    audience: process.env.GOOGLE_CLIENT_ID!,
  });

  // Verify nonce if used
  if (payload.nonce !== session.nonce) {
    throw new Error('Invalid nonce');
  }

  return payload;
}

Monitoring Metrics

Metric	Alert Threshold
OAuth callback failures	> 50/hour
State validation failures	> 10/hour
Token refresh failures	> 20/hour
Invalid provider responses	> 5/hour

Error Handling

async function handleOAuthCallback(req: Request) {
  try {
    // Check for provider errors
    if (req.query.error) {
      const error = req.query.error as string;
      const description = req.query.error_description as string;

      if (error === 'access_denied') {
        // User cancelled - redirect to login
        return redirect('/login?cancelled=true');
      }

      throw new OAuthError(error, description);
    }

    // Validate state
    validateState(req.query.state, req.cookies.oauth_state);

    // Exchange code for tokens
    const tokens = await exchangeCode(req.query.code);

    // Create/update user
    const user = await findOrCreateUser(tokens);

    // Create session
    await createSession(user);

  } catch (error) {
    // Log security events
    logger.warn('OAuth callback error', {
      error: error.message,
      ip: req.ip,
      provider: 'google',
    });

    return redirect('/login?error=oauth_failed');
  }
}

Checklist

• State parameter for CSRF protection
• PKCE for all public clients (SPAs, mobile)
• Validate state before code exchange
• Verify ID token signature and claims
• Encrypt stored OAuth tokens
• Auto-refresh expired tokens
• Handle provider errors gracefully
• Log all OAuth security events
• Use localhost for dev redirect URIs
• Strict redirect URI validation
• Rate limit callback endpoint

Reference Documentation

• Provider Setup
• PKCE Flow