From 8f473023e47ea76801ececd78579557e6607a80c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 13:50:38 +0100 Subject: [PATCH] docs: refresh web surface auth mirrors --- docs/gateway/remote.md | 4 +++- docs/web/dashboard.md | 13 ++++++++++--- docs/web/webchat.md | 2 +- 3 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/gateway/remote.md b/docs/gateway/remote.md index 89f3ff59b2b..68061b7bed3 100644 --- a/docs/gateway/remote.md +++ b/docs/gateway/remote.md @@ -139,7 +139,7 @@ Short version: **keep the Gateway loopback-only** unless you’re sure you need - **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure). - Plaintext `ws://` is loopback-only by default. For trusted private networks, set `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` on the client process as break-glass. -- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use auth tokens/passwords. +- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use gateway auth: token, password, or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`. - `gateway.remote.token` / `.password` are client credential sources. They do **not** configure server auth by themselves. - Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset. - If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking). @@ -148,6 +148,8 @@ Short version: **keep the Gateway loopback-only** unless you’re sure you need headers when `gateway.auth.allowTailscale: true`; HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Set it to `false` if you want tokens/passwords everywhere. +- **Trusted-proxy** auth is for non-loopback identity-aware proxy setups only. + Same-host loopback reverse proxies do not satisfy `gateway.auth.mode: "trusted-proxy"`. - Treat browser control like operator access: tailnet-only + deliberate node pairing. Deep dive: [Security](/gateway/security). diff --git a/docs/web/dashboard.md b/docs/web/dashboard.md index 682c155b841..69ffecdea7c 100644 --- a/docs/web/dashboard.md +++ b/docs/web/dashboard.md @@ -20,8 +20,15 @@ Key references: - [Tailscale](/gateway/tailscale) for Serve/Funnel automation. - [Web surfaces](/web) for bind modes and security notes. -Authentication is enforced at the WebSocket handshake via `connect.params.auth` -(token or password). See `gateway.auth` in [Gateway configuration](/gateway/configuration). +Authentication is enforced at the WebSocket handshake via the configured gateway +auth path: + +- `connect.params.auth.token` +- `connect.params.auth.password` +- Tailscale Serve identity headers when `gateway.auth.allowTailscale: true` +- trusted-proxy identity headers when `gateway.auth.mode: "trusted-proxy"` + +See `gateway.auth` in [Gateway configuration](/gateway/configuration). Security note: the Control UI is an **admin surface** (chat, config, exec approvals). Do not expose it publicly. The UI keeps dashboard URL tokens in sessionStorage @@ -40,7 +47,7 @@ Prefer localhost, Tailscale Serve, or an SSH tunnel. - **Token source**: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` can pass it via URL fragment for one-time bootstrap, and the Control UI keeps it in sessionStorage for the current browser tab session and selected gateway URL instead of localStorage. - If `gateway.auth.token` is SecretRef-managed, `openclaw dashboard` prints/copies/opens a non-tokenized URL by design. This avoids exposing externally managed tokens in shell logs, clipboard history, or browser-launch arguments. - If `gateway.auth.token` is configured as a SecretRef and is unresolved in your current shell, `openclaw dashboard` still prints a non-tokenized URL plus actionable auth setup guidance. -- **Not localhost**: use Tailscale Serve (tokenless for Control UI/WebSocket if `gateway.auth.allowTailscale: true`, assumes trusted gateway host; HTTP APIs still need token/password), tailnet bind with a token, or an SSH tunnel. See [Web surfaces](/web). +- **Not localhost**: use Tailscale Serve (tokenless for Control UI/WebSocket if `gateway.auth.allowTailscale: true`, assumes trusted gateway host; HTTP APIs still need token/password), a non-loopback bind with token/password auth, an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. See [Web surfaces](/web). diff --git a/docs/web/webchat.md b/docs/web/webchat.md index b88145b4b74..313d5f77ec3 100644 --- a/docs/web/webchat.md +++ b/docs/web/webchat.md @@ -60,6 +60,6 @@ Related global options: - `gateway.port`, `gateway.bind`: WebSocket host/port. - `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`: WebSocket auth (token/password). -- `gateway.auth.mode: "trusted-proxy"`: reverse-proxy auth for browser clients (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "trusted-proxy"`: reverse-proxy auth for browser clients behind an identity-aware **non-loopback** proxy source (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). - `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: remote gateway target. - `session.*`: session storage and main key defaults.