diff --git a/docs/deployment/authentication.md b/docs/deployment/authentication.md new file mode 100644 index 00000000000..7e1e55a529a --- /dev/null +++ b/docs/deployment/authentication.md @@ -0,0 +1,93 @@ +--- +title: + page: "Authentication Configuration" + nav: "Authentication" +description: + main: "Configure device authentication for the OpenClaw gateway, including the NEMOCLAW_DISABLE_DEVICE_AUTH build argument." + agent: "Documents the NEMOCLAW_DISABLE_DEVICE_AUTH build argument and device authentication configuration. Use when configuring gateway authentication, disabling device auth, or reviewing auth security implications." +keywords: ["nemoclaw authentication", "device auth disable build arg"] +topics: ["generative_ai", "ai_agents"] +tags: ["nemoclaw", "security", "authentication", "deployment"] +content: + type: reference + difficulty: intermediate + audience: ["developer", "engineer", "security_engineer"] +status: published +--- + + + +# Authentication Configuration + +This page documents the device authentication settings for the OpenClaw gateway, including the `NEMOCLAW_DISABLE_DEVICE_AUTH` build argument and related security controls. + +## `NEMOCLAW_DISABLE_DEVICE_AUTH` + +**Location**: Dockerfile build argument (line 59), propagated to `openclaw.json` as `dangerouslyDisableDeviceAuth`. +**Default**: `0` (device auth enabled — secure by default). + +### What It Does + +When set to `1`, the OpenClaw gateway skips the OAuth 2.0 Device Authorization Grant flow. +Users are not prompted to authenticate via browser-based device code approval before accessing the gateway API. + +The setting is baked into `openclaw.json` at image build time and verified by a SHA256 integrity hash at container startup. +It cannot be changed at runtime. + +### When to Disable (Set to `1`) + +Disable device auth only when: + +- The sandbox runs locally with no network exposure (single-user, localhost only). +- The environment is headless with no browser available to complete the device auth flow. +- The NemoClaw Docker sandbox is the only consumer (the default `nemoclaw onboard` flow handles this automatically). + +```console +$ docker build --build-arg NEMOCLAW_DISABLE_DEVICE_AUTH=1 -t nemoclaw-sandbox . +``` + +### When to Keep Enabled (Default `0`) + +Keep device auth enabled when: + +- The gateway is network-accessible beyond localhost. +- Multiple users or external clients connect to the same instance. +- The sandbox is exposed via a tunnel (for example, cloudflared) or LAN binding. +- You need per-device audit trails. + +### Security Implications + +| Setting | Risk | Use Case | +|---------|------|----------| +| `0` (enabled, default) | Requires browser-based approval; gateway generates per-device tokens | Multi-user, external access, production | +| `1` (disabled) | Anyone with network access to the gateway can use it without authentication | Single-user local/Docker, headless development | + +:::{warning} +Disabling device auth on a network-accessible gateway creates an unauthenticated endpoint. +Combined with a cloudflared tunnel or LAN-bind changes in remote deployments, this results in a publicly reachable, unauthenticated dashboard. +::: + +### Related Settings + +`allowInsecureAuth` +: Derived automatically from the `CHAT_UI_URL` scheme at build time. + When the URL uses `http://` (local development), insecure auth is allowed. + When it uses `https://`, insecure auth is blocked. + See [Security Best Practices](../security/best-practices.md) for details. + +`auth.token` +: A gateway bearer token generated at build time using `secrets.token_hex(32)`. + Unique per image build. + +`trustedProxies` +: IPs allowed to set `X-Forwarded-For` headers. + Defaults to `127.0.0.1` and `::1`. + +## Next Steps + +- [Security Best Practices](../security/best-practices.md) for the full gateway authentication controls reference. +- [Sandbox Hardening](sandbox-hardening.md) for container-level security measures. +- [Deploy to a Remote GPU Instance](deploy-to-remote-gpu.md) for remote deployment considerations. diff --git a/docs/index.md b/docs/index.md index 57d08c4bbd5..725d355a4b5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -271,6 +271,7 @@ Credential Storage Deploy to a Remote GPU Instance Set Up Telegram Sandbox Hardening +Authentication ``` ```{toctree} diff --git a/docs/network-policy/customize-network-policy.md b/docs/network-policy/customize-network-policy.md index 6da052d3c35..809f0712651 100644 --- a/docs/network-policy/customize-network-policy.md +++ b/docs/network-policy/customize-network-policy.md @@ -51,6 +51,52 @@ Each entry in the `network` section defines an endpoint group with the following `rules` : HTTP methods and paths that are permitted. +### Access Modes + +Each endpoint supports two access modes that control how OpenShell inspects traffic: + +:::{list-table} +:header-rows: 1 +:widths: 15 15 70 + +* - Field + - Value + - Behavior + +* - `protocol` + - `rest` + - OpenShell terminates TLS and inspects HTTP method/path against `rules`. + Only matching requests are forwarded. + +* - `access` + - `full` + - OpenShell creates a raw CONNECT tunnel. + No HTTP inspection — all traffic to the host:port is allowed. + Use only when protocol-level inspection is not possible, such as `git` SSH-over-HTTPS or WebSocket upgrades. + +::: + +#### Enforcement and TLS Fields + +```yaml +endpoints: + - host: api.example.com + port: 443 + protocol: rest # Enable HTTP inspection + enforcement: enforce # Block non-matching requests (vs "audit" = log only) + tls: terminate # OpenShell terminates TLS to inspect HTTP layer + rules: + - allow: { method: GET, path: "/v1/**" } + - allow: { method: POST, path: "/v1/chat/completions" } +``` + +:::{note} +`access: full` bypasses all HTTP-layer rules. +The `github` policy uses `access: full` because `git` requires CONNECT tunneling. +This means method and path restrictions cannot be enforced on `api.github.com` — the agent has full API access. +See [Security Best Practices](../security/best-practices.md) for hardening options. +::: + ### Re-Run Onboard Apply the updated policy by re-running the onboard wizard: @@ -103,7 +149,7 @@ Available presets: | Preset | Endpoints | |--------|-----------| -| `discord` | Discord webhook API | +| `discord` | Discord REST API, WebSocket gateway, CDN | | `docker` | Docker Hub, NVIDIA container registry | | `huggingface` | Hugging Face model registry | | `jira` | Atlassian Jira API | diff --git a/docs/reference/network-policies.md b/docs/reference/network-policies.md index 68c052686b9..e2dd1ba190b 100644 --- a/docs/reference/network-policies.md +++ b/docs/reference/network-policies.md @@ -64,14 +64,9 @@ The following endpoint groups are allowed by default: - All methods * - `github` - - `github.com:443` + - `github.com:443`, `api.github.com:443` - `/usr/bin/gh`, `/usr/bin/git` - - All methods, all paths - -* - `github_rest_api` - - `api.github.com:443` - - `/usr/bin/gh` - - GET, POST, PATCH, PUT, DELETE + - `access: full` (no HTTP inspection — CONNECT tunnel) * - `clawhub` - `clawhub.ai:443` @@ -91,13 +86,27 @@ The following endpoint groups are allowed by default: * - `npm_registry` - `registry.npmjs.org:443` - `/usr/local/bin/openclaw`, `/usr/local/bin/npm`, `/usr/local/bin/node` - - All methods, all paths + - `access: full` (no HTTP inspection — CONNECT tunnel) * - `telegram` - `api.telegram.org:443` - - Any binary + - `/usr/local/bin/node` - GET, POST on `/bot*/**` +* - `discord` + - `discord.com:443`, `gateway.discord.gg:443`, `cdn.discordapp.com:443` + - `/usr/local/bin/node` + - REST API allows GET and POST. + WebSocket gateway uses `access: full`. + CDN allows GET only. + +::: + +:::{note} +Endpoints with `access: full` use a raw CONNECT tunnel with no HTTP-layer inspection. +Method and path restrictions cannot be enforced on these endpoints. +The `github` policy uses `access: full` because `git` requires CONNECT tunneling. +See [Security Best Practices](../security/best-practices.md) for details on the L4-only vs L7 inspection trade-off. ::: All endpoints use TLS termination and are enforced at port 443.