Server-Side CORS Configuration & Header Management

Server-side CORS configuration is the mechanism by which a web server controls which cross-origin requests browsers are permitted to complete, implemented through the Access-Control-* response header family defined in the WHATWG Fetch Standard (Living Standard, sections 3.2 and 4). Every CORS decision the browser makes is driven entirely by what the server returns — incorrect, missing, or duplicated headers cause requests to be blocked at the browser even when the network connection succeeds.

This guide covers the complete server-side responsibility: preflight routing, header directive semantics, dynamic origin validation, credential isolation, wildcard risk, reverse-proxy gotchas, and production debugging.

Key architectural principles:

• The WHATWG Fetch Standard defines CORS as an opt-in relaxation of the Same-Origin Policy, enforced by browsers on the client, not by the network on the wire.
• Every Access-Control-* directive must appear exactly once per response; duplicate headers cause immediate rejection by all major browsers.
• Access-Control-Allow-Origin must contain either the literal * or a single serialized origin — regular expressions are illegal per spec and must be evaluated server-side before writing the header.
• When Access-Control-Allow-Credentials: true is present, the origin value must be an exact echoed string; * is forbidden and browsers will block the response.
• Vary: Origin is mandatory on every response where the server conditionally sets Access-Control-Allow-Origin; omitting it causes CDN cache poisoning.
• Preflight OPTIONS responses must be routed and handled before any application middleware that reads or modifies the request body.
• Security boundaries for credentials (SameSite=None; Secure cookies, Authorization headers, TLS client certificates) require coordinated configuration at the cookie, application, and CORS layers simultaneously.

Header-Flow Reference

The table below maps every Access-Control-* directive to its role, allowed values, and the browser behaviour it controls.

CORS Preflight Mechanics & OPTIONS Routing

The browser classifies every cross-origin request as either simple or non-simple per WHATWG Fetch §4.1.1. A request is simple if it uses GET, HEAD, or POST with only safelisted request headers (Accept, Accept-Language, Content-Language, Content-Type restricted to application/x-www-form-urlencoded, multipart/form-data, or text/plain). Any deviation — a PUT/DELETE/PATCH method, a custom header like Authorization, or Content-Type: application/json — triggers a preflight OPTIONS exchange before the actual request is sent.

The server must intercept OPTIONS requests at the outermost middleware layer, before authentication guards, body parsers, or rate-limit middleware. A correct preflight response carries a 200 or 204 status and three directives: Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Max-Age. Chrome and Safari cap Access-Control-Max-Age at 600 seconds; Firefox accepts up to 86400 seconds. Set 600 for cross-browser consistency.

// Node.js / Express — preflight middleware (place before all routes)
app.use((req, res, next) => {
  const allowedOrigins = ['https://app.example.com', 'https://admin.example.com'];
  const origin = req.headers.origin;

  if (allowedOrigins.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    res.setHeader('Vary', 'Origin');
  }

  if (req.method === 'OPTIONS') {
    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,PATCH');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization,X-Request-ID');
    res.setHeader('Access-Control-Max-Age', '600');
    return res.sendStatus(204);
  }

  next();
});

Request Classification Matrix

The presence of Authorization in Access-Control-Request-Headers is the most common trigger teams overlook. Even a GET request becomes non-simple the moment the client sends a bearer token.

Access-Control Header Directives & Precedence

Full directive semantics are covered in the Access-Control-* Header Directives reference. The critical precedence rules for the server are:

Duplicate headers cause hard rejection. If two middleware layers both set Access-Control-Allow-Origin, the browser rejects the response with a CORS error even if both values are identical. Use proxy_hide_header in Nginx or equivalent stripping in your proxy to prevent upstream duplication.

Order of evaluation matters. Browsers read Access-Control-Allow-Origin first. If that check fails, the browser stops — it does not evaluate Access-Control-Allow-Credentials or Access-Control-Allow-Headers. Fix origin errors first when debugging cascading failures.

Vary: Origin is a cache-correctness requirement, not optional. When you conditionally echo different origin values, a CDN that does not see Vary: Origin will cache the first response and serve that cached header to all subsequent requests from other origins, causing hard CORS failures for legitimate users. Omitting Vary: Origin is one of the most common production bugs.

