Home › Answers › OAuth issuer behind a reverse proxy

MCP OAuth behind a reverse proxy: the endless 401 loop

Two symptoms, one root cause

Deriving the origin from the request produces two different failures depending on where the wrong URL surfaces first.

The second is the more confusing of the two, because everything works: the flow completes, the token is signed, the user sees a consent screen. The failure is a string comparison nobody thought to log.

Why frameworks get this wrong by default

Web frameworks build absolute URLs from the request they received: new URL(req.url).origin, request.base_url, url_for(_external=True). On a laptop, that origin is the public origin, so everything works. In production the process sits behind nginx, a load balancer, or a platform router, and it receives http://127.0.0.1:3000. The framework is not wrong — it is answering the question it was asked. The question was wrong.

What makes this a security question and not merely a configuration one: the canonical resource URI is the value your server compares the token's aud claim against. It is an identifier, not a convenience.

Do not reconstruct it from X-Forwarded-Host

The reflex is to read X-Forwarded-Host and X-Forwarded-Proto and rebuild the origin. Resist it. Those headers are set by whatever spoke to your process last. Unless every hop strips and re-sets them, an attacker who can reach your origin server directly controls the value — and therefore controls where discovery points and which audience you accept.

The public URL of your MCP endpoint is a constant of the deployment. It does not vary per request. It belongs in configuration:

CORTEX_CANONICAL_URI=https://mcp.example.com/mcp   # the resource identifier = expected audience
OAUTH_ISSUER=https://auth.example.com              # JWKS at /.well-known/jwks.json

Everything else derives from those two strings: the resource_metadata URL in the challenge, the resource field of the discovery document, and the audience the verifier enforces. One source of truth, no request involved.

The audience check is the point, not an obstacle

It is tempting, once you understand the loop, to "fix" it by skipping the aud check. That trades a visible bug for an invisible vulnerability.

A token is not valid; it is valid for a resource. If your MCP server accepts any well-signed token from your authorization server, then a token your user granted to an unrelated application — an internal dashboard, a partner integration, a low-trust script — is silently honoured by your high-trust MCP endpoint. RFC 8707 resource indicators exist so the client can request a token scoped to exactly one resource, and the audience check is where that scoping becomes real. Bind it to the canonical URI and reject everything else.

Three strings that must match exactly

OAuth compares these literally. A trailing slash breaks them. An http scheme breaks them. An internal hostname breaks them.

If the authorization server also runs behind a proxy — and it usually does — it has the same disease: its iss claim and its own discovery document must carry the public URL, not the internal one.

Verify it on the deployed URL

These checks cannot fail on localhost, which is exactly why they must run against production.

# 1. The metadata must describe the public resource
curl -s https://mcp.example.com/.well-known/oauth-protected-resource | jq .resource
# → "https://mcp.example.com/mcp"   (never localhost, never an internal host)

# 2. The challenge must point at the public metadata URL
curl -si -X POST https://mcp.example.com/mcp -d '{}' | grep -i www-authenticate

# 3. The token's audience must equal that same string, character for character
echo "$ACCESS_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq '.aud, .iss'

Make check 1 a smoke test in your deployment pipeline. It is one HTTP call, it catches the whole family, and it is the difference between finding this in CI and finding it in a support thread.

What Cortex Gateway does

Cortex Gateway refuses to guess. The canonical URI is configuration (CORTEX_CANONICAL_URI), the expected audience defaults to it (overridable with OAUTH_AUDIENCE for the RFC 8707 audience-per-resource pattern), and the WWW-Authenticate challenge is built from it rather than from the inbound request. The issuer is required at boot — the process refuses to start without OAUTH_ISSUER — because a resource server that does not know its own authorization server has nothing useful to do.

The broader rule, worth carrying to any protocol: a value used in a security comparison must never be derived from the message being checked.

Full wiring, including scopes and revocation: securing your MCP server with OAuth 2.1.

FAQ