Skip to content

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

  1. First request has no session → redirect to <team>.cloudflareaccess.com.
  2. 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).
  3. PIN entered → Access sets a session cookie (CF_Authorization) that is a JWT signed by Cloudflare, carrying email, 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. (Not Authorization: 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.com exactly.
  • 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:

  1. See your identity. Log in (OTP) and open <app>.<tenant-domain>/whoami. request.headers shows your X-User-Email and X-User-Id. With a service token (curl) instead, you get X-Service-Id. Both show X-Tenant.
  2. 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.
  3. Try the anonymous door. No credentials → you get a 302 and never reach /whoami at 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).