Автентифікація довіреного проксі

​

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

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

​

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

• Ваш проксі не автентифікує користувачів, а лише завершує TLS або балансує навантаження.
• Існує будь-який шлях до Gateway в обхід проксі (прогалини в міжмережевому екрані, доступ із внутрішньої мережі).
• Ви не впевнені, що проксі правильно видаляє або перезаписує переспрямовані заголовки.
• Вам потрібен лише особистий однокористувацький доступ (натомість розгляньте Tailscale Serve + local 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 Plugin, що використовують автентифікацію 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.
• Використовуйте попереднє завантаження, лише якщо свідомо виконуєте його вимоги для повного набору доменів.
• Локальна розробка лише через local 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"], // 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",
      },
    },
  },
}

​

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

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

​

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

• Проксі — єдиний шлях: порт Gateway захищено брандмауером від усіх підключень, крім вашого проксі.
• Мінімальний список trustedProxies: лише фактичні IP-адреси ваших проксі, а не цілі підмережі.
• Джерело проксі через local loopback вибрано свідомо: автентифікація через довірений проксі працює за принципом безпечної відмови для запитів із джерелом local loopback, якщо gateway.auth.trustedProxy.allowLoopback явно не ввімкнено для проксі на тому самому хості.
• Проксі видаляє заголовки: ваш проксі перезаписує (а не доповнює) отримані від клієнтів заголовки x-forwarded-*.
• Завершення TLS: ваш проксі обробляє TLS; користувачі підключаються через HTTPS.
• allowedOrigins задано явно: Control UI поза local 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 — простіша альтернатива для доступу лише з мережі Tailscale