Güvenilir proxy kimlik doğrulaması

​

Ne zaman kullanılmalı

• OpenClaw’ı bir kimlik farkındalıklı proxy arkasında çalıştırıyorsanız (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Proxy’niz tüm kimlik doğrulamayı yönetiyor 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 iletemediği için WebSocket 1008 unauthorized hataları alıyorsanız.

​

Ne zaman kullanılmamalı

• 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çıkları, dahili ağ erişimi).
• Proxy’nizin iletilen başlıkları doğru şekilde kaldırıp kaldırmadığından/ü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’i değerlendirin).

​

Nasıl çalışır

​

Control UI eşleştirme davranışı

• Cihazsız Control UI WebSocket oturumları bağlanır ancak varsayılan olarak operatör kapsamı almaz. OpenClaw istenen kapsam listesini [] olarak temizler; böylece onaylanmış eşleştirilmiş bir cihaza/token’a bağlı olmayan bir oturum izinleri kendi kendine beyan edemez.
• Başarılı bir WebSocket bağlantısından sonra yöntemler missing scope ile başarısız olursa, tarayıcının cihaz kimliği oluşturabilmesi ve eşleştirmeyi tamamlayabilmesi için HTTPS kullanın. Bkz. Control UI güvenli olmayan HTTP.
• Yalnızca acil durum için: gateway.controlUi.dangerouslyDisableDeviceAuth=true, cihaz kimliği olmasa bile istenen kapsamları korur. Bu ciddi bir güvenlik düşürmesidir; hızla geri alın. Bkz. Control UI güvenli olmayan HTTP.

• Proxy’niz Control UI WebSocket yükseltme isteğinde x-openclaw-scopes gönderirse, OpenClaw oturum kapsamlarını istenen kapsamlar ile beyan edilen kapsamların kesişimiyle sınırlar. Bu başlık kapsam vermez; yalnızca oturumun sahip olabileceklerini daraltır.

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

​

Yapılandırma

{
  gateway: {
    // Trusted-proxy kimlik doğrulaması varsayılan olarak non-loopback güvenilir proxy kaynağından gelen istekleri bekler
    bind: "lan",

    // KRİTİK: Buraya yalnızca proxy’nizin IP’lerini ekleyin
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Kimliği doğrulanmış kullanıcı kimliğini içeren başlık (zorunlu)
        userHeader: "x-forwarded-user",

        // İsteğe bağlı: bulunması ZORUNLU başlıklar (proxy doğrulaması)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // İsteğe bağlı: belirli kullanıcılarla sınırla (boş = tümüne izin ver)
        allowUsers: ["nick@example.com", "admin@company.org"],

        // İsteğe bağlı: açıkça kabul edildikten sonra aynı ana makinedeki loopback proxy’ye izin ver
        allowLoopback: false,
      },
    },
  },
}

​

Yapılandırma referansı

​

TLS sonlandırma ve HSTS

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

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

​

Dağıtım rehberi

• Trafiği doğrularken önce kısa bir maksimum yaşla başlayın (örneğin max-age=300).
• Uzun ömürlü değerlere (örneğin max-age=31536000) yalnızca güven yüksek olduktan sonra yükseltin.
• includeSubDomains değerini yalnızca her alt etki alanı HTTPS’ye hazırsa ekleyin.
• Preload’ı 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 yararlanmaz.

​

Proxy kurulum örnekleri

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium'un IP'si
    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'si
    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'si
    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 konteyner IP'si
    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 amaçlıyorsanız gateway.auth.mode değerini "token" olarak değiştirin.

​

Operatör kapsamları üstbilgisi

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

• Üstbilgi mevcut olduğunda, OpenClaw bildirilen kapsam kümesini uygular.
• Üstbilgi mevcut ama boş olduğunda, istek hiçbir operatör kapsamı bildirmez.
• Üstbilgi yoksa, normal kimlik taşıyan HTTP API’leri standart varsayılan operatör 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ı kaynaklı HTTP istekleri, trusted-proxy kimlik doğrulaması başarılı olduktan sonra bile gateway.controlUi.allowedOrigins denetiminden (veya bilinçli Host üstbilgisi yedek modundan) geçmelidir.
• Control UI WebSocket oturumlarında, x-openclaw-scopes yükseltme isteğinde mevcut olduğunda bir kapsam üst sınırıdır. Boş değer kapsam vermez.

​

Güvenlik kontrol listesi

• Proxy tek yoldur: Gateway bağlantı noktası, proxy’niz dışında her şeye karşı güvenlik duvarıyla kapatılmıştır.
• trustedProxies asgaridir: Tüm alt ağlar değil, yalnızca gerçek proxy IP’leriniz.
• Loopback proxy kaynağı bilinçlidir: gateway.auth.trustedProxy.allowLoopback aynı ana makinedeki bir proxy için açıkça etkinleştirilmediği sürece loopback kaynaklı isteklerde trusted-proxy kimlik doğrulaması güvenli kapalı şekilde başarısız olur.
• Proxy üstbilgileri temizler: Proxy’niz istemcilerden gelen x-forwarded-* üstbilgilerinin üzerine yazar (ekleme yapmaz).
• TLS sonlandırma: Proxy’niz TLS’yi yönetir; kullanıcılar HTTPS üzerinden bağlanır.
• allowedOrigins açıktır: Loopback dışı 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 belirteç yapılandırması yoktur: Hem gateway.auth.token hem de gateway.auth.mode: "trusted-proxy" ayarlamayın.
• Yerel parola yedeği ö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 etkinleştirilmiş allowLoopback
• Açığa çıkarılmış Control UI yüzeylerinde joker karakterli veya eksik tarayıcı kaynak ilkesi

​

Sorun giderme

​

Belirteç kimlik doğrulamasından geçiş

​

İlgili

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