Аутентификация через доверенный прокси

​

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

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

​

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

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

​

Как это работает

​

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

{
  gateway: {
    // По умолчанию аутентификация доверенного прокси требует, чтобы IP-адрес источника прокси не был loopback-адресом
    bind: "lan",

    // КРИТИЧЕСКИ ВАЖНО: добавляйте сюда только IP-адреса своих прокси
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Заголовок с идентификатором аутентифицированного пользователя (обязательно)
        userHeader: "x-forwarded-user",

        // Необязательно: заголовки, которые ОБЯЗАТЕЛЬНО должны присутствовать (проверка прокси)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Необязательно: ограничить доступ указанными пользователями (пусто = разрешить всем)
        allowUsers: ["nick@example.com", "admin@company.org"],

        // Необязательно: разрешить loopback-прокси на том же хосте после явного включения
        allowLoopback: false,
      },
    },
  },
}

​

Справочник по конфигурации

​

Поведение сопряжения Control UI

• Сеансы WebSocket Control UI без устройства подключаются, но по умолчанию не получают областей доступа оператора. OpenClaw очищает список запрошенных областей доступа до [], чтобы сеанс, не привязанный к одобренному сопряжённому устройству или токену, не мог самостоятельно назначить себе разрешения.
• Если после успешного подключения WebSocket методы завершаются ошибкой missing scope, используйте HTTPS, чтобы браузер мог создать идентификатор устройства и завершить сопряжение. См. Небезопасный HTTP для Control UI.
• Только для аварийного доступа: gateway.controlUi.dangerouslyDisableDeviceAuth=true сохраняет запрошенные области доступа даже без идентификатора устройства. Это серьёзно снижает безопасность; как можно скорее отмените это изменение. См. Небезопасный HTTP для Control UI.

• В этом режиме сопряжение больше не является основным механизмом ограничения доступа к Control UI.
• Фактическим механизмом контроля доступа становятся политика аутентификации вашего обратного прокси и allowUsers.
• Разрешайте входящий трафик Gateway только с IP-адресов доверенных прокси (gateway.trustedProxies + межсетевой экран).

​

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

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

• Если заголовок присутствует, OpenClaw учитывает объявленный набор областей доступа.
• Если заголовок присутствует, но пуст, запрос объявляет отсутствие областей доступа оператора.
• Если заголовок отсутствует, обычные HTTP API с передачей идентификатора используют стандартный набор областей доступа оператора по умолчанию (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• HTTP-маршруты плагинов с аутентификацией Gateway по умолчанию имеют более узкие права: при отсутствии x-openclaw-scopes их область доступа среды выполнения ограничивается только operator.write.
• HTTP-запросы из браузера должны проходить проверку gateway.controlUi.allowedOrigins (или намеренно включённый резервный режим заголовка Host) даже после успешной аутентификации через доверенный прокси.

​

Завершение 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.
• Используйте предварительную загрузку, только если вы намеренно выполняете её требования для всего набора доменов.
• Локальная разработка исключительно через loopback не получает преимуществ от HSTS.

​

Примеры настройки прокси

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // IP-адрес Pomerium
    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"], // IP-адрес прокси Caddy/sidecar
    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"], // IP-адрес nginx/oauth2-proxy
    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"], // IP-адрес контейнера Traefik
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

Смешанная конфигурация токенов

• Удалите общий токен при использовании режима доверенного прокси или
• Переключите gateway.auth.mode на "token", если планируете использовать аутентификацию по токену.

​

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

• Прокси — единственный путь: порт 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 межсетевым экраном, чтобы удалённые клиенты вне прокси не могли подключаться к нему напрямую.

​

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

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

​

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

​

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

​

Связанные материалы

• Конфигурация — справочник по конфигурации
• Области доступа оператора — роли, области доступа и проверки подтверждений
• Удалённый доступ — другие схемы удалённого доступа
• Безопасность — полное руководство по безопасности
• Tailscale — более простая альтернатива для доступа только из tailnet-сети