A tiny (~100 lines, one real dependency) ForwardAuth / auth_request service that validates
Cloudflare Access JWTs at your origin.
Why. Cloudflare Access only protects the Cloudflare edge. If your origin is reachable directly
(by IP with a forged Host, from inside your network, through a misrouted tunnel) nothing stops a request
from skipping the login page. Cloudflare's recommendation is to
validate the Cf-Access-Jwt-Assertion JWT on every request.
This service does that for any reverse proxy with an external-auth hook, and hands the authenticated
identity to your app as headers so it can log the user in automatically.
client ──Cloudflare Access──▶ proxy ──(ForwardAuth)──▶ cloudflare-access-forwardauth
│ │ 200 + X-Remote-User
└────── upstream app ◀─────────┘ (or 401)
| Path | Result |
|---|---|
/healthz |
200 ok (liveness/readiness) |
anything else (/verify by convention) |
200 with X-Remote-User and X-Remote-User-Email when the JWT is valid; 401 when missing or invalid; 503 when the JWKS cannot be fetched (fails closed) |
The JWT is read from the Cf-Access-Jwt-Assertion header or the CF_Authorization cookie, exactly as
Cloudflare sends them. Checks: RS256 signature against your team's JWKS (cached 1h, refreshed on unknown kid),
issuer https://<team>.cloudflareaccess.com, audience = your application's AUD tag, exp/iat
(30 s leeway) and an email claim.
| Variable | Required | Default | Meaning |
|---|---|---|---|
CF_ACCESS_TEAM_DOMAIN |
yes | e.g. example.cloudflareaccess.com |
|
CF_ACCESS_AUD |
yes | Application Audience (AUD) tag of the Access application (Zero Trust → Access → Applications → Overview) | |
CF_ACCESS_CERTS_URL |
no | https://$TEAM/cdn-cgi/access/certs |
JWKS URL (override for tests) |
USER_HEADER |
no | X-Remote-User |
response header carrying the identity |
EMAIL_HEADER |
no | X-Remote-User-Email |
response header carrying the e-mail |
SERVICE_TOKENS |
no | reject |
what to do with Access service tokens (JWT without email): reject (401), pass (200 with empty identity headers: the app does its own auth) or identity (200 with X-Remote-User = common_name). See below |
REQUIRE_EMAIL |
no | true |
deprecated alias: false = SERVICE_TOKENS=identity |
CLOCK_SKEW_SECONDS |
no | 30 |
leeway for exp/iat/nbf |
LOG_LEVEL |
no | INFO |
DEBUG logs each accepted identity |
Scripts and integrations authenticate to Access with a service token
(CF-Access-Client-Id / CF-Access-Client-Secret headers, plus a Service Auth policy on the application).
Cloudflare then issues a JWT with common_name = the token name and no email. By default such requests
are rejected, so only humans get in. Two ways to allow them:
SERVICE_TOKENS=pass: the request is let through with emptyX-Remote-User/X-Remote-User-Email. The upstream app must authenticate it itself (API token, basic auth...), exactly as if nobody were logged in. The empty headers are sent on purpose: a proxy that only replaces headers still wipes whatever the client forged. This is the right mode for apps with their own API tokens (NetBox, Grafana service accounts...): the service token proves the client is allowed to reach the origin, the API token says who it is.SERVICE_TOKENS=identity: the token is logged in as a user namedcommon_name(e.g.abcdef0123.access). Use it only if the app should treat the token itself as a user.
Both modes keep every other check (signature, issuer, audience, expiry).
docker run --rm -p 8080:8080 \
-e CF_ACCESS_TEAM_DOMAIN=example.cloudflareaccess.com \
-e CF_ACCESS_AUD=0123…abcd \
ghcr.io/estabilis/cloudflare-access-forwardauth:latestImage: ghcr.io/estabilis/cloudflare-access-forwardauth (linux/amd64 + arm64), tags latest, X.Y.Z (from git tag vX.Y.Z), X.Y, main,
sha-<commit>. Runs as uid 10001, works with a read-only root filesystem (mount a writable /tmp).
- Traefik on Kubernetes (ForwardAuth
Middleware+ Ingress annotation):examples/traefik-kubernetes.yaml - nginx (
auth_request):examples/nginx.conf - Caddy:
forward_auth cloudflare-access-forwardauth:8080 { uri /verify; copy_headers X-Remote-User X-Remote-User-Email }
Make sure the proxy replaces X-Remote-User/X-Remote-User-Email on the upstream request with the values from
this service (Traefik's authResponseHeaders and nginx's proxy_set_header do). Never let the client's own
copy of those headers through, and make sure the upstream is reachable only through the proxy
(NetworkPolicy, firewall, localhost binding).
- NetBox:
REMOTE_AUTH_ENABLED=True,REMOTE_AUTH_HEADER='HTTP_X_REMOTE_USER',REMOTE_AUTH_USER_EMAIL='HTTP_X_REMOTE_USER_EMAIL',REMOTE_AUTH_AUTO_CREATE_USER=True(REMOTE_AUTH_GROUP_SYNC_ENABLED=Trueif you useREMOTE_AUTH_SUPERUSERS). - Grafana:
[auth.proxy] enabled = true, header_name = X-Remote-User, header_property = username. - Django:
RemoteUserMiddleware+RemoteUserBackendwithheader = 'HTTP_X_REMOTE_USER'.
Logging out of such an app should also end the Access session: redirect to
https://<your host>/cdn-cgi/access/logout.
pip install --require-hashes -r requirements.txt -r requirements-dev.txt
pytest -qTests sign JWTs with a local RSA key served from an in-process JWKS endpoint and cover: valid token via header and
via cookie, forged client header, expired, wrong audience, wrong issuer, wrong key, unknown kid,
tampered signature, garbage, and service tokens in the three SERVICE_TOKENS modes. Dependencies are pinned with hashes; regenerate with
docker run --rm -v "$PWD":/w -w /w python:3.13-slim sh -c 'pip install -q pip-tools && pip-compile --generate-hashes --strip-extras requirements.in && pip-compile --generate-hashes --strip-extras -o requirements-dev.txt requirements-dev.in'MIT.