Uwierzytelnianie przez zaufane proxy

# Kiedy używać

Użyj trybu uwierzytelniania trusted-proxy, gdy:

• 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.
• Działasz w środowisku Kubernetes lub kontenerowym, gdzie proxy jest jedyną ścieżką do Gateway.
• Trafiasz na 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 lub równoważnikiem obciążenia).
• Jeśli istnieje jakakolwiek ścieżka do Gateway omijająca proxy (luki w zaporze, 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

Gdy gateway.auth.mode = "trusted-proxy" jest aktywne, a żądanie przejdzie kontrole trusted-proxy, sesje WebSocket Control UI mogą łączyć się bez tożsamości parowania urządzenia.

Konsekwencje:

• Parowanie nie jest już główną bramką dostępu do Control UI w tym trybie.
• Polityka uwierzytelniania Twojego reverse proxy i allowUsers stają się skuteczną kontrolą dostępu.
• Ogranicz wejście do gateway wyłącznie do zaufanych adresów IP proxy (gateway.trustedProxies + zapora).

# 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: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# Opis konfiguracji

# Terminacja TLS i HSTS

Użyj jednego punktu terminacji TLS i zastosuj tam 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 walidowania 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 pełnego zestawu domen.
• Lokalne programowanie wyłącznie na loopback nie korzysta 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: [email protected]
    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

OpenClaw odrzuca niejednoznaczne konfiguracje, w których jednocześnie aktywne są gateway.auth.token (lub OPENCLAW_GATEWAY_TOKEN) i tryb trusted-proxy. Mieszane konfiguracje tokenów mogą sprawić, że żądania loopback zostaną po cichu uwierzytelnione na niewłaściwej ścieżce uwierzytelniania.

Jeśli podczas uruchamiania zobaczysz błąd mixed_trusted_proxy_token:

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

Nagłówki tożsamości trusted-proxy z loopback nadal kończą się zamkniętą odmową: wywołujący z tego samego hosta nie są po cichu uwierzytelniani jako użytkownicy proxy. Wewnętrzni wywołujący OpenClaw, którzy omijają proxy, mogą zamiast tego uwierzytelniać się przez gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Awaryjny powrót do tokenu pozostaje celowo nieobsługiwany w trybie trusted-proxy.

# Nagłówek zakresów operatora

Uwierzytelnianie trusted-proxy jest trybem HTTP niosącym tożsamość, więc wywołujący mogą opcjonalnie deklarować zakresy operatora za pomocą x-openclaw-scopes.

Przykłady:

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

Zachowanie:

• 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 interfejsy API HTTP 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 jest nieobecny, ich zakres czasu wykonania wraca do operator.write.
• Żądania HTTP pochodzące z przeglądarki nadal muszą przejść gateway.controlUi.allowedOrigins (lub celowy tryb awaryjny oparty na nagłówku Host), nawet po powodzeniu uwierzytelniania trusted-proxy.

Praktyczna zasada: wysyłaj x-openclaw-scopes jawnie, gdy chcesz, aby żądanie trusted-proxy było węższe niż wartości domyślne, albo gdy trasa Plugin uwierzytelniana przez gateway wymaga czegoś silniejszego niż zakres zapisu.

# Lista kontrolna bezpieczeństwa

Przed włączeniem uwierzytelniania trusted-proxy sprawdź:

• [ ] Proxy is the only path: Port Gateway jest odizolowany zaporą od wszystkiego poza Twoim proxy.
• [ ] trustedProxies is minimal: Tylko rzeczywiste adresy IP Twojego proxy, a nie całe podsieci.
• [ ] Loopback proxy source is deliberate: Uwierzytelnianie trusted-proxy kończy się bezpieczną odmową 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 strips headers: Twoje proxy nadpisuje (nie dopisuje) nagłówki x-forwarded-* od klientów.
• [ ] TLS termination: Twoje proxy obsługuje TLS; użytkownicy łączą się przez HTTPS.
• [ ] allowedOrigins is explicit: Control UI poza loopback używa jawnego gateway.controlUi.allowedOrigins.
• [ ] allowUsers is set (zalecane): Ogranicz dostęp do znanych użytkowników zamiast zezwalać każdemu uwierzytelnionemu.
• [ ] No mixed token config: Nie ustawiaj jednocześnie gateway.auth.token i gateway.auth.mode: "trusted-proxy".
• [ ] Local password fallback is private: Jeśli konfigurujesz gateway.auth.password dla wewnętrznych wywołań bezpośrednich, utrzymuj port Gateway za zaporą, aby zdalni klienci spoza proxy nie mogli dotrzeć do niego bezpośrednio.

# Audyt bezpieczeństwa

openclaw security audit oznaczy uwierzytelnianie trusted-proxy wynikiem o ważności krytycznej. To zamierzone — jest to przypomnienie, że delegujesz bezpieczeństwo do konfiguracji proxy.

Audyt sprawdza:

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

# Rozwiązywanie problemów

# Migracja z uwierzytelniania tokenem

Jeśli przechodzisz z uwierzytelniania tokenem na trusted-proxy:

# Powiązane

• Konfiguracja — dokumentacja konfiguracji
• Dostęp zdalny — inne wzorce dostępu zdalnego
• Bezpieczeństwo — pełny przewodnik po bezpieczeństwie
• Tailscale — prostsza alternatywa dla dostępu tylko w tailnet