Auth Flow Validation - Quick Reference

When NOT to Use This Skill

• Security auditing - Use security skills

• OAuth provider configuration - Use oauth2 skill

• JWT implementation - Use jwt skill

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: jwt or oauth2 for protocol details.

Auth Flow Overview

┌─────────────────────────────────────────────────────────────────────┐ │ AUTHENTICATION FLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Frontend Backend │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 1. Login │──────────→│ POST /auth │ │ │ │ Form │ │ /login │ │ │ └──────────────┘ └──────┬───────┘ │ │ ↑ │ │ │ │ ↓ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 2. Store │←──────────│ Return JWT │ │ │ │ Tokens │ │ + Refresh │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ ↓ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 3. API Call │──────────→│ Validate JWT │ │ │ │ + Auth Header│ │ │ │ │ └──────────────┘ └──────┬───────┘ │ │ ↑ │ │ │ │ 401 Unauthorized │ │ │ │←─────────────────────────┤ │ │ │ │ │ │ ↓ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 4. Refresh │──────────→│ POST /auth │ │ │ │ Token │ │ /refresh │ │ │ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘

Validation Checklist

Login Flow

Step Frontend Backend Validation

Endpoint POST /auth/login POST /auth/login Path match

Request Body { email, password } { email, password } Schema match

Response { accessToken, refreshToken, user } Same structure Type match

Token Storage localStorage/httpOnly cookie Expects cookie or header Method match

Error Response Handle 401, 400 Returns structured error Error format

Token Refresh Flow

Step Frontend Backend Validation

Trigger 401 response intercepted Returns 401 on expired Consistent behavior

Endpoint POST /auth/refresh POST /auth/refresh Path match

Request refreshToken in body/cookie Expects same location Method match

Response New accessToken Returns new token Structure match

Retry Original request retried Accepts new token Flow complete

Common Discrepancies

1. Token Storage Mismatch

// Backend expects: HttpOnly cookie res.cookie('accessToken', token, { httpOnly: true, secure: true, sameSite: 'strict', });

// Frontend stores: localStorage (MISMATCH!) localStorage.setItem('accessToken', response.accessToken);

// Frontend should: Let backend set cookie // No manual storage needed - cookie sent automatically

2. Authorization Header Format

// Backend expects Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// Frontend sends (WRONG) Authorization: eyJhbGciOiJIUzI1NiIs... // Missing "Bearer "

// Frontend sends (WRONG) Authorization: bearer eyJhbGciOiJIUzI1NiIs... // Wrong case

// Correct frontend implementation const token = getAccessToken(); fetch('/api/users', { headers: { 'Authorization': Bearer ${token}, }, });

3. Refresh Token Placement

// Backend expects: Cookie app.post('/auth/refresh', (req, res) => { const refreshToken = req.cookies.refreshToken; // From cookie });

// Frontend sends: Body (MISMATCH!) fetch('/auth/refresh', { method: 'POST', body: JSON.stringify({ refreshToken }), // Wrong! });

// Correct: Cookie sent automatically fetch('/auth/refresh', { method: 'POST', credentials: 'include', // Include cookies });

4. Token Expiration Handling

// Backend: Token expires after 15 minutes const token = jwt.sign(payload, secret, { expiresIn: '15m' });

// Frontend: No expiration check (BAD) function makeAuthenticatedRequest() { return fetch('/api/data', { headers: { Authorization: Bearer ${token} }, }); }

// Frontend: Check expiration before request (GOOD) function makeAuthenticatedRequest() { const token = getAccessToken();

if (isTokenExpired(token)) { await refreshAccessToken(); }

return fetch('/api/data', { headers: { Authorization: Bearer ${getAccessToken()} }, }); }

// Helper to check expiration function isTokenExpired(token: string): boolean { const payload = JSON.parse(atob(token.split('.')[1])); return payload.exp * 1000 < Date.now(); }

Token Refresh Patterns

Axios Interceptor

import axios from 'axios';

const api = axios.create({ baseURL: '/api', });

// Request interceptor - add token api.interceptors.request.use((config) => { const token = getAccessToken(); if (token) { config.headers.Authorization = Bearer ${token}; } return config; });

// Response interceptor - handle 401 api.interceptors.response.use( (response) => response, async (error) => { const originalRequest = error.config;

if (error.response?.status === 401 && !originalRequest._retry) {
  originalRequest._retry = true;

  try {
    const newToken = await refreshAccessToken();
    originalRequest.headers.Authorization = `Bearer ${newToken}`;
    return api(originalRequest);
  } catch (refreshError) {
    // Refresh failed - logout user
    logout();
    return Promise.reject(refreshError);
  }
}

return Promise.reject(error);

} );

Fetch with Refresh

async function fetchWithAuth(url: string, options: RequestInit = {}) { let token = getAccessToken();

// Check if token expired if (isTokenExpired(token)) { token = await refreshAccessToken(); }

const response = await fetch(url, { ...options, headers: { ...options.headers, Authorization: Bearer ${token}, }, });

// Handle 401 (token rejected by server) if (response.status === 401) { token = await refreshAccessToken();

return fetch(url, {
  ...options,
  headers: {
    ...options.headers,
    Authorization: `Bearer ${token}`,
  },
});

}

return response; }

React Query Auth

import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({ defaultOptions: { queries: { retry: (failureCount, error) => { // Don't retry on 401 if (error instanceof Response && error.status === 401) { return false; } return failureCount < 3; }, }, }, });

// Global error handler queryClient.setDefaultOptions({ mutations: { onError: (error) => { if (error instanceof Response && error.status === 401) { // Redirect to login window.location.href = '/login'; } }, }, });

OpenAPI Auth Definition

JWT Bearer

components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT

security:

• bearerAuth: []

paths: /users: get: security: - bearerAuth: [] responses: 401: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error'

Cookie Auth

components: securitySchemes: cookieAuth: type: apiKey in: cookie name: accessToken

paths: /users: get: security: - cookieAuth: []

Validation Report Template

Auth Flow Validation Report

Login Flow

Token Refresh Flow

Recommendations

1. Critical: Change token storage to httpOnly cookies
2. Critical: Update refresh to use credentials: 'include'
3. Warning: Add expiresIn to login response for proactive refresh

Anti-Patterns

Anti-Pattern Why It's Bad Correct Approach

localStorage for tokens XSS vulnerability Use httpOnly cookies

No token refresh Poor UX, forced logout Implement refresh flow

Refresh on every request Performance Refresh on 401 or near expiry

No logout on refresh fail Security risk Clear tokens and redirect

Hardcoded token expiry Drift with backend Parse from token or response

Quick Troubleshooting

Issue Likely Cause Solution

401 on login Wrong credentials format Check request body schema

401 after refresh Refresh token also expired Re-authenticate user

Infinite refresh loop Not marking retried requests Add retry flag

CORS on auth endpoints Missing credentials config Add credentials: 'include'

Token not sent Authorization header format Check "Bearer " prefix

Related Skills

• OpenAPI Contract

• Error Contract

• JWT Security