Build Log: Untangling SameSite, Same-Origin, and Cookie Auth in a Microservice Platform

Current Situation Analysis

Migrating authentication from browser storage tokens to HTTP-only cookies is frequently treated as a backend configuration task. Engineering teams assume that swapping Authorization: Bearer headers for Set-Cookie responses will seamlessly improve security posture. In practice, this migration consistently fails in staging or production because the root friction point is not the authentication logic itself, but the interaction between browser security models and deployment topology.

The industry pain point centers on a fundamental misunderstanding of how modern browsers evaluate cross-origin requests versus cross-site requests. Teams routinely configure SameSite=None; Secure cookies to force authentication across microservices, inadvertently expanding their CSRF attack surface. Others deploy separate API hostnames without aligning CORS credential headers, resulting in silent session drops that only surface during user acceptance testing. The problem is overlooked because backend frameworks abstract away HTTP header negotiation, leading developers to treat cookie attributes as static constants rather than topology-dependent variables.

Data from production deployments consistently shows that cookie authentication failures correlate directly with hostname divergence. When a frontend application and an API gateway share a single hostname but different ports or paths, browsers treat them as same-origin. When they diverge to separate subdomains, the browser shifts to same-site evaluation. Reverse proxies mask backend complexity but do not alter the URL bar, which remains the browser's source of truth for origin calculation. Ignoring this distinction forces teams to over-engineer CORS stacks, disable security headers, or maintain dual authentication strategies during migration windows.

WOW Moment: Key Findings

The critical insight emerges when mapping deployment topology against browser security evaluation. Two identical backend codebases will exhibit completely different authentication behavior depending solely on how URLs are presented to the client. The browser does not care about internal service mesh routing, container orchestration, or proxy headers. It evaluates cookies against the scheme, host, and port visible in the address bar.

Deployment Topology	Browser Origin Perception	Cookie Policy Behavior	CORS Overhead
Single Gateway (Path-Based)	Same-Origin	SameSite=Strict attaches automatically	None
Separate API Hostnames	Cross-Origin, Same-Site	SameSite=Strict attaches with credentials flag	Mandatory credentials: 'include'
Cross-Domain Services	Cross-Origin, Cross-Site	SameSite=None; Secure required	Full CORS preflight stack

This finding matters because it decouples security configuration from backend implementation. Teams can eliminate SameSite=None entirely for internal microservice communication by aligning routing topology with same-site boundaries. The browser's strict cookie enforcement becomes a security asset rather than a deployment obstacle. This enables zero-trust session management without sacrificing developer velocity or introducing cross-site request forgery vulnerabilities.

Core Solution

Building a resilient cookie authentication layer requires topology-first design. The implementation sequence must start with URL architecture, proceed to cookie attribute alignment, and conclude with client-side credential propagation.

Step 1: Audit Deployment Topology

Map every public-facing hostname and path. Determine what the browser actually sees after DNS resolution and proxy routing. If the frontend and all backend services resolve to https://platform.example.com with path-based routing, you are operating in a same-origin environment. If the API lives at https://api.example.com, you are in a cross-origin, same-site environment.

Step 2: Align Cookie Attributes with Topology

Never default to SameSite=None. For same-origin or same-site deployments, enforce SameSite=Strict. This blocks third-party cookie attachment while preserving first-party session continuity. Combine with HttpOnly to prevent JavaScript access and Secure to enforce TLS transmission.

// SessionManager.ts
import { Response } from 'express';

export class SessionManager {
  static attachAuthCookie(res: Response, sessionId: string): void {
    const isProduction = process.env.NODE_ENV === 'production';
    
    res.cookie('platform_session', sessionId, {
      httpOnly: true,
      secure: isProduction,
      sameSite: 'strict',
      maxAge: 24 * 60 * 60 * 1000, // 24 hours
      path: '/',
      domain: isProduction ? '.example.com' : undefined
    });
  }

  static clearAuthCookie(res: Response): void {
    res.clearCookie('platform_session', {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'strict',
      path: '/'
    });
  }
}

Step 3: Configure Client-Side Credential Propagation

Browsers will not attach cookies to cross-origin requests unless explicitly instructed. Update all HTTP clients to include credentials. Wildcard CORS origins are incompatible with credential transmission; servers must reflect the exact requesting origin.

// NetworkClient.ts
export class NetworkClient {
  private static readonly BASE_URL = process.env.API_ENDPOINT || '/api';

