Довірена автентифікація через проксі

Коли використовувати

Використовуйте режим автентифікації trusted-proxy, коли:

• Ви запускаєте OpenClaw за проксі з урахуванням ідентичності (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Ваш проксі обробляє всю автентифікацію та передає ідентичність користувача через заголовки.
• Ви працюєте в Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway.
• Ви отримуєте помилки WebSocket 1008 unauthorized, бо браузери не можуть передавати токени в корисному навантаженні WS.

Коли НЕ використовувати

• Якщо ваш проксі не автентифікує користувачів (лише TLS-термінатор або балансувальник навантаження).
• Якщо існує будь-який шлях до Gateway в обхід проксі (прогалини у firewall, доступ з внутрішньої мережі).
• Якщо ви не впевнені, чи ваш проксі коректно видаляє/перезаписує переслані заголовки.
• Якщо вам потрібен лише персональний однокористувацький доступ (розгляньте Tailscale Serve + loopback для простішого налаштування).

Як це працює

Поведінка сполучення Control UI

Коли активний gateway.auth.mode = "trusted-proxy" і запит проходить перевірки trusted-proxy, WebSocket-сеанси Control UI можуть підключатися без ідентичності сполученого пристрою.

Наслідки для області дії:

• WebSocket-сеанси Control UI без пристрою підключаються, але типово не отримують операторських областей дії. OpenClaw очищає список запитаних областей дії до [], щоб сеанс, не прив'язаний до схваленого сполученого пристрою/токена, не міг самостійно оголошувати дозволи.
• Якщо методи завершуються помилкою missing scope після успішного WebSocket-підключення, використовуйте HTTPS, щоб браузер міг згенерувати ідентичність пристрою та завершити сполучення. Див. небезпечний HTTP Control UI.
• Лише аварійний обхід: gateway.controlUi.dangerouslyDisableDeviceAuth=true зберігає запитані області дії навіть без ідентичності пристрою. Це суттєве зниження рівня безпеки; швидко скасуйте. Див. небезпечний HTTP Control UI.

Обмеження областей дії зворотним проксі:

• Якщо ваш проксі надсилає x-openclaw-scopes у запиті оновлення WebSocket для Control UI, OpenClaw обмежує області дії сеансу перетином запитаних і оголошених областей дії. Цей заголовок не надає областей дії; він лише звужує те, що може мати сеанс.

Наслідки:

• Сполучення більше не є основним бар'єром для доступу до Control UI в цьому режимі.
• Ваша політика автентифікації зворотного проксі та allowUsers стають фактичним контролем доступу.
• Тримайте вхідний доступ до gateway обмеженим лише довіреними IP-адресами проксі (gateway.trustedProxies + firewall).

Власні WebSocket-клієнти не є сеансами Control UI. gateway.controlUi.dangerouslyDisableDeviceAuth не надає областей дії довільним клієнтам client.mode: "backend" або клієнтам у стилі CLI. Власна автоматизація має використовувати ідентичність/сполучення пристрою, зарезервований прямий локальний допоміжний шлях backend client.id: "gateway-client" або Plugin admin HTTP RPC, коли поверхня HTTP-запит/відповідь підходить краще.

Конфігурація

{  gateway: {    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default    bind: "lan",     // CRITICAL: Only add your proxy's IP(s) here    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header containing authenticated user identity (required)        userHeader: "x-forwarded-user",         // Optional: headers that MUST be present (proxy verification)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Optional: restrict to specific users (empty = allow all)        allowUsers: ["nick@example.com", "admin@company.org"],         // Optional: allow a same-host loopback proxy after explicit opt-in        allowLoopback: false,      },    },  },}

Довідник конфігурації

TLS-термінація та HSTS

Використовуйте одну точку TLS-термінації та застосовуйте HSTS там.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

Рекомендації з розгортання

• Спершу почніть із короткого max age (наприклад, max-age=300), поки перевіряєте трафік.
• Збільшуйте до довготривалих значень (наприклад, max-age=31536000) лише після високої впевненості.
• Додавайте includeSubDomains лише якщо кожен піддомен готовий до HTTPS.
• Використовуйте preload лише якщо ви свідомо відповідаєте вимогам preload для повного набору доменів.
• Локальна розробка лише через loopback не отримує користі від HSTS.

Приклади налаштування проксі

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Pomerium's IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

location / {    auth_request /oauth2/auth;    auth_request_set $user $upstream_http_x_auth_request_email;     proxy_pass http://openclaw:18789;    proxy_set_header X-Auth-Request-Email $user;    proxy_http_version 1.1;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection "upgrade";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // Traefik container IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Змішана конфігурація токенів

OpenClaw відхиляє неоднозначні конфігурації, де одночасно активні gateway.auth.token (або OPENCLAW_GATEWAY_TOKEN) і режим trusted-proxy. Змішані конфігурації токенів можуть призвести до того, що loopback-запити тихо автентифікуватимуться неправильним шляхом автентифікації.

Якщо під час запуску ви бачите помилку mixed_trusted_proxy_token:

• Видаліть спільний токен, коли використовуєте режим trusted-proxy, або
• Перемкніть gateway.auth.mode на "token", якщо ви маєте намір використовувати автентифікацію на основі токенів.

Довірені proxy-заголовки ідентичності loopback усе ще завершуються відмовою: виклики з того самого хоста не автентифікуються неявно як користувачі proxy. Внутрішні виклики OpenClaw, що обходять proxy, натомість можуть автентифікуватися через gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Резервний варіант із токеном у режимі trusted-proxy навмисно не підтримується.

Заголовок операторських scopes

Автентифікація trusted-proxy є HTTP-режимом, що передає ідентичність, тож виклики можуть необов’язково оголошувати операторські scopes за допомогою x-openclaw-scopes в HTTP API-запитах.

Примітка: WebSocket scopes визначаються handshake протоколу Gateway і прив’язкою ідентичності пристрою. У запитах Control UI на WebSocket upgrade x-openclaw-scopes є лише обмеженням negotiated session scopes, а не наданням прав. Про поведінку WebSocket scope з trusted-proxy див. поведінку pairing Control UI.

Приклади:

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

Поведінка:

• Коли заголовок присутній, OpenClaw враховує оголошений набір scopes.
• Коли заголовок присутній, але порожній, запит оголошує, що операторських scopes немає.
• Коли заголовок відсутній, звичайні HTTP API, що передають ідентичність, повертаються до стандартного набору операторських scopes за замовчуванням.
• Plugin HTTP routes з Gateway-автентифікацією типово мають вужчі права: коли x-openclaw-scopes відсутній, їхній runtime scope повертається до operator.write.
• HTTP-запити з браузерним origin усе ще мають пройти gateway.controlUi.allowedOrigins (або навмисний fallback-режим Host-заголовка) навіть після успішної trusted-proxy auth.
• Для WebSocket-сеансів Control UI x-openclaw-scopes є обмеженням scopes, коли він присутній у upgrade-запиті. Порожнє значення не дає жодних scopes.

Практичне правило: надсилайте x-openclaw-scopes явно, коли хочете, щоб trusted-proxy-запит був вужчим за типові значення, або коли Plugin route з gateway-auth потребує чогось сильнішого за write scope.

Контрольний список безпеки

Перш ніж увімкнути trusted-proxy auth, перевірте:

• [ ] Proxy є єдиним шляхом: порт Gateway закритий firewall для всього, крім вашого proxy.
• [ ] trustedProxies мінімальний: лише фактичні IP-адреси вашого proxy, а не цілі підмережі.
• [ ] Джерело loopback proxy є навмисним: trusted-proxy auth завершується відмовою для запитів із loopback-джерела, якщо gateway.auth.trustedProxy.allowLoopback не ввімкнено явно для proxy на тому самому хості.
• [ ] Proxy прибирає заголовки: ваш proxy перезаписує (а не додає) x-forwarded-* заголовки від клієнтів.
• [ ] TLS termination: ваш proxy обробляє TLS; користувачі підключаються через HTTPS.
• [ ] allowedOrigins задано явно: Control UI не з loopback використовує явний gateway.controlUi.allowedOrigins.
• [ ] allowUsers задано (рекомендовано): обмежте доступ відомими користувачами замість дозволяти всім автентифікованим.
• [ ] Без змішаної конфігурації токенів: не задавайте одночасно gateway.auth.token і gateway.auth.mode: "trusted-proxy".
• [ ] Локальний fallback пароля приватний: якщо ви налаштовуєте gateway.auth.password для внутрішніх прямих викликів, тримайте порт Gateway за firewall, щоб віддалені клієнти не через proxy не могли звернутися до нього напряму.

Аудит безпеки

openclaw security audit позначить trusted-proxy auth знахідкою з критичною серйозністю. Це навмисно — нагадування, що ви делегуєте безпеку налаштуванню свого proxy.

Аудит перевіряє:

• Базове попередження/критичне нагадування gateway.trusted_proxy_auth
• Відсутню конфігурацію trustedProxies
• Відсутню конфігурацію userHeader
• Порожній allowUsers (дозволяє будь-якого автентифікованого користувача)
• Увімкнений allowLoopback для proxy-джерел на тому самому хості
• Wildcard або відсутню політику браузерного origin на відкритих поверхнях Control UI

Усунення несправностей

Міграція з token auth

Якщо ви переходите з token auth на trusted-proxy:

Пов’язане

• Конфігурація — довідник конфігурації
• Віддалений доступ — інші шаблони віддаленого доступу
• Безпека — повний посібник із безпеки
• Tailscale — простіша альтернатива для доступу лише з tailnet