Access-Control-Expose-Headers governs script access, not browser blocking. By default, scripts can only read the seven safe response headers (Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma, plus Content-Length in some browsers). To expose X-Request-ID, ETag, or rate-limit headers to JavaScript, list them explicitly.

# Nginx — map-based dynamic origin validation
map $http_origin $cors_origin {
  default          "";
  "https://app.example.com"   $http_origin;
  "https://admin.example.com" $http_origin;
}

server {
  location /api/ {
    # Strip any upstream CORS headers before adding ours
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Credentials;

    add_header Access-Control-Allow-Origin  $cors_origin always;
    add_header Access-Control-Allow-Credentials true always;
    add_header Vary Origin always;

    if ($request_method = OPTIONS) {
      add_header Access-Control-Allow-Methods  'GET, POST, PUT, DELETE, PATCH' always;
      add_header Access-Control-Allow-Headers  'Content-Type, Authorization' always;
      add_header Access-Control-Max-Age        600 always;
      return 204;
    }

    proxy_pass http://backend;
  }
}

The always flag in add_header is essential: without it, Nginx only emits the header on 2xx responses and silently drops it on 4xx/5xx, causing CORS failures on error paths.

Dynamic Origin Validation & Allowlisting

Hardcoding origins in static configuration files creates drift: as staging, preview, and production environments multiply, the allowlist falls out of sync. Runtime validation against a centralized registry scales more reliably.

The canonical approach is exact string matching against a hash set loaded at startup (or refreshed on a short TTL):

# FastAPI / Python — middleware with exact-match allowlist
ALLOWED_ORIGINS: set[str] = {
    "https://app.example.com",
    "https://admin.example.com",
    "https://staging.example.com",
}

@app.middleware("http")
async def cors_middleware(request: Request, call_next):
    origin = request.headers.get("origin", "")
    is_allowed = origin in ALLOWED_ORIGINS

    if request.method == "OPTIONS" and is_allowed:
        return Response(
            status_code=204,
            headers={
                "Access-Control-Allow-Origin": origin,
                "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE,PATCH",
                "Access-Control-Allow-Headers": "Content-Type,Authorization",
                "Access-Control-Allow-Credentials": "true",
                "Access-Control-Max-Age": "600",
                "Vary": "Origin",
            },
        )

    response = await call_next(request)
    if is_allowed:
        response.headers["Access-Control-Allow-Origin"] = origin
        response.headers["Access-Control-Allow-Credentials"] = "true"
        response.headers["Vary"] = "Origin"
    return response

Subdomain patterns require full URL parsing. A suffix check for .example.com is insufficient — evil.example.com.attacker.com passes a naive suffix test. Always parse the origin as a URL, extract the hostname, and validate scheme, host, and port separately:

// Safe subdomain allowlist check — never use simple string suffix matching
function isAllowedOrigin(origin) {
  try {
    const url = new URL(origin);
    return (
      url.protocol === 'https:' &&
      (url.hostname === 'example.com' || url.hostname.endsWith('.example.com')) &&
      url.port === ''                    // no non-standard port
    );
  } catch {
    return false;                        // malformed origin → deny
  }
}

For architecture and caching strategies for the registry itself, see Dynamic Origin Validation Patterns.

Credential Sharing & Subdomain Isolation

Cross-origin credential transmission requires explicit consent at three layers simultaneously: the browser fetch() call (or XMLHttpRequest.withCredentials), the cookie attributes, and the server CORS headers.

Cookie requirements for cross-origin sharing:

Set-Cookie: session_id=abc123; Path=/; Domain=.example.com; Secure; HttpOnly; SameSite=None

The wildcard + credentials invariant. The WHATWG Fetch Standard prohibits Access-Control-Allow-Credentials: true alongside Access-Control-Allow-Origin: *. Browsers enforce this at the response evaluation step and block the request even after the network round-trip completes. There is no workaround: echo the exact origin string.

Subdomain tenant isolation. Multi-tenant architectures that share a root domain must be careful with Domain=.example.com cookie scoping. A session cookie scoped to the root domain is accessible to every subdomain, including attacker-controlled subdomains that may exist due to subdomain takeover vulnerabilities. Scope cookies to the minimum necessary hostname when isolation between tenants matters. Full isolation patterns are covered in Credential Sync Across Subdomains.

Security Boundary Mapping: Wildcard Prohibitions & Vary Requirements

