Feature request: trusted proxy (header) authentication for self-hosted instances #536

Summary

Add an opt-in "trusted proxy" login for self-hosted instances. When OpenPanel sits behind an authenticating reverse proxy (Tailscale, oauth2-proxy, Authelia, Authentik, Cloudflare Access, …), the proxy passes the user's identity in request headers, and OpenPanel signs that user in, creating or updating their account automatically.

This is the same pattern as Grafana's auth.proxy. We run OpenPanel self-hosted behind a VPN that already sends these headers, and we'd like to implement this ourselves if you're open to it.

Proposed configuration

All off by default. Only AUTH_PROXY_ENABLED, the email header and the trusted sources are required; the other headers are optional, so any subset works.

AUTH_PROXY_ENABLED=true
AUTH_PROXY_HEADER_EMAIL=X-Forwarded-Email       # required, identifies the user
AUTH_PROXY_HEADER_NAME=X-Forwarded-Name         # optional, full name, split into first/last
AUTH_PROXY_HEADER_FIRST_NAME=                   # optional, instead of NAME
AUTH_PROXY_HEADER_LAST_NAME=                    # optional
AUTH_PROXY_HEADER_AVATAR=X-Forwarded-Picture    # optional, image URL
AUTH_PROXY_HEADER_ROLE=X-Forwarded-Role         # optional, see "Roles" below
AUTH_PROXY_TRUSTED_IPS=10.0.0.0/8,100.64.0.0/10 # required, headers from anywhere else are ignored
AUTH_PROXY_AUTO_SIGN_UP=true                    # create users that don't exist yet

Behaviour

• Where: in the dashboard API's existing onRequest session hook in apps/api/src/app.ts, next to the DEMO_USER_ID path. If there's no valid session cookie and the request comes from a trusted source with the email header set, the API looks up the user by email, creates them if AUTH_PROXY_AUTO_SIGN_UP allows, updates name and avatar if they changed, and issues a normal session cookie. Everything after that uses the existing session flow.
• Existing users: a user who signed up with Google, GitHub or a password is matched by email and signed in, instead of getting the "sign in using your original authentication method" error.
• SSR: the dashboard's server-side tRPC client currently forwards only the Cookie header to API_URL_SSR. It would also forward the configured identity headers, so server-rendered pages see the logged-in user.
• Logout: while proxy auth is active the logout button would just sign the user straight back in, so it would be hidden, or point to an optional AUTH_PROXY_LOGOUT_URL.

Roles

Member.role is per organization, so a role header needs a target organization. Proposal:

AUTH_PROXY_ORGANIZATION_ID=<org id>                    # org that proxy users join automatically
AUTH_PROXY_ROLE_MAP=admin:org:admin,*:org:member       # header value -> member role; * = default

The header would set the role on every login, so roles stay managed by the identity provider. If that's too opinionated, roles could be left out of the first version.

Security

• Disabled unless explicitly enabled. Headers are ignored unless the request's source IP is in AUTH_PROXY_TRUSTED_IPS, because a deployment with a public ingest API would otherwise let anyone impersonate any user by setting a header.
• Optionally, AUTH_PROXY_SECRET_HEADER / AUTH_PROXY_SECRET: a shared secret the proxy must send, for setups where IP ranges aren't reliable.
• Only the dashboard API routes accept proxy auth, never the public ingest/track endpoints.

Scope

• Profile pictures need a new avatar column on User (a Prisma migration) plus showing it in the dashboard. That could be a follow-up PR if you'd prefer to keep the first one small.
• Tests for the session hook and user upsert, and a docs page under self-hosting.

Questions before we start

1. Is this something you'd accept upstream?
2. Any preferences on config names, or should roles be left out of the first version?
3. Related: feature request: OIDC support #368 asks for OIDC. This is complementary (no IdP integration in OpenPanel itself), but let us know if you'd rather see effort go there instead.