Uwierzytelnianie zaufanego proxy

​

Kiedy używać

• Uruchamiasz OpenClaw za proxy świadomym tożsamości (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Twoje proxy obsługuje całe uwierzytelnianie i przekazuje tożsamość użytkownika przez nagłówki.
• Pracujesz w środowisku Kubernetes lub kontenerowym, gdzie proxy jest jedyną ścieżką do Gateway.
• Napotykasz błędy WebSocket 1008 unauthorized, ponieważ przeglądarki nie mogą przekazywać tokenów w ładunkach WS.

​

Kiedy NIE używać

• Jeśli Twoje proxy nie uwierzytelnia użytkowników (jest tylko terminatorem TLS albo load balancerem).
• Jeśli istnieje jakakolwiek ścieżka do Gateway, która omija proxy (luki w firewallu, dostęp z sieci wewnętrznej).
• Jeśli nie masz pewności, czy Twoje proxy poprawnie usuwa/nadpisuje przekazywane nagłówki.
• Jeśli potrzebujesz tylko osobistego dostępu dla jednego użytkownika (rozważ Tailscale Serve + loopback dla prostszej konfiguracji).

​

Jak to działa

​

Zachowanie parowania Control UI

• Sesje WebSocket Control UI bez urządzenia łączą się, ale domyślnie nie otrzymują żadnych zakresów operatora. OpenClaw czyści żądaną listę zakresów do [], aby sesja, która nie jest powiązana z zatwierdzonym sparowanym urządzeniem/tokenem, nie mogła samodzielnie deklarować uprawnień.
• Jeśli metody kończą się błędem missing scope po udanym połączeniu WebSocket, użyj HTTPS, aby przeglądarka mogła wygenerować tożsamość urządzenia i dokończyć parowanie. Zobacz niezabezpieczony HTTP Control UI.
• Tylko awaryjnie: gateway.controlUi.dangerouslyDisableDeviceAuth=true zachowuje żądane zakresy nawet bez tożsamości urządzenia. To poważne obniżenie poziomu bezpieczeństwa; szybko je wycofaj. Zobacz niezabezpieczony HTTP Control UI.

• Jeśli Twoje proxy wysyła x-openclaw-scopes w żądaniu aktualizacji WebSocket Control UI, OpenClaw ogranicza zakresy sesji do części wspólnej żądanych zakresów i zadeklarowanych zakresów. Ten nagłówek nie przyznaje zakresów; tylko zawęża to, co sesja może posiadać.

• Parowanie nie jest już główną bramą dostępu do Control UI w tym trybie.
• Polityka uwierzytelniania Twojego reverse proxy i allowUsers stają się faktyczną kontrolą dostępu.
• Ogranicz dostęp przychodzący do Gateway wyłącznie do zaufanych adresów IP proxy (gateway.trustedProxies + firewall).

​

Konfiguracja

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

​

Referencja konfiguracji

​

Terminacja TLS i HSTS

Strict-Transport-Security: max-age=31536000; includeSubDomains

{
  gateway: {
    tls: { enabled: true },
    http: {
      securityHeaders: {
        strictTransportSecurity: "max-age=31536000; includeSubDomains",
      },
    },
  },
}

​

Wskazówki wdrożeniowe

• Zacznij najpierw od krótkiego maksymalnego wieku (na przykład max-age=300) podczas walidacji ruchu.
• Zwiększ do wartości długotrwałych (na przykład max-age=31536000) dopiero po uzyskaniu wysokiej pewności.
• Dodaj includeSubDomains tylko wtedy, gdy każda subdomena jest gotowa na HTTPS.
• Używaj preload tylko wtedy, gdy celowo spełniasz wymagania preload dla całego zestawu domen.
• Lokalne programowanie wyłącznie na loopback nie odnosi korzyści z HSTS.

​

Przykłady konfiguracji proxy

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

​

Mieszana konfiguracja tokenów

• Usuń współdzielony token podczas używania trybu trusted-proxy albo
• Przełącz gateway.auth.mode na "token", jeśli zamierzasz używać uwierzytelniania opartego na tokenach.

​

Nagłówek zakresów operatora

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

• Gdy nagłówek jest obecny, OpenClaw respektuje zadeklarowany zestaw zakresów.
• Gdy nagłówek jest obecny, ale pusty, żądanie deklaruje brak zakresów operatora.
• Gdy nagłówka nie ma, zwykłe HTTP API niosące tożsamość wracają do standardowego domyślnego zestawu zakresów operatora.
• Trasy HTTP Plugin uwierzytelniane przez Gateway są domyślnie węższe: gdy x-openclaw-scopes nie występuje, ich zakres środowiska uruchomieniowego wraca do operator.write.
• Żądania HTTP pochodzące z przeglądarki nadal muszą przejść gateway.controlUi.allowedOrigins (albo celowy tryb awaryjny na podstawie nagłówka Host), nawet po powodzeniu uwierzytelniania przez zaufane proxy.
• Dla sesji WebSocket Control UI x-openclaw-scopes jest limitem zakresu, gdy występuje w żądaniu aktualizacji. Pusta wartość nie daje żadnych zakresów.

​

Lista kontrolna bezpieczeństwa

• Proxy jest jedyną ścieżką: port Gateway jest odgrodzony zaporą od wszystkiego poza Twoim proxy.
• trustedProxies jest minimalne: tylko rzeczywiste adresy IP proxy, nie całe podsieci.
• Źródło proxy loopback jest celowe: uwierzytelnianie przez zaufane proxy odmawia dostępu domyślnie dla żądań ze źródła loopback, chyba że gateway.auth.trustedProxy.allowLoopback jest jawnie włączone dla proxy na tym samym hoście.
• Proxy usuwa nagłówki: Twoje proxy nadpisuje (nie dopisuje) nagłówki x-forwarded-* od klientów.
• Terminacja TLS: Twoje proxy obsługuje TLS; użytkownicy łączą się przez HTTPS.
• allowedOrigins jest jawne: Control UI poza loopback używa jawnego gateway.controlUi.allowedOrigins.
• allowUsers jest ustawione (zalecane): ogranicz dostęp do znanych użytkowników zamiast dopuszczać każdego uwierzytelnionego.
• Brak mieszanej konfiguracji tokenów: nie ustawiaj jednocześnie gateway.auth.token i gateway.auth.mode: "trusted-proxy".
• Lokalny awaryjny dostęp hasłem jest prywatny: jeśli konfigurujesz gateway.auth.password dla wewnętrznych bezpośrednich wywołujących, utrzymuj port Gateway za zaporą, aby zdalni klienci spoza proxy nie mogli dotrzeć do niego bezpośrednio.

​

Audyt bezpieczeństwa

• Podstawowe ostrzeżenie/przypomnienie krytyczne gateway.trusted_proxy_auth
• Brak konfiguracji trustedProxies
• Brak konfiguracji userHeader
• Puste allowUsers (pozwala dowolnemu uwierzytelnionemu użytkownikowi)
• Włączone allowLoopback dla źródeł proxy na tym samym hoście
• Wieloznaczną albo brakującą politykę źródeł przeglądarki na wystawionych powierzchniach Control UI

​

Rozwiązywanie problemów

​

Migracja z uwierzytelniania tokenem

​

Powiązane

• Konfiguracja — dokumentacja konfiguracji
• Dostęp zdalny — inne wzorce dostępu zdalnego
• Bezpieczeństwo — pełny przewodnik bezpieczeństwa
• Tailscale — prostsza alternatywa dla dostępu wyłącznie z tailnet