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

​

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

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

​

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

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

​

Як це працює

​

Поведінка сполучення 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).

​

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

{
  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

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",
      },
    },
  },
}

​

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

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

​

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

• 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.

​

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

• 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 не могли звернутися до нього напряму.

​

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

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

​

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

​

Міграція з token auth

​

Пов’язане

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