chmonitorProxy & SSO auth setup
Overview of putting chmonitor behind a proxy that handles login — Cloudflare Access, nginx + oauth2-proxy, or Traefik ForwardAuth — using the proxy or trusted auth provider.
"Proxy auth" means chmonitor doesn't do the login itself — a reverse proxy in front of it authenticates the user and forwards their identity. chmonitor never sees a password or an OIDC handshake; it only ever sees either a cryptographically signed header (Cloudflare Access) or a plain identity header plus a shared secret (everything else). This is the model for self-hosted deployments that already have SSO infrastructure (Zero Trust, an internal IdP, Kubernetes ingress auth) and don't want chmonitor managing its own user database.
The security model
The proxy must be the only path to chmonitor
Every pattern below works by trusting a header the proxy sets. If chmonitor is reachable by any route that bypasses the proxy — a public LoadBalancer, a NodePort, a forwarded router port, a debug tunnel left open — that path can forge the same headers and impersonate any user. chmonitor's trusted provider fails closed (denies every request) unless you explicitly configure a trust gate (a shared secret, or an opt-in network-isolation flag); the proxy provider's Cloudflare Access mechanism is self-proving via JWT signature, but its optional shared-secret mechanism has the same bypass risk. Treat "chmonitor's port is not independently reachable" as a hard requirement, not a nice-to-have.
chmonitor has two auth providers for this:
proxy— verifies a signedCf-Access-Jwt-AssertionJWT from Cloudflare Access (no secret needed), and/or a bare identity header gated by a shared secret. Extracts only a subject.trusted— extracts a full principal (subject, name, email, avatar, groups) from multiple forwarded headers, gated by a shared secret or an explicit insecure/network-isolated opt-in. Supports group-based access gating (CHM_TRUSTED_ALLOWED_GROUPS).
Pick the guide that matches your infrastructure — each is a complete, standalone walkthrough:
Cloudflare Access + Tunnel
Zero Trust, signed JWT, no shared secret needed. Best if you're already on (or want) Cloudflare.
nginx + oauth2-proxy
Self-hosted OIDC login in front of nginx, using auth_request. Full identity profile via the trusted provider.
Traefik ForwardAuth + OIDC
Traefik's forwardAuth middleware delegating to oauth2-proxy (or Authelia/Authentik) for OIDC login.
Quick comparison
| Setup | chmonitor provider | Trust mechanism | Full profile (name/email/avatar/groups)? |
|---|---|---|---|
| Cloudflare Access + Tunnel | proxy | Signed Cf-Access-Jwt-Assertion JWT — no shared secret needed | No — subject only (email claim) |
| nginx + oauth2-proxy | trusted | Shared secret header (X-Chm-Proxy-Secret) | Yes |
| Traefik ForwardAuth + OIDC | trusted | Shared secret header, or network isolation (CHM_TRUSTED_ALLOW_INSECURE) | Yes |
Troubleshooting
Every page returns 401
Both providers reject requests they can't verify — there is no open fallback. Confirm the trust gate: for proxy, CHM_CF_ACCESS_TEAM_DOMAIN and CHM_CF_ACCESS_AUD (Cloudflare Access) or CHM_PROXY_AUTH_SECRET (bare trusted-header); for trusted, CHM_TRUSTED_AUTH_SECRET or CHM_TRUSTED_ALLOW_INSECURE. Each per-platform guide above has a dedicated troubleshooting section covering wrong header names, header-spoofing risk, and websocket/streaming passthrough for the AI agent chat. See also Troubleshooting → Auth failures.
Related
Authentication overview
Compare all chmonitor auth providers side by side.
Trusted forwarded headers reference
Full env var reference for the trusted provider (full profile).
Trusted header (proxy provider) reference
Bare identity subject via shared secret, no full profile.
Cloudflare Access reference
Reference for the proxy JWT provider.
API keys
Issue and use chmonitor API tokens.
Store backends
Per-backend setup for conversation history — AgentState, Cloudflare D1, Postgres, Memory, and Browser defaults.
Slack app
Install the native chmonitor Slack app — OAuth setup, the /chmonitor slash command (status, read-only query, alerts), a Home tab, and Acknowledge buttons on alert messages.