Access-Control-Allow-Origin: * permits any origin to read the response body for requests without credentials. This is appropriate for public CDN assets, open APIs, and font files. It is inappropriate for any endpoint that relies on cookies, session tokens, or API keys for authentication — even if those credentials are not explicitly sent in that specific request, because CSRF attacks use the browser’s automatic cookie attachment.

Concrete risks of overly permissive policies:

• CSRF amplification: Endpoints that use cookies for authentication and return * enable cross-origin reads of authenticated responses. Combine allowlist-based CORS with per-request CSRF tokens on mutation endpoints.
• Information leakage via public metadata: Even unauthenticated endpoints may expose rate-limit counters, user identifiers in headers, or tenant slugs in JSON. Scope the allowlist to legitimate consumer origins.
• Wildcard on internal services: Internal APIs reachable from the browser (via a VPN or corporate network) should never emit Access-Control-Allow-Origin: *; a malicious page loaded in the internal browser can initiate requests to internal endpoints.

For detailed threat-modelling and boundary enforcement strategies, see Wildcard Risks & Mitigation.

Infrastructure Interaction: CDN, WAF & Reverse-Proxy Gotchas

Most CORS bugs in production are not application bugs — they are proxy-layer bugs. The application returns correct headers, but an intermediate layer strips, duplicates, or overwrites them.

Nginx add_header without always: Nginx only emits add_header directives on responses with status codes 200, 201, 204, 206, 301, 302, 303, 304, and 307. A 401 or 500 response silently drops all CORS headers, so the browser sees no Access-Control-Allow-Origin and reports a CORS failure rather than the actual HTTP error. Always add the always flag.

AWS ALB / API Gateway header injection: AWS Application Load Balancer can return its own CORS headers on OPTIONS responses when CORS support is enabled at the ALB level. If your backend also emits CORS headers, the response will contain duplicates and browsers will reject it. Disable CORS at the ALB level and manage it entirely in the application, or disable it in the application and use the ALB — never both.

Cloudflare cache and Vary: Origin: Cloudflare respects Vary: Origin but only when the response is cacheable. If your CORS endpoint returns Cache-Control: no-store, Cloudflare does not cache it at all, and Vary has no effect. For cacheable CORS responses (GET public APIs, static JSON), ensure Vary: Origin is present and Cache-Control has a non-zero max-age. Use a proxy bypass strategy for preflight caching at the edge.

WAF header inspection: Some WAF rules block requests containing Access-Control-Request-Headers values that list non-standard header names, treating them as injection attempts. Review WAF logs for blocked preflight OPTIONS requests before concluding the issue is server-side.

Load-balancer health check conflicts: Health check probes sometimes arrive on the same port as API traffic. If the health checker does not set an Origin header, a strict middleware that adds CORS headers only on origin-present requests will return different header sets for health vs. real traffic, causing CDN inconsistency.

Debugging Workflow: DevTools + curl

Step-by-step trace

1. Open DevTools Network tab. Filter by Fetch/XHR or type options in the filter to isolate preflight requests.
2. Inspect the OPTIONS request. Confirm Origin, Access-Control-Request-Method, and Access-Control-Request-Headers are present and correct.
3. Inspect the OPTIONS response. Verify status is 200 or 204. Check that Access-Control-Allow-Origin matches the request Origin exactly (case-sensitive). Check Access-Control-Allow-Headers includes every header the request sends.
4. Inspect the actual request. If the preflight passed, the browser sends the real request. Check the response again for Access-Control-Allow-Origin and Vary: Origin on the actual response — preflight success does not carry over to the main response.
5. Read the console error. Browser CORS errors specify which directive failed. “Response to preflight request doesn’t pass access control check” followed by “No ‘Access-Control-Allow-Origin’ header” means the preflight returned no matching header, not that the origin is wrong.

curl synthetic validation

# Test preflight response
curl -si -X OPTIONS https://api.example.com/v1/data \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Authorization, Content-Type" \
  | grep -i "access-control\|vary\|HTTP/"

# Test actual request with credentials
curl -si -X POST https://api.example.com/v1/data \
  -H "Origin: https://app.example.com" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}' \
  | grep -i "access-control\|vary\|HTTP/"

Error-code-to-cause mapping

Common Implementation Mistakes

Frequently Asked Questions