docs(auth): document trusted header login

.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
 

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:-}

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:-}

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                              |