Uwierzytelnianie zaufanego serwera proxy

​

Kiedy używać

• Uruchamiasz OpenClaw za serwerem proxy rozpoznającym tożsamość (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Serwer proxy obsługuje całe uwierzytelnianie i przekazuje tożsamość użytkownika w nagłówkach.
• Korzystasz ze środowiska Kubernetes lub kontenerowego, w którym serwer proxy jest jedyną drogą do Gateway.
• Napotykasz błędy WebSocket 1008 unauthorized, ponieważ przeglądarki nie mogą przekazywać tokenów w ładunkach WS.

​

Kiedy NIE używać

• Serwer proxy nie uwierzytelnia użytkowników (jest tylko terminatorem TLS lub modułem równoważenia obciążenia).
• Istnieje jakakolwiek droga do Gateway omijająca serwer proxy (luki w zaporze, dostęp z sieci wewnętrznej).
• Nie masz pewności, czy serwer proxy prawidłowo usuwa lub nadpisuje przekazywane nagłówki.
• Potrzebujesz tylko osobistego dostępu dla jednego użytkownika (zamiast tego rozważ Tailscale Serve + local loopback).

​

Jak to działa

​

Konfiguracja

{
  gateway: {
    // Uwierzytelnianie przez zaufany serwer proxy domyślnie wymaga, aby źródłowy adres IP serwera proxy nie był adresem pętli zwrotnej
    bind: "lan",

    // KRYTYCZNE: dodaj tutaj wyłącznie adresy IP swojego serwera proxy
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Nagłówek zawierający tożsamość uwierzytelnionego użytkownika (wymagany)
        userHeader: "x-forwarded-user",

        // Opcjonalnie: nagłówki, które MUSZĄ być obecne (weryfikacja serwera proxy)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Opcjonalnie: ograniczenie do określonych użytkowników (pusta lista = zezwól wszystkim)
        allowUsers: ["nick@example.com", "admin@company.org"],

        // Opcjonalnie: zezwolenie na serwer proxy local loopback na tym samym hoście po jawnym włączeniu
        allowLoopback: false,
      },
    },
  },
}

​

Dokumentacja konfiguracji

​

Zachowanie parowania interfejsu Control UI

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

• W tym trybie parowanie nie jest już podstawową bramą dostępu do interfejsu Control UI.
• Zasady uwierzytelniania odwrotnego serwera proxy i allowUsers stają się faktycznym mechanizmem kontroli dostępu.
• Ogranicz ruch przychodzący do Gateway wyłącznie do adresów IP zaufanych serwerów proxy (gateway.trustedProxies + zapora).

​

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łówek jest nieobecny, standardowe interfejsy API HTTP przenoszące tożsamość używają standardowego domyślnego zestawu zakresów operatora (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Trasy HTTP pluginów uwierzytelniane przez Gateway są domyślnie bardziej ograniczone: gdy x-openclaw-scopes jest nieobecny, ich zakres działania ogranicza się wyłącznie do operator.write.
• Żądania HTTP pochodzące z przeglądarki nadal muszą przejść kontrolę gateway.controlUi.allowedOrigins (lub celowo włączony awaryjny tryb nagłówka Host), nawet po pomyślnym uwierzytelnieniu przez zaufany serwer proxy.

​

Terminowanie TLS i HSTS

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

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

​

Wskazówki dotyczące wdrażania

• Zacznij od krótkiego maksymalnego czasu ważności (na przykład max-age=300) podczas weryfikowania ruchu.
• Zwiększ go do wartości długoterminowych (na przykład max-age=31536000) dopiero po uzyskaniu wysokiego poziomu pewności.
• Dodaj includeSubDomains tylko wtedy, gdy każda subdomena jest gotowa do obsługi HTTPS.
• Używaj preload tylko wtedy, gdy świadomie spełniasz wymagania wstępnego ładowania dla całego zestawu domen.
• Lokalne programowanie ograniczone wyłącznie do local loopback nie odnosi korzyści z HSTS.

​

Przykłady konfiguracji serwera proxy

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Adres 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",
      },
    },
  },
}

​

Konfiguracja mieszana z tokenem

• Usuń współdzielony token podczas korzystania z trybu zaufanego proxy albo
• Zmień gateway.auth.mode na "token", jeśli zamierzasz korzystać z uwierzytelniania opartego na tokenie.

​

Lista kontrolna bezpieczeństwa

• Proxy jest jedyną ścieżką: Port Gateway jest chroniony zaporą przed wszystkim poza Twoim proxy.
• Lista trustedProxies jest minimalna: Zawiera wyłącznie rzeczywiste adresy IP proxy, a nie całe podsieci.
• Źródło proxy w interfejsie pętli zwrotnej jest zamierzone: Uwierzytelnianie przez zaufane proxy odrzuca w razie wątpliwości żądania pochodzące z interfejsu pętli zwrotnej, chyba że dla proxy na tym samym hoście jawnie włączono gateway.auth.trustedProxy.allowLoopback.
• Proxy usuwa nagłówki: Twoje proxy nadpisuje (zamiast dołączać) nagłówki x-forwarded-* pochodzące od klientów.
• Terminacja TLS: Twoje proxy obsługuje TLS; użytkownicy łączą się przez HTTPS.
• Lista allowedOrigins jest jawna: Interfejs sterowania używany poza interfejsem pętli zwrotnej korzysta z jawnej wartości gateway.controlUi.allowedOrigins.
• Ustawiono allowUsers (zalecane): Ogranicz dostęp do znanych użytkowników zamiast zezwalać każdemu uwierzytelnionemu użytkownikowi.
• Brak mieszanej konfiguracji tokenu: Nie ustawiaj jednocześnie gateway.auth.token i gateway.auth.mode: "trusted-proxy".
• Lokalne uwierzytelnianie zapasowe hasłem jest prywatne: Jeśli konfigurujesz gateway.auth.password dla wewnętrznych klientów łączących się bezpośrednio, zabezpiecz port Gateway zaporą, aby zdalni klienci niekorzystający z proxy nie mogli uzyskać do niego bezpośredniego dostępu.

​

Audyt bezpieczeństwa

• Podstawowe ostrzeżenie lub krytyczne przypomnienie gateway.trusted_proxy_auth.
• Brak konfiguracji trustedProxies.
• Brak konfiguracji userHeader.
• Pustą listę allowUsers (zezwala każdemu uwierzytelnionemu użytkownikowi).
• Włączoną opcję allowLoopback dla źródeł proxy na tym samym hoście.

​

Rozwiązywanie problemów

​

Migracja z uwierzytelniania tokenem

​

Powiązane materiały

• Konfiguracja — dokumentacja konfiguracji
• Zakresy operatora — role, zakresy i kontrole zatwierdzeń
• Dostęp zdalny — inne wzorce dostępu zdalnego
• Bezpieczeństwo — pełny przewodnik dotyczący bezpieczeństwa
• Tailscale — prostsza alternatywa dla dostępu ograniczonego do sieci tailnet