Доверенная аутентификация прокси

Когда использовать

Используйте режим аутентификации trusted-proxy, когда:

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

Когда НЕ использовать

• Если ваш прокси не аутентифицирует пользователей (только TLS-терминатор или балансировщик нагрузки).
• Если есть любой путь к Gateway в обход прокси (дыры в файрволе, доступ из внутренней сети).
• Если вы не уверены, что ваш прокси корректно удаляет/перезаписывает переданные заголовки.
• Если вам нужен только личный однопользовательский доступ (рассмотрите 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 + файрвол).

Пользовательские 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=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", если вы хотите использовать аутентификацию на основе токена.

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

Заголовок областей оператора

Аутентификация через доверенный прокси — это HTTP-режим, несущий идентификацию, поэтому вызывающие стороны могут при необходимости объявлять области оператора с помощью x-openclaw-scopes в запросах HTTP API.

Примечание: области WebSocket определяются рукопожатием протокола Gateway и привязкой идентичности устройства. В запросах обновления WebSocket для Control UI x-openclaw-scopes является только ограничением согласованных областей сеанса, а не предоставлением доступа. Поведение областей WebSocket с доверенным прокси см. в разделе поведение сопряжения Control UI.

Примеры:

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

Поведение:

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

Практическое правило: отправляйте x-openclaw-scopes явно, когда нужно, чтобы запрос через доверенный прокси был уже значений по умолчанию, или когда маршруту Plugin с аутентификацией Gateway требуется что-то сильнее области записи.

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

Перед включением аутентификации через доверенный прокси проверьте:

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

Аудит безопасности

openclaw security audit пометит аутентификацию через доверенный прокси находкой с критической серьезностью. Это намеренно — это напоминание, что вы делегируете безопасность настройке своего прокси.

Аудит проверяет:

• Базовое предупреждение/критическое напоминание gateway.trusted_proxy_auth
• Отсутствующую конфигурацию trustedProxies
• Отсутствующую конфигурацию userHeader
• Пустой allowUsers (разрешает любого аутентифицированного пользователя)
• Включенный allowLoopback для источников прокси на том же хосте
• Шаблонную или отсутствующую политику браузерных источников на открытых поверхностях Control UI

Устранение неполадок

Миграция с аутентификации по токену

Если вы переходите с аутентификации по токену на доверенный прокси:

Связанные разделы

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