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+protox-grpc-web: 1x-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:
- Handle CORS at the gRPC-Web proxy
- Handle CORS in the application server
- 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:
POSTOPTIONScontent-typex-grpc-webgrpc-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.comhttps://api.example.net
Use this:
https://app.example.comhttps://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-statusgrpc-messagegrpc-status-details-binauthorizationin allowed request headersOPTIONSin allowed methodsVary: Originwhen 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:
- same-origin if feasible
- otherwise proxy-level CORS with explicit origins
- 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: