curiositech/oauth-oidc-implementer

OAuth/OIDC Implementer

Expert in implementing OAuth 2.0 and OpenID Connect (OIDC) authentication flows. Specializes in secure token handling, social login integration, API authorization, and identity provider configuration.

Decision Points

Flow Selection Matrix

For Web Applications (with backend):

• If frontend + backend architecture → Authorization Code flow with client_secret
• If SPA (React/Vue) only → Authorization Code + PKCE (no client_secret)
• If mobile app → Authorization Code + PKCE + custom URI scheme

For API Access:

• If service-to-service authentication → Client Credentials flow
• If user delegation required → Authorization Code flow with offline_access scope
• If device has no browser (IoT/CLI) → Device Authorization flow

For Enterprise SSO:

• If SAML existing infrastructure → OIDC bridge or native SAML
• If modern identity provider → OIDC Authorization Code flow
• If legacy systems involved → Federation with protocol translation

Token Storage Decision Tree

Access Tokens:

• If server-side rendering → httpOnly cookie with SameSite=Lax
• If SPA with API calls → memory only, refresh on page load
• If mobile app → secure keychain/keystore

Refresh Tokens:

• Always httpOnly cookie for web apps (never localStorage)
• Secure storage for mobile apps
• Never expose to client JavaScript

Failure Modes

Invalid Grant Error

Detection: Error response contains "error": "invalid_grant" Root Cause: Authorization code expired (>10min) or PKCE verifier mismatch Fix: Implement proper code exchange timing and verify PKCE generation/storage

Token Expired Syndrome

Detection: API returns 401 with expired token, no automatic retry Root Cause: Missing token refresh logic or refresh token rotation failure Fix: Implement automatic refresh with race condition handling and fallback to login

State Mismatch Vulnerability

Detection: OAuth callback validation fails with state parameter errors Root Cause: State not properly stored/validated or CSRF attack in progress Fix: Verify state generation uses cryptographically secure randomness and server-side validation

Scope Creep Anti-pattern

Detection: Requesting excessive scopes (scope=* or kitchen-sink permissions) Root Cause: Over-requesting permissions instead of minimal viable scopes Fix: Request only needed scopes initially, use incremental authorization for additional permissions

Silent Login Loop

Detection: Infinite redirects between app and identity provider Root Cause: Session state mismatch or malformed logout implementation Fix: Implement proper session cleanup and logout flow with back-channel notification

Worked Example: SPA Social Login Implementation

Scenario: React app implementing "Login with Google" using Authorization Code + PKCE

Step 1: Initialize Flow

// Expert catches: PKCE generation must be cryptographically secure
const codeVerifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(32)));
const codeChallenge = base64URLEncode(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier)));

// Novice misses: State must be stored server-side to prevent tampering
const state = crypto.randomUUID();
sessionStorage.setItem('oauth_state', state);
sessionStorage.setItem('pkce_verifier', codeVerifier);

Step 2: Decision Point Navigation

• Flow chosen: Authorization Code + PKCE (SPA detected)
• Storage strategy: sessionStorage for temporary values (PKCE verifier, state)
• Scope minimal: openid profile email only

Step 3: Handle Callback

// Expert validates: State MUST match exactly
if (urlState !== sessionStorage.getItem('oauth_state')) {
  throw new Error('CSRF protection failed');
}

// Novice misses: Code verifier must be included in token exchange
const tokenRequest = {
  grant_type: 'authorization_code',
  code: authCode,
  code_verifier: sessionStorage.getItem('pkce_verifier'),
  client_id: CLIENT_ID,
  redirect_uri: REDIRECT_URI
};

Step 4: Token Handling

• Expert approach: Store access token in memory, implement refresh pattern
• Novice mistake: Storing refresh token in localStorage (security vulnerability)
• Correct implementation: Access token expires in 1 hour, automatic refresh before expiry

Quality Gates

Implementation checklist for production readiness:

• [ ] State parameter validated on callback (CSRF protection verified)
• [ ] PKCE code verifier uses crypto.getRandomValues() (not Math.random)
• [ ] Refresh tokens stored in httpOnly cookies (never accessible to JavaScript)
• [ ] Token expiry handled with automatic refresh and fallback to login
• [ ] Logout flow tested with token revocation and session cleanup
• [ ] JWT signature validation implemented using provider's JWKS endpoint
• [ ] Scope requests follow principle of least privilege
• [ ] Error handling covers network failures and invalid_grant scenarios
• [ ] Race conditions prevented in concurrent token refresh requests
• [ ] Production uses HTTPS for all OAuth endpoints and redirects

NOT-FOR Boundaries

Do NOT use this skill for:

• Session-based authentication → Use traditional cookie sessions instead
• API key management → Use api-security-specialist for static API keys
• Password hashing/storage → Use authentication-specialist for credential handling
• SAML implementation → Use enterprise-sso-architect for SAML-specific flows
• Custom JWT creation → Use jwt-specialist for application-specific token generation

Delegate to other skills:

• Certificate management → tls-certificate-manager
• Database user storage → database-architect
• Rate limiting auth endpoints → api-rate-limiter
• Security monitoring → security-monitoring-specialist