  static async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
    const response = await fetch(`${this.BASE_URL}${endpoint}`, {
      ...options,
      credentials: 'include',
      headers: {
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
  }
}

Step 4: Implement Topology-Aware Routing

For path-based deployments, configure the gateway to route API traffic and static assets under distinct prefixes. This prevents collision between backend endpoints and frontend asset resolution.

# Gateway routing configuration
server {
    listen 443 ssl;
    server_name platform.example.com;

    # Frontend application
    location /app/ {
        alias /var/www/frontend/dist/;
        try_files $uri $uri/ /app/index.html;
    }

    # API services
    location /api/ {
        proxy_pass http://backend_cluster;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Architecture Rationale

Path-based routing eliminates cross-origin friction entirely. The browser perceives a single origin, allowing SameSite=Strict cookies to attach automatically without CORS negotiation. Subdomain routing introduces cross-origin evaluation but maintains same-site boundaries, requiring explicit credential flags but preserving strict cookie scoping. The choice depends on organizational constraints: path routing simplifies security but requires careful asset path management; subdomain routing isolates services but demands rigorous CORS configuration. Always terminate TLS at the edge; Secure cookies will be silently dropped by browsers over plaintext HTTP, regardless of backend configuration.

Pitfall Guide

1. Proxy Origin Illusion

Explanation: Teams assume that routing traffic through a reverse proxy changes the browser's origin evaluation. The proxy only masks backend topology; the URL bar remains the source of truth. Fix: Verify origin calculation by inspecting window.location.origin in the browser console. Configure cookie domains and CORS headers against the public hostname, not internal service addresses.

2. Unnecessary SameSite Relaxation

Explanation: Setting SameSite=None for internal microservice communication expands CSRF attack surface without providing functional benefit when services share a registrable domain. Fix: Audit eTLD+1 boundaries. If frontend and API share example.com, enforce SameSite=Strict. Reserve None only for genuine cross-domain third-party integrations.

3. Secure Cookie Drop on HTTP

Explanation: Browsers reject Secure cookies over unencrypted connections. Deployments using raw IPs or plaintext HTTP will experience silent authentication failures. Fix: Enforce TLS termination before the application layer. Use Let's Encrypt or enterprise certificates. Validate cookie transmission with browser developer tools network tab before debugging backend logic.

4. SPA Path Collision

Explanation: Hosting frontend assets and API endpoints under identical prefixes causes routing conflicts. The gateway cannot distinguish between /billing/invoices (API route) and /billing/ (frontend asset). Fix: Implement strict prefix separation. Reserve /api/ for backend services and /app/ or /ui/ for static assets. Update build tool base paths and router basenames accordingly.

5. CORS Credential Mismatch

Explanation: Using Access-Control-Allow-Origin: * with credentials: 'include' violates browser security policy. Preflight requests will fail, and cookies will not attach. Fix: Reflect the requesting origin dynamically. Validate against an allowlist before setting Access-Control-Allow-Origin. Ensure Access-Control-Allow-Credentials: true is present.

6. Build Tool Path Drift

Explanation: Frontend bundlers default to root-relative asset paths. Deploying under /app/ without configuring the base path causes 404 errors for JavaScript and CSS bundles. Fix: Align Vite base, Webpack publicPath, and framework router basename with the deployment prefix. Test production builds locally using a static server before gateway deployment.

7. Dual Authentication State

Explanation: Running JWT bearer tokens and cookie sessions simultaneously during migration creates inconsistent authorization states. Middleware may validate one token while ignoring the other. Fix: Implement atomic migration phases. Disable JWT validation in production middleware before enabling cookie parsing. Use feature flags to control authentication strategy rollout.

Production Bundle

Action Checklist

• Map public hostnames and paths to determine browser origin perception
• Verify TLS termination exists before application layer routing
• Configure SameSite=Strict for same-site deployments; avoid None unless cross-domain
• Update all HTTP clients to include credentials: 'include'
• Implement dynamic CORS origin reflection; remove wildcard * with credentials
• Separate API and frontend routing prefixes to prevent asset collision
• Align frontend build base paths and router basenames with deployment topology
• Monitor Set-Cookie header transmission rates in production analytics

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal microservices sharing domain	Path-based single gateway	Eliminates CORS, simplifies cookie scoping, reduces infrastructure complexity	Low (single certificate, unified routing)
Public API + internal frontend	Subdomain routing (api. + app.)	Isolates service boundaries while maintaining same-site cookie behavior	Medium (CORS configuration, dual certificate management)
Third-party partner integration	Cross-domain with SameSite=None	Required for cross-site cookie attachment; must enforce strict TLS and CSRF tokens	High (security overhead, monitoring, compliance)
Legacy monolith migration	Phased cookie rollout with feature flags	Prevents session disruption; allows gradual JWT deprecation	Low (engineering time, minimal infra changes)

Configuration Template

// auth.config.ts
export const CookieConfig = {
  name: 'platform_session',
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'strict' as const,
  maxAge: 86400000,
  path: '/',
  domain: process.env.NODE_ENV === 'production' ? '.example.com' : undefined
};

// cors.middleware.ts
import { Request, Response, NextFunction } from 'express';

const ALLOWED_ORIGINS = new Set([
  'https://app.example.com',
  'https://platform.example.com'
]);

export function corsMiddleware(req: Request, res: Response, next: NextFunction) {
  const origin = req.headers.origin;
  
  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  }

  if (req.method === 'OPTIONS') {
    return res.sendStatus(204);
  }

  next();
}

Quick Start Guide

1. Audit Topology: Run window.location.origin in your frontend console. Document the exact hostname, scheme, and port visible to users.
2. Configure Edge TLS: Ensure your load balancer or gateway terminates HTTPS. Verify certificate validity and HSTS headers.
3. Set Cookie Attributes: Apply HttpOnly, Secure, and SameSite=Strict to your session cookie. Match the domain to your registrable domain (eTLD+1).
4. Update Client Requests: Add credentials: 'include' to all fetch/Axios calls. Remove manual Authorization header injection.
5. Validate Transmission: Open browser developer tools → Network tab → filter by Set-Cookie. Confirm cookies appear in responses and attach to subsequent requests.