auth-flow-validation

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
| Check | Status | Details |
|-------|--------|---------|
| Endpoint path | OK | POST /auth/login |
| Request body | OK | { email, password } |
| Response structure | WARNING | Missing `expiresIn` field |
| Token storage | ERROR | Frontend uses localStorage, backend expects cookie |

### Token Refresh Flow
| Check | Status | Details |
|-------|--------|---------|
| Trigger condition | OK | 401 intercepted |
| Refresh endpoint | OK | POST /auth/refresh |
| Token placement | ERROR | Frontend sends in body, backend expects cookie |
| Retry mechanism | OK | Original request retried |

### 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