From 98b2f1a0bb8db4e2648cbc5d41815a5e60d308e4 Mon Sep 17 00:00:00 2001 From: Brad Anderson Date: Mon, 12 Oct 2026 01:05:40 -0700 Subject: [PATCH] docs(auth): document trusted header login --- .env.example | 6 ++++ docker-compose.dev.yml | 4 +++ docker-compose.yml | 4 +++ docs/09-deployment/environment-variables.md | 33 +++++++++++++++++++++ 4 files changed, 47 insertions(+) diff --git a/.env.example b/.env.example index 43d993d..98cdc62 100644 --- a/.env.example +++ b/.env.example @@ -109,6 +109,12 @@ ENABLE_CACHE_PREWARM=true # Off unless both are set. See docs/09-deployment/environment-variables.md. # STREAMING_API_URL=http://flashpoint-session-manager:8080 # STREAMING_API_TOKEN= +# Sign in users an authenticating reverse proxy (e.g. Authentik forward auth) +# names in a header. Off unless TRUSTED_HEADER_USERNAME and TRUSTED_PROXIES are +# both set. See docs/09-deployment/environment-variables.md. +# TRUSTED_HEADER_USERNAME=X-authentik-username +# TRUSTED_HEADER_EMAIL=X-authentik-email +# TRUSTED_PROXIES=192.0.2.10 # Serve the built frontend from the backend (on by default in production) # SERVE_FRONTEND=true diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index b6b6f3f..d02a586 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -67,6 +67,10 @@ services: # Streamed play for games that can't run in a browser (off unless both are set) - STREAMING_API_URL=${STREAMING_API_URL:-} - STREAMING_API_TOKEN=${STREAMING_API_TOKEN:-} + # Sign in users named by an authenticating reverse proxy (off unless both are set) + - TRUSTED_HEADER_USERNAME=${TRUSTED_HEADER_USERNAME:-} + - TRUSTED_HEADER_EMAIL=${TRUSTED_HEADER_EMAIL:-} + - TRUSTED_PROXIES=${TRUSTED_PROXIES:-} # OpenTelemetry - OTEL_ENABLED=${OTEL_ENABLED:-false} - OTEL_EXPORTER_OTLP_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT:-} diff --git a/docker-compose.yml b/docker-compose.yml index 3b91070..cf36ab8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -59,6 +59,10 @@ services: # Streamed play for games that can't run in a browser (off unless both are set) - STREAMING_API_URL=${STREAMING_API_URL:-} - STREAMING_API_TOKEN=${STREAMING_API_TOKEN:-} + # Sign in users named by an authenticating reverse proxy (off unless both are set) + - TRUSTED_HEADER_USERNAME=${TRUSTED_HEADER_USERNAME:-} + - TRUSTED_HEADER_EMAIL=${TRUSTED_HEADER_EMAIL:-} + - TRUSTED_PROXIES=${TRUSTED_PROXIES:-} # OpenTelemetry - OTEL_ENABLED=${OTEL_ENABLED:-false} - OTEL_EXPORTER_OTLP_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT:-} diff --git a/docs/09-deployment/environment-variables.md b/docs/09-deployment/environment-variables.md index e49d654..049dbdc 100644 --- a/docs/09-deployment/environment-variables.md +++ b/docs/09-deployment/environment-variables.md @@ -131,6 +131,39 @@ browser's IndexedDB. | `STREAMING_API_URL` | - | Session manager's internal API, e.g. `http://flashpoint-session-manager:8080` | | `STREAMING_API_TOKEN` | - | Token the session manager expects. Streaming is off unless both are set | +**Trusted Header Login:** + +When a reverse proxy such as Authentik (forward auth) authenticates users in +front of flashpoint-web, it can pass the signed-in username in a header so +users don't log in twice. The backend believes the header only on connections +from `TRUSTED_PROXIES`, checked against the connection's own address, not +`X-Forwarded-For`. The proxy must always set the header, overwriting anything a +client sends, and flashpoint-web must not be reachable from untrusted networks +except through it. + +Users are matched by username, so an existing account of that name is signed +in; otherwise an account is created (the first one as admin, as with +registration). New accounts get a random password. While signed in through the +proxy, users can set a password from Settings without knowing the current one, +then log in with it when reaching flashpoint-web without the proxy, such as on a +LAN. + +| Variable | Default | Description | +| ------------------------- | ------- | ------------------------------------------------------------------------ | +| `TRUSTED_HEADER_USERNAME` | - | Header holding the username, e.g. `X-authentik-username` | +| `TRUSTED_HEADER_EMAIL` | - | Optional header holding the email used for new accounts | +| `TRUSTED_PROXIES` | - | Comma-separated proxy addresses or CIDR ranges allowed to set the header | + +With nginx and Authentik's forward auth, pass the header from the auth +subrequest in each protected `location`: + +```nginx +auth_request_set $authentik_username $upstream_http_x_authentik_username; +auth_request_set $authentik_email $upstream_http_x_authentik_email; +proxy_set_header X-authentik-username $authentik_username; +proxy_set_header X-authentik-email $authentik_email; +``` + **OpenTelemetry:** | Variable | Default | Description |