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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

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

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

​

Як це працює

​

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

• Сполучення більше не є основним бар’єром для доступу до 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=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", якщо ви плануєте автентифікацію на основі токенів.

​

Заголовок операторських областей дії

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

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

​

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

• Проксі — єдиний шлях: Порт Gateway захищено брандмауером від усього, крім вашого проксі.
• trustedProxies мінімальний: Лише фактичні IP-адреси ваших проксі, а не цілі підмережі.
• Джерело loopback-проксі вибране навмисно: Автентифікація trusted-proxy закривається з відмовою для запитів із 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 для джерел проксі на тому самому хості
• Політику походження браузера з wildcard або її відсутність на відкритих поверхнях Control UI

​

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

​

Міграція з автентифікації за токеном

​

Пов’язане

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