Reverse proxy: trusted header

Use this when you front chmonitor with a proxy that does its own authentication — nginx with an SSO module, a Kubernetes ingress with auth-url, or similar. The proxy sets a header with the authenticated user's identity; chmonitor trusts it only when a shared secret is also present.

• The upstream proxy authenticates the user and sets a header with their identity (e.g. X-Forwarded-User: alice@example.com).
• The proxy also sets a shared-secret header on every request.
• chmonitor checks the secret in constant time. If it matches, the identity header is trusted and the user is authenticated.
• Without CHM_PROXY_AUTH_SECRET set, this mechanism is disabled. Any request missing the correct secret is treated as unauthenticated regardless of the identity header.

This prevents header forgery: a direct client hitting the Worker URL cannot fake authentication because they don't know the secret.

Prerequisites

A reverse proxy (nginx, Kubernetes ingress, or similar) that authenticates users upstream and can inject request headers before forwarding to chmonitor.

Setup

CHM_AUTH_PROVIDER=proxy
CHM_PROXY_AUTH_HEADER=X-Forwarded-User          # identity header (default)
CHM_PROXY_SHARED_SECRET_HEADER=X-Chm-Proxy-Secret  # secret header (default)

Set the secret out-of-band — never as a plaintext env file:

wrangler secret put CHM_PROXY_AUTH_SECRET

location / {
  # Your auth_request / SSO module sets $authenticated_user
  auth_request /auth;
  auth_request_set $authenticated_user $upstream_http_x_auth_user;

  proxy_set_header X-Forwarded-User    $authenticated_user;
  proxy_set_header X-Chm-Proxy-Secret  "the-same-long-random-secret";
  proxy_pass http://chmonitor_upstream;
}

nginx.ingress.kubernetes.io/configuration-snippet: |
  proxy_set_header X-Forwarded-User $http_x_auth_request_user;
  proxy_set_header X-Chm-Proxy-Secret "the-same-long-random-secret";

Verify

Send an authenticated request through the proxy and confirm data returns. A direct request to the Worker URL — bypassing the proxy, and therefore missing the correct secret header — must be treated as unauthenticated even if it carries an identity header.

Troubleshooting

Related