Identity & traffic flow: from the edge to your headers
Audience: engineers building a service behind the platform gateway. The one thing to take away: by the time a request reaches your container, who-is-calling is already a set of verified, plain HTTP headers you can read directly — no login code, no token parsing, no auth library.
This document traces a single request from the public internet to your backend, and explains exactly how the gateway makes those headers trustworthy. It stops at your container's front door — what your service does with the identity is yours.
Current trial
The live example is ScreamingFace's fusion.testsfapp.net. In prose we
use generic placeholders — <app>.<tenant-domain>, <team>.cloudflareaccess.com,
<AUD> — so the shapes apply to any tenant. Rate limiting is planned,
not yet deployed (§7 notes where it will appear).
1. The whole path in one picture
sequenceDiagram
autonumber
actor H as Human (browser)
actor S as Automation (script)
participant CF as Cloudflare Access
participant T as cloudflared (tunnel)
participant E as Envoy (gateway)
participant B as Your service
H->>CF: request → <app>.<tenant-domain>
CF-->>H: redirect → login (email one-time PIN)
H->>CF: email + PIN
CF-->>H: session cookie = signed JWT (email, sub)
S->>CF: request + service-token id/secret
Note over CF: token pair valid for this app?<br/>JWT identity = common_name
Note over CF: both paths → ONE header:<br/>Cf-Access-Jwt-Assertion (signed JWT)
CF->>T: forward down the tunnel + JWT header
T->>E: hand to the gateway (no public IP)
Note over E: re-verify: signature vs JWKS,<br/>issuer, audience → fail = 401/403
Note over E: verified claims → headers<br/>(client's own values discarded)
E->>B: request + X-User-Email / X-User-Id / X-Service-Id / X-Tenant
B-->>H: response
B-->>S: response
Three independent planes do the work: the Cloudflare edge authenticates, the gateway (Envoy) re-verifies and translates, and NetworkPolicy guarantees there's no other way in. Design rationale lives in ADR-0005; this doc is the as-built mechanics.
2. Who's trusted for what
| Component | Trusted to | NOT trusted for |
|---|---|---|
| Cloudflare Access | Authenticate the caller; sign a JWT asserting identity | Being the only check — the gateway re-verifies |
| cloudflared tunnel | Carry requests inbound; no public origin exists | Adding/altering identity — it forwards only |
| Envoy (gateway) | Cryptographically verify the JWT; stamp identity headers | Authorizing actions — that's your service's job |
| NetworkPolicy | Guarantee the gateway is the only path to your pod | — (this is what makes the headers believable) |
| Your service | Read the headers, decide what the identity may do | Re-checking the JWT — already done, and you don't get the signing keys |
The load-bearing idea: we do not trust network position, we trust cryptography and topology. Envoy re-verifies the signature even though the request came from Cloudflare's own tunnel; and you may trust the headers because NetworkPolicy proves nothing can reach you except through the gateway that stamped them.
3. Entry — and why there's no back door
<app>.<tenant-domain> resolves to Cloudflare, not to us. The cluster has no
public IP: the gateway's Envoy fleet is a ClusterIP service, reachable only
from inside. The single way in is the tunnel (§5). So you cannot "find the
origin" and skip Access — there is no origin to find. This is the tier's
structural guarantee, not a firewall rule that could be misconfigured.
4. Authentication at the edge — two kinds of caller
Cloudflare Access decides who before anything reaches the cluster. Two caller types exist, and they produce slightly different identity.
4a. A human — email one-time PIN
- First request has no session → redirect to
<team>.cloudflareaccess.com. - The person enters their email. Only if it matches an allowed policy does Cloudflare email a one-time PIN (a non-match sends nothing — this is deliberate, so the login page can't be used to probe which emails exist).
- PIN entered → Access sets a session cookie (
CF_Authorization) that is a JWT signed by Cloudflare, carryingemail,sub(a stable per-user id),aud,iss,exp. Later requests carry it automatically until it expires.
4b. Automation — a service token
A script sends CF-Access-Client-Id / CF-Access-Client-Secret headers.
Access validates the pair for this app and issues a JWT whose identity claim is
common_name (the token's name). It has no email, and an empty sub —
which is why a service token yields only X-Service-Id downstream, never the
user headers.
4c. The audience (aud) is the tenant boundary
Every Access application has one Application Audience tag. The JWT's aud is
that tag. A token minted for app A is cryptographically useless at app B — the
gateway checks aud and rejects a mismatch (§6). This is how one shared
gateway safely serves many tenants.
5. Transport — the tunnel
Two cloudflared replicas run inside the cluster (platform-owned namespace)
holding outbound-only connections to Cloudflare — nothing dials in. When
Cloudflare forwards a request it copies the session/token JWT into a request
header, Cf-Access-Jwt-Assertion. This is the normalization point: whether the
caller was a cookie-bearing human or a header-bearing script, the gateway sees
one consistent artifact — that header.
6. Enforcement — what the gateway actually does
The gateway attaches a policy (an Envoy SecurityPolicy) to your route. On
every request it runs Envoy's JWT filter with these rules, drawn from the live
config:
- Where to find the token:
Cf-Access-Jwt-Assertion. (NotAuthorization: Bearer— a common wrong assumption; Cloudflare doesn't put it there.) - Signature: verified against Cloudflare's public keys, fetched from
<team>.cloudflareaccess.com/cdn-cgi/access/certs(a JWKS endpoint) and cached. If the keys can't be fetched, requests fail closed. - Issuer: must equal
<team>.cloudflareaccess.comexactly. - Audience: must equal this tenant's
<AUD>exactly.
Any failure — missing token, bad signature, expired, wrong issuer, wrong audience — and Envoy returns 401/403 and your service never sees the request.
Only after the token verifies does Envoy translate claims into headers.
7. The header contract — what your service receives
This is the section to bookmark.
The headers
| Header | Set from | Present for |
|---|---|---|
X-User-Email |
JWT email claim |
humans (OTP) |
X-User-Id |
JWT sub claim |
humans (OTP) |
X-Service-Id |
JWT common_name claim |
service tokens |
X-Tenant |
platform (route) — constant <tenant> |
every request |
Presence tells you the caller type: X-User-Email set → a verified human;
X-Service-Id set → a machine identity. (A service token's sub is empty,
so it produces no X-User-Id — don't rely on X-User-Id to detect "a
caller"; use the pair.)
How they're protected against forgery (verified, not asserted)
For the identity headers, Envoy removes any value the client sent and then sets its own from the verified claim. We tested this against the live edge by sending forged headers with a valid credential and inspecting what the backend received:
| Client sent | Backend received | Why |
|---|---|---|
X-User-Email: ceo@evil.example (service token) |
(absent) | managed header cleared; no email claim to set → stays empty |
X-User-Id: 00000000-forged |
(absent) | same — cleared, empty sub sets nothing |
X-Service-Id: someone-else |
the real token name | cleared, then set from common_name |
X-Tenant: acme-corp |
<tenant> |
route overwrites it (see below) |
The key subtlety: Envoy clears all the managed identity headers before re-injecting, so even when a claim is absent (a service token has no email), a forged value for that header does not survive. Forgery loses in both the overwrite case and the absent-claim case.
X-Tenant is handled differently — it comes from no JWT claim, so the platform
stamps it at the route with an overwrite (set) that discards any client
value. (An earlier probe found that a header not managed this way passes
through untouched; that's why X-Tenant is explicitly set, not merely
added.)
What you may assume, and what you may not
Assume: every header above was cryptographically verified no earlier than this request; and no request can reach you without passing through the gateway that stamped them (NetworkPolicy — §2).
Do not assume: that identity means authorization. X-User-Email tells
you who, truthfully — deciding whether that person may do the thing is your
service's job. Also don't assume both caller types set the same headers; handle
the human set and the service set.
Identifying your caller (pseudocode)
email = header["X-User-Email"]
service = header["X-Service-Id"]
if email: caller is a person, identified by email
elif service: caller is automation, identified by service token name
else: should be impossible behind the gateway — reject
tenant = header["X-Tenant"] # always your tenant; safe to trust
Planned: rate limiting
Per-identity rate limits (keyed on these same verified X-User-Id /
X-Service-Id headers) are designed but not yet deployed. When they land,
an over-budget caller will receive 429 here, and this section will gain
the response details.
8. When it fails — which hop, which signature
| You see | Produced by | Meaning |
|---|---|---|
| 302 → login page | Cloudflare edge | no session — authenticate first |
| Access block page (Ray ID, App AUD shown) | Cloudflare edge | authenticated, but no policy allows you |
| plain 401 | gateway (Envoy) | token missing / expired / malformed / bad signature |
| plain 403 | gateway (Envoy) | wrong audience — token was for another app |
| 502 | your backend | you were reached; the error is past the gateway |
| timeout | network policy / backend | egress blocked or backend down |
Two useful specifics learned in practice: an unauthenticated request returns
302 (redirect) once an identity policy exists — it was 403 when the app had
only a service-token policy. And a fake Cf-Access-Jwt-Assertion sent from
outside gets you nowhere on an Access-gated hostname — Cloudflare only
forwards requests it authenticated there, so you cannot smuggle the header
past the edge. On the anonymous hostnames in the platform posture table,
Cloudflare forwards unauthenticated
traffic by design; the header is simply inert on those routes — no
SecurityPolicy consumes it, and identity headers are stripped tier-wide
regardless.
9. Seeing it for yourself
The tenant route exposes /whoami — it reflects back the exact headers your
backend received. Use it to run the experiment yourself:
- See your identity. Log in (OTP) and open
<app>.<tenant-domain>/whoami.request.headersshows yourX-User-EmailandX-User-Id. With a service token (curl) instead, you getX-Service-Id. Both showX-Tenant. - Try to lie. Send
-H "X-User-Email: ceo@evil.example"with a valid service token → the backend sees no such value (§7). The gateway owns the header; you can't set it. - Try the anonymous door. No credentials → you get a 302 and never reach
/whoamiat all.
For operators, deeper inspection points: Cloudflare's Access logs (edge
decisions), the cloudflared pod logs (tunnel), and the gateway's compiled
Envoy config (the JWT filter state).
10. When identity changes
Today Cloudflare Access is the identity provider. The architecture treats it as
one replaceable plane: when the platform's own IdP (Keycloak) takes over, §4
(how the JWT is obtained) changes, but §5–§7 — the tunnel, the verification,
and the header contract your service reads — stay the same. That stability is
the point of the design: your service reads X-User-Email and doesn't care
what minted the token.
Sources: ADR-0005 (+§4
amendment); the live sf-fusion SecurityPolicy and HTTPRoute; forged-header
probe transcripts (2026-07-22).