Origin Matching Rules & Validation

Without strict origin-tuple matching, a browser has no reliable way to distinguish a legitimate cross-origin request from a forged one. When validation is absent or incorrectly implemented, authenticated API endpoints become reachable from any domain the attacker controls — no XSS required, just a crafted fetch() call.

This page is part of Core CORS Mechanics & Same-Origin Policy Fundamentals, which covers how the browser enforces the same-origin policy end to end. Here the focus is narrower: the exact algorithm browsers use to parse and serialize an origin, the rules servers must follow when comparing it, and the secure allowlist patterns that tie both sides together.

How the Origin Tuple Is Built and Serialized

The authoritative definition lives in RFC 6454 and the WHATWG URL Standard. A browser constructs an origin as a three-part tuple — (scheme, host, port) — and serializes it to a single ASCII string before attaching it to the Origin request header.

The diagram below shows the normalization pipeline every browser runs before serialization:

Key normalization invariants:

• Scheme and host are lowercased. HTTPS://App.Example.com becomes https://app.example.com.
• Default ports are omitted. Port 80 for http and port 443 for https are dropped from the serialized string. An explicit :443 suffix causes a mismatch against an allowlist entry without it.
• Unicode hostnames are Punycode-encoded. münchen.de becomes xn--mnchen-3ya.de before comparison.
• Path, query, and fragment are discarded. The origin tuple never includes anything past the authority component.
• Trailing slashes are dropped. https://example.com/ serializes to https://example.com.

Normalization examples

Understanding how how browsers evaluate the same-origin policy handles opaque origins and sandboxed contexts prevents false-positive validation failures when one of these invariants applies unexpectedly.

Header and Parameter Reference

The Access-Control-Allow-Origin (ACAO) header is the server’s sole mechanism for declaring which origin is permitted to read a response. All comparison happens after the browser’s normalization pipeline runs.

The browser enforces two constraints that cannot be worked around in the header itself:

1. Wildcard + credentials is always blocked. When Access-Control-Allow-Origin: * appears alongside Access-Control-Allow-Credentials: true, the browser discards the response regardless of origin. This is a hard spec prohibition, not a browser quirk.
2. Comma-separated lists are invalid. The ACAO header cannot contain https://a.com, https://b.com. The browser treats the entire string — commas included — as a literal origin to match, which will always fail.

Step-by-Step Implementation

1. Build the allowlist

Store normalized origin strings — no trailing slashes, no default ports — in a data structure that supports O(1) lookup. Configuration files or environment variables are preferable to hardcoded values so staging origins never appear in production.

# Nginx: map-based allowlist with dynamic ACAO reflection
map $http_origin $cors_origin {
    default                          "";
    "https://app.secure-platform.io" "https://app.secure-platform.io";
    "https://admin.secure-platform.io" "https://admin.secure-platform.io";
}

server {
    location /api/ {
        if ($cors_origin != "") {
            add_header Access-Control-Allow-Origin $cors_origin always;
            add_header Vary Origin always;
        }

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

        proxy_pass http://upstream;
    }
}

2. Parse and validate the Origin header

On every request, read req.headers.origin (not Host) and perform a strict set lookup before writing any CORS header:

// Express/Node: strict set-based validation with dynamic reflection
const ALLOWED_ORIGINS = new Set([
  'https://app.secure-platform.io',
  'https://admin.secure-platform.io'
]);

function corsMiddleware(req, res, next) {
  const origin = req.headers.origin;

  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  }

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

  next();
}

3. Normalize before comparing (when using regex patterns)

If your allowlist must cover a subdomain range, normalize the incoming value before testing it. Explicitly strip any trailing :443 or :80 that a misbehaving client might send, then test against a pattern anchored at both ends:

// Safe subdomain-range validation with explicit port normalization
const ORIGIN_PATTERN = /^https:\/\/([a-z0-9-]+\.)?secure-platform\.io$/;

function isValidOrigin(origin) {
  if (!origin || typeof origin !== 'string') return false;
  // Normalize explicit default ports to implicit form before matching
  const normalized = origin.replace(/:443$/, '').replace(/:80$/, '');
  return ORIGIN_PATTERN.test(normalized);
}

Anchoring with ^ and $ prevents bypass attempts such as https://evil.secure-platform.io.attacker.com.

4. Echo the matched origin, not a recomputed value

Write the value from the Set (or the matched allowlist entry) directly to the response header — not a recomputed version. This avoids subtle bugs where normalization differences between your code and the browser produce a mismatch. The reflected value must be byte-for-byte identical to what the browser sent.

5. Always set Vary: Origin

Any time ACAO is set dynamically, append Origin to the Vary header. Omitting it means a CDN or reverse proxy may cache a response with one origin’s ACAO value and serve it to requests from a different origin, producing intermittent failures that are hard to reproduce. See handling the Vary: Origin header correctly for caching-layer specifics.

Edge Cases and Security Boundaries

Subdomain normalization

Subdomains are fully independent origins. https://api.example.com and https://app.example.com are distinct tuples even though they share a registrable domain. Your allowlist must enumerate each subdomain explicitly, or use a validated subdomain pattern as shown in step 3 above.

The null origin

Browsers send Origin: null from sandboxed iframes (<iframe sandbox> without allow-same-origin), data: URLs, and some file:// contexts. Reflecting null in the ACAO header is almost always wrong: it grants access to any sandboxed context on any page, not just your own. Reject null explicitly:

if (origin && origin !== 'null' && ALLOWED_ORIGINS.has(origin)) {
  res.setHeader('Access-Control-Allow-Origin', origin);
}

If you genuinely need a sandboxed iframe to reach your API, add allow-same-origin to the sandbox attribute and serve the iframe from a controlled subdomain.

Opaque responses from no-cors fetches

A fetch(url, { mode: 'no-cors' }) call returns an opaque response: status 0, empty body, no readable headers. The browser still enforces origin isolation — JavaScript cannot inspect the response — so opaque responses cannot be used to exfiltrate data. They are only appropriate for fire-and-forget requests such as telemetry pings.

Redirects and intermediate origins

When a credentialed request is redirected, the browser strips the Authorization header and may rewrite the Origin to null depending on the redirect type. Avoid issuing redirects for authenticated cross-origin endpoints; return the final URL directly.

Sec-Fetch-Site as a secondary signal

Modern browsers send Sec-Fetch-Site: cross-site (or same-origin, same-site, none) on all requests. This header is set by the browser and cannot be spoofed by JavaScript. Use it as a supplementary check, not a replacement for ACAO validation, because older browsers and non-browser HTTP clients do not send it.

Proxy and CDN Interaction

Origin validation breaks silently when an intermediary rewrites or drops the Origin header. Three patterns cause this:

Proxy stripping. Nginx and HAProxy may omit non-standard request headers by default. Add explicit pass-through:

proxy_set_header Origin $http_origin;

For AWS Application Load Balancer, ensure the listener rule does not include an Origin header override. For Cloudflare, Origin is forwarded unchanged to the origin server; no additional configuration is needed.

CDN cache keying. A CDN that does not key its cache on Origin will serve one response to all origins. The cached ACAO value will match only the first requester. Setting Vary: Origin on every dynamic ACAO response instructs the CDN to maintain separate cache entries per origin.

TLS termination at the load balancer. When TLS terminates before your application server, the Origin header the server sees still contains https:// — the scheme reflects what the client used, not what protocol the internal hop used. Do not rewrite the scheme inside your validation logic based on X-Forwarded-Proto.

The preflight optimization and caching strategies section covers how Access-Control-Max-Age and CDN configuration interact with the preflight cache — reducing redundant OPTIONS requests without loosening origin validation.

DevTools and curl Verification Checklist

Use this checklist after deploying any change to your CORS validation logic:

• Open DevTools → Network, filter by XHR/Fetch, trigger the cross-origin request, and confirm the Origin request header matches your allowlist entry exactly (scheme, host, port).
• Confirm Access-Control-Allow-Origin in the response equals the Origin value byte-for-byte — copy both and diff them if the request is failing.
• Confirm Vary: Origin is present in the response headers.
• Test a preflight with curl: curl -v -X OPTIONS -H "Origin: https://app.secure-platform.io" -H "Access-Control-Request-Method: POST" https://api.target.io/endpoint — verify the response includes ACAO and a 204 status.
• Test a rejected origin: curl -v -X OPTIONS -H "Origin: https://evil.com" https://api.target.io/endpoint — confirm ACAO is absent from the response.
• Test the null origin: curl -v -H "Origin: null" https://api.target.io/endpoint — confirm ACAO is absent.
• Check CDN behavior: make two requests with different allowed origins and confirm each response carries the corresponding ACAO value (not a cached value from the first request).
• Cross-reference any 403/401 responses against your authentication middleware — these indicate server-side rejection before CORS evaluation, not an origin mismatch.

For OPTIONS endpoint–specific verification, see designing lightweight OPTIONS endpoints.

Common Mistakes

FAQ