Güvenilir proxy kimlik doğrulaması

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.

​

Ne zaman kullanılır?

• OpenClaw’ı kimlik farkındalığı olan bir proxy arkasında çalıştırıyorsanız (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + ileri kimlik doğrulama).
• Proxy’niz tüm kimlik doğrulamayı işliyor ve kullanıcı kimliğini başlıklar aracılığıyla iletiyorsa.
• Proxy’nin Gateway’e giden tek yol olduğu bir Kubernetes veya konteyner ortamındaysanız.
• Tarayıcılar WS yüklerinde token geçiremediği için WebSocket 1008 unauthorized hataları alıyorsanız.

​

Ne zaman kullanılmamalıdır?

• Proxy’niz kullanıcıların kimliğini doğrulamıyorsa (yalnızca TLS sonlandırıcı veya yük dengeleyiciyse).
• Gateway’e proxy’yi atlayan herhangi bir yol varsa (güvenlik duvarı açıklıkları, dahili ağ erişimi).
• Proxy’nizin iletilen başlıkları doğru şekilde kaldırıp/üzerine yazıp yazmadığından emin değilseniz.
• Yalnızca kişisel tek kullanıcılı erişime ihtiyacınız varsa (daha basit kurulum için Tailscale Serve + loopback seçeneğini değerlendirin).

​

Nasıl çalışır?

​

Control UI eşleştirme davranışı

• Bu modda eşleştirme artık Control UI erişimi için birincil kapı değildir.
• Ters proxy kimlik doğrulama politikanız ve allowUsers fiili erişim denetimi haline gelir.
• Gateway girişini yalnızca güvenilir proxy IP’lerine kilitli tutun (gateway.trustedProxies + güvenlik duvarı).

​

Yapılandırma

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

​

Yapılandırma başvurusu

​

TLS sonlandırma ve HSTS

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

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

​

Kullanıma alma yönergeleri

• Trafiği doğrularken önce kısa bir maksimum yaş ile başlayın (örneğin max-age=300).
• Uzun ömürlü değerlere (örneğin max-age=31536000) yalnızca güven yüksek olduğunda artırın.
• includeSubDomains değerini yalnızca her alt etki alanı HTTPS’ye hazırsa ekleyin.
• Preload’u yalnızca tüm etki alanı kümeniz için preload gereksinimlerini bilinçli olarak karşılıyorsanız kullanın.
• Yalnızca loopback yerel geliştirme HSTS’den fayda sağlamaz.

​

Proxy kurulum örnekleri

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

​

Karma token yapılandırması

• trusted-proxy modunu kullanırken paylaşılan token’ı kaldırın veya
• Token tabanlı kimlik doğrulama istiyorsanız gateway.auth.mode değerini "token" olarak değiştirin.

​

Operatör kapsamları başlığı

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

• Başlık mevcut olduğunda OpenClaw bildirilen kapsam kümesini dikkate alır.
• Başlık mevcut ancak boş olduğunda istek hiçbir operatör kapsamı bildirmez.
• Başlık yoksa normal kimlik taşıyan HTTP API’leri standart operatör varsayılan kapsam kümesine geri döner.
• Gateway kimlik doğrulamalı Plugin HTTP rotaları varsayılan olarak daha dardır: x-openclaw-scopes yoksa çalışma zamanı kapsamları operator.write kapsamına geri döner.
• Tarayıcı kökenli HTTP istekleri, trusted-proxy kimlik doğrulaması başarılı olduktan sonra bile gateway.controlUi.allowedOrigins değerinden (veya bilinçli Host başlığı geri dönüş modundan) geçmek zorundadır.

​

Güvenlik denetim listesi

• Proxy tek yoldur: Gateway bağlantı noktası, proxy’niz dışında her şeye karşı güvenlik duvarıyla kapatılmıştır.
• trustedProxies minimumdur: Tüm alt ağlar değil, yalnızca gerçek proxy IP’leriniz.
• Loopback proxy kaynağı bilinçlidir: trusted-proxy kimlik doğrulaması, aynı ana makinedeki bir proxy için gateway.auth.trustedProxy.allowLoopback açıkça etkinleştirilmedikçe loopback kaynaklı isteklerde kapalı kalacak şekilde başarısız olur.
• Proxy başlıkları temizler: Proxy’niz istemcilerden gelen x-forwarded-* başlıklarının üzerine yazar, ekleme yapmaz.
• TLS sonlandırması: Proxy’niz TLS’i işler; kullanıcılar HTTPS üzerinden bağlanır.
• allowedOrigins açıktır: Loopback olmayan Control UI, açık gateway.controlUi.allowedOrigins kullanır.
• allowUsers ayarlanmıştır (önerilir): Kimliği doğrulanmış herkese izin vermek yerine bilinen kullanıcılarla sınırlandırın.
• Karışık token yapılandırması yoktur: Hem gateway.auth.token hem de gateway.auth.mode: "trusted-proxy" ayarlamayın.
• Yerel parola geri dönüşü özeldir: Dahili doğrudan çağıranlar için gateway.auth.password yapılandırırsanız, proxy dışı uzak istemcilerin doğrudan erişememesi için Gateway bağlantı noktasını güvenlik duvarıyla kapalı tutun.

​

Güvenlik denetimi

• Temel gateway.trusted_proxy_auth uyarısı/kritik hatırlatıcısı
• Eksik trustedProxies yapılandırması
• Eksik userHeader yapılandırması
• Boş allowUsers (kimliği doğrulanmış herhangi bir kullanıcıya izin verir)
• Aynı ana makine proxy kaynakları için etkin allowLoopback
• Açığa çıkarılmış Control UI yüzeylerinde joker karakterli veya eksik tarayıcı kaynak politikası

​

Sorun giderme

​

Token kimlik doğrulamasından geçiş

​

İlgili

• Yapılandırma — yapılandırma başvurusu
• Uzak erişim — diğer uzak erişim kalıpları
• Güvenlik — tam güvenlik kılavuzu
• Tailscale — yalnızca tailnet erişimi için daha basit alternatif