--- name: oauth2 description: | OAuth 2.0 authorization framework. Covers flows, tokens, and provider integration. Use for third-party authentication. USE WHEN: user mentions "OAuth", "Google login", "GitHub auth", "social login", "authorization code flow", "PKCE", asks about "third-party auth", "provider integration" DO NOT USE FOR: JWT tokens (use jwt skill), NextAuth.js (use nextauth skill), API keys, simple password auth allowed-tools: Read, Grep, Glob, Write, Edit --- # 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 ```typescript // 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 ```typescript // 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 ```typescript // 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) ```typescript // 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 ```typescript // 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 { 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 ```typescript // Verify ID token (for OpenID Connect) import * as jose from 'jose'; async function verifyIdToken(idToken: string, provider: string): Promise { 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 ```typescript 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](quick-ref/providers.md) - [PKCE Flow](quick-ref/pkce.md)