gRPC-Web looks simple on the surface: your browser app makes RPC calls, your backend answers, everybody wins. Then CORS shows up and turns a clean protocol choice into a deployment problem.

I’ve hit this enough times to have a strong opinion: CORS for gRPC-Web is less about “turning on cross-origin access” and more about choosing where protocol translation and policy enforcement should live. That choice affects debugging, security posture, local development, and whether your frontend team hates you by Friday.

Why gRPC-Web triggers CORS pain

Normal gRPC uses HTTP/2 and binary framing that browsers don’t expose directly in fetch or XHR. gRPC-Web works around that by sending browser-compatible requests, usually through a proxy or server layer that translates between gRPC-Web and native gRPC.

Because the browser is involved, CORS rules apply.

A typical gRPC-Web request often includes non-simple headers like:

  • content-type: application/grpc-web+proto
  • x-grpc-web: 1
  • x-user-agent: grpc-web-javascript/...

That means preflight requests are common. If your server or proxy doesn’t answer OPTIONS correctly, the app fails before your RPC handler ever sees traffic.

The main ways to handle CORS for gRPC-Web

There are really three patterns:

  1. Handle CORS at the gRPC-Web proxy
  2. Handle CORS in the application server
  3. Avoid cross-origin entirely with same-origin deployment

I’d rank them in that order for most teams.


1. CORS at the gRPC-Web proxy

This is the most practical setup.

If you’re using Envoy or another edge/proxy layer to terminate browser traffic and translate gRPC-Web to gRPC, that proxy is the right place to enforce CORS.

Why this usually wins

The browser talks to the proxy first, not your upstream gRPC service. So the proxy is the component that must correctly answer preflight requests and attach the right response headers.

That gives you a clean split:

  • browser concerns at the edge
  • RPC logic in the service
  • less duplicated CORS config across backends

Pros

  • Single place to manage CORS
  • Preflight handled before app code
  • Works well with multiple gRPC services behind one frontend
  • Cleaner backend services
  • Easier to audit allowed origins and headers

Cons

  • Another config surface to maintain
  • Proxy misconfig can be opaque
  • Local development can drift from production
  • You still need to expose gRPC metadata intentionally

Example: headers you’ll usually need

For gRPC-Web, a CORS policy often needs to allow:

  • POST
  • OPTIONS
  • content-type
  • x-grpc-web
  • grpc-timeout
  • authorization headers if auth is used

And if the browser needs to read response metadata, you need Access-Control-Expose-Headers.

That part gets missed a lot.

Real APIs do this too. api.github.com responds with:

access-control-allow-origin: *
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset, Warning

That’s a useful reminder: allowing cross-origin requests is only half the story. If your app needs trailers or metadata, expose them deliberately.

Envoy-style config shape

Exact config varies, but the policy usually looks like this:

cors:
  allow_origin_string_match:
    - exact: "https://app.example.com"
  allow_methods: "POST, OPTIONS"
  allow_headers: "content-type,x-grpc-web,grpc-timeout,authorization"
  expose_headers: "grpc-status,grpc-message,grpc-status-details-bin"
  max_age: "86400"

For gRPC-Web, exposing grpc-status and grpc-message is commonly required so browser code can interpret failures correctly.

If you need official reference material, use the gRPC-Web docs and your proxy’s official docs.


2. CORS in the application server

This can work, but I only like it when the app server itself is directly serving browser-compatible traffic and you don’t have a separate edge proxy doing translation.

If your app is already handling gRPC-Web natively, then sure, keep CORS there. Otherwise this tends to spread browser policy into services that shouldn’t care.

Pros

  • Config lives close to business logic
  • Can be easier in simple deployments
  • No need to depend on proxy-specific features
  • Good for smaller teams with one service

Cons

  • Harder to standardize across services
  • Every service can drift
  • Preflight logic gets duplicated
  • Backend engineers end up owning browser behavior
  • Annoying in polyglot environments

Example in Node/Express

If you’re exposing a gRPC-Web-compatible endpoint from a Node service, the CORS handling often looks something like this:

import express from "express";

const app = express();

const allowedOrigins = new Set([
  "https://app.example.com",
  "http://localhost:5173"
]);

app.use((req, res, next) => {
  const origin = req.headers.origin;

  if (origin && allowedOrigins.has(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Vary", "Origin");
    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
    res.setHeader(
      "Access-Control-Allow-Headers",
      "content-type,x-grpc-web,grpc-timeout,authorization"
    );
    res.setHeader(
      "Access-Control-Expose-Headers",
      "grpc-status,grpc-message,grpc-status-details-bin"
    );
  }

  if (req.method === "OPTIONS") {
    return res.status(204).end();
  }

  next();
});

This works, but once you have five services and three environments, it gets messy fast.

My rule of thumb: if the browser traffic hits an edge layer anyway, CORS belongs there.


3. Same-origin deployment to avoid CORS

This is the underrated option. If your frontend and gRPC-Web endpoint are served from the same origin, the browser doesn’t need CORS at all.

That means fewer moving parts, fewer weird browser errors, and less security foot-gunning.

Pros

  • No CORS preflight headaches
  • Simpler browser behavior
  • Fewer headers to maintain
  • Less attack surface from bad wildcard policies
  • Usually the easiest experience for frontend teams

Cons

  • Can complicate infrastructure
  • Less flexible for multi-domain setups
  • Harder when APIs are shared across many clients
  • May require reverse proxy routing changes

Example architecture

Instead of this:

  • https://app.example.com
  • https://api.example.net

Use this:

  • https://app.example.com
  • https://app.example.com/grpc/* → reverse proxied to your gRPC-Web gateway

If I have the choice, I prefer same-origin for internal apps and controlled environments. It avoids a whole category of support tickets.


Wildcard vs explicit origins

For public, non-credentialed APIs, Access-Control-Allow-Origin: * is fine. GitHub does exactly that for parts of its API.

For authenticated gRPC-Web apps, wildcard origins are usually the wrong move.

If you use cookies or HTTP auth with credentials, you need a specific origin, not *. And you should return Vary: Origin when dynamically reflecting allowed origins.

Bad pattern:

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

Browsers reject that combination anyway, and it signals confused policy design.

Better pattern:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin

Headers people forget for gRPC-Web

The common misses:

  • grpc-status
  • grpc-message
  • grpc-status-details-bin
  • authorization in allowed request headers
  • OPTIONS in allowed methods
  • Vary: Origin when origin is dynamic

If your frontend says the network call “succeeded” but your app can’t read the error details, missing Access-Control-Expose-Headers is a likely cause.

That’s the same lesson you can infer from GitHub’s exposed headers list: useful metadata is only useful if the browser is allowed to reveal it to JavaScript.


Security tradeoffs

CORS is not auth. It’s browser policy.

Your gRPC service still needs real authentication and authorization. CORS only decides whether browser JavaScript from one origin can read responses from another.

I’ve seen teams treat a strict allowlist as if it were a security boundary. It’s not. Non-browser clients don’t care about CORS at all.

If you’re hardening browser-facing APIs, CORS should sit alongside proper security headers. If you need guidance beyond CORS, https://csp-guide.com is a good reference for CSP and related headers.


My recommendation

If you want the short version:

  • Best default: handle CORS at the gRPC-Web proxy
  • Best for simplicity: deploy same-origin and avoid CORS entirely
  • Use app-level CORS only when the app truly owns browser-facing transport

For most production systems, I’d choose:

  1. same-origin if feasible
  2. otherwise proxy-level CORS with explicit origins
  3. app-level CORS only for small or special-case deployments

That gives you fewer surprises, cleaner services, and much better odds that gRPC-Web behaves like a normal browser API instead of a weekly debugging ritual.

Official docs worth keeping open: