Güvenilir proxy kimlik doğrulaması

​

Ne zaman kullanılmalı

• OpenClaw’ı kimlik bilgisine duyarlı bir proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + iletilen kimlik doğrulama) arkasında çalıştırıyorsanız.
• Proxy’niz tüm kimlik doğrulama işlemlerini gerçekleştiriyor ve kullanıcı kimliğini üstbilgiler 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 belirteç iletemediği için WebSocket 1008 unauthorized hataları alıyorsanız.

​

Ne zaman KULLANILMAMALI

• Proxy’niz kullanıcıların kimliğini doğrulamıyorsa (yalnızca bir 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 üstbilgileri doğru biçimde kaldırdığından/üzerine yazdığından emin değilseniz.
• Yalnızca kişisel, tek kullanıcılı erişime ihtiyacınız varsa (bunun yerine Tailscale Serve + geri döngüyü değerlendirin).

​

Nasıl çalışır

​

Yapılandırma

{
  gateway: {
    // Güvenilir proxy kimlik doğrulaması, proxy'nin kaynak IP'sinin varsayılan olarak geri döngü olmamasını bekler
    bind: "lan",

    // KRİTİK: Buraya yalnızca proxy'nizin IP adreslerini 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 üstbilgi (gerekli)
        userHeader: "x-forwarded-user",

        // İsteğe bağlı: BULUNMASI ZORUNLU üstbilgiler (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 etkinleştirildikten sonra aynı ana makinedeki geri döngü proxy'sine izin ver
        allowLoopback: false,

        // İsteğe bağlı: kimliği doğrulanmış proxy kullanıcılarının yeni tarayıcı cihazlarını kaydetmesine izin ver
        deviceAutoApprove: {
          enabled: false,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

​

Yapılandırma başvurusu

​

Otomatik cihaz onayı

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        allowUsers: ["operator@example.com"],
        deviceAutoApprove: {
          enabled: true,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

1. WebSocket, trusted-proxy yöntemi üzerinden, boş olmayan ve bir izin verilenler listesi yapılandırılmışsa allowUsers denetimini geçen bir kullanıcı kimliğiyle doğrulanmış olmalıdır. Belirteç, parola, Tailscale ve kimliği doğrulanmamış bağlantılar bu politikayı hiçbir zaman kullanmaz.
2. Yalnızca yeni bir Control UI veya WebChat tarayıcı cihazı otomatik olarak onaylanabilir. Kapsam yükseltme dahil olmak üzere mevcut bir cihaza yönelik tüm istekler, openclaw devices approve <requestId> ile elle onaylanmak üzere beklemede kalır.
3. Cihaz, operator rolüyle onaylanır. Bağlantı isteği kapsamlar içeriyorsa verilen yetki, istenen kapsamlarla deviceAutoApprove.scopes değerinin tam kesişimidir. İstekte kapsamlar belirtilmezse yapılandırılmış liste verilir; bu liste belirtilmediğinde varsayılan olarak operator.read, operator.write ve operator.approvals kullanılır. Ardından ortaya çıkan yetki, mevcut olduğunda bağlantının x-openclaw-scopes proxy üstbilgisiyle ayrıca sınırlandırılır; böylece bir kullanıcının kapsamlarını daraltan proxy yalnızca oturumu değil, kalıcı cihaz yetkisini de sınırlar; mevcut ancak boş bir üstbilgi hiçbir kapsam sağlamaz. Bu sınır, istemci kendi kapsam listesini belirtmediğinde da uygulanır.
4. operator.admin yalnızca deviceAutoApprove.scopes içinde açıkça listelenmesi yoluyla kullanılabilir. Listelendiğinde, proxy üzerinden kimliği doğrulanmış her kullanıcı yeni bir tarayıcı cihazında tam yönetici yetkisi isteyebilir ve bunu otomatik olarak alabilir; kapsamsız istekler otomatik olarak tam yönetici yetkisi alır. openclaw security audit, KRİTİK gateway.trusted_proxy_device_auto_approve_admin bulgusunu bildirir ve Gateway başlatma sırasında bir kez uyarı kaydeder. Kimlik başına roller kullanıma sunulana kadar openclaw devices approve veya openclaw devices rotate ile elle yönetici onayını tercih edin.

​

Control UI eşleştirme davranışı

• Cihazsız Control UI WebSocket oturumları bağlanır ancak varsayılan olarak hiçbir operatör kapsamı almaz. OpenClaw, istenen kapsam listesini [] olarak temizler; böylece onaylanmış eşleştirilmiş bir cihaza/belirtece bağlı olmayan bir oturum izinlerini kendisi beyan edemez.
• Başarılı bir WebSocket bağlantısından sonra yöntemler missing scope hatasıyla 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.
• Kullanımdan kaldırılmış gateway.controlUi.dangerouslyDisableDeviceAuth=true anahtarını hâlâ içeren eski yapılandırmalar, sınırlandırılmış Control UI yükseltme geçişini kullanır.

• Eşleştirme artık cihazsız Control UI erişimi için birincil geçit değildir. deviceAutoApprove.enabled doğru olduğunda proxy kimliği, yeni tarayıcı cihazı kaydı için de onay geçidi hâline gelir.
• Ters proxy kimlik doğrulama politikanız ve allowUsers etkin erişim denetimi hâline gelir.
• Gateway girişini yalnızca güvenilir proxy IP’leriyle sınırlı tutun (gateway.trustedProxies + güvenlik duvarı).

​

Operatör kapsamları üstbilgisi

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

• Üst bilgi mevcut olduğunda OpenClaw, bildirilen kapsam kümesini dikkate alır.
• Üst bilgi mevcut ancak boş olduğunda istek, hiçbir operatör kapsamı bildirmez.
• Üst bilgi olmadığında, normal kimlik taşıyan HTTP API’leri standart varsayılan operatör kapsamı kümesine geri döner (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Gateway kimlik doğrulamalı plugin HTTP rotaları varsayılan olarak daha dardır: x-openclaw-scopes olmadığında çalışma zamanı kapsamları yalnızca operator.write kapsamına geri döner.
• Tarayıcı kaynaklı HTTP istekleri, güvenilir proxy kimlik doğrulaması başarılı olduktan sonra bile gateway.controlUi.allowedOrigins denetiminden (veya bilinçli Host üst bilgisi geri dönüş modundan) geçmelidir.

​

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 rehberi

• Trafiği doğrularken önce kısa bir maksimum süreyle (örneğin max-age=300) başlayın.
• Uzun süreli değerlere (örneğin max-age=31536000) yalnızca yeterince emin olduktan sonra geçin.
• Yalnızca tüm alt alan adları HTTPS’ye hazırsa includeSubDomains ekleyin.
• Ön yüklemeyi yalnızca tüm alan adı kümeniz için ön yükleme gereksinimlerini bilinçli olarak karşılıyorsanız kullanın.
• Yalnızca geri döngüye bağlı yerel geliştirme HSTS’den fayda sağlamaz.

​

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/yardımcı 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 kapsayıcı IP'si
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

Karma token yapılandırması

• Güvenilir proxy modunu kullanırken paylaşılan tokenı kaldırın veya
• Token tabanlı kimlik doğrulamayı amaçlıyorsanız gateway.auth.mode değerini "token" olarak değiştirin.

​

Güvenlik denetim listesi

• Proxy tek yoldur: Gateway portu, proxy’niz dışındaki her şeye karşı güvenlik duvarıyla korunur.
• trustedProxies asgaridir: Tüm alt ağlar değil, yalnızca gerçek proxy IP’leriniz.
• Geri döngü proxy kaynağı bilinçli seçilmiştir: Aynı ana makinedeki bir proxy için gateway.auth.trustedProxy.allowLoopback açıkça etkinleştirilmediği sürece, güvenilir proxy kimlik doğrulaması geri döngü kaynaklı isteklerde güvenli biçimde başarısız olur.
• Proxy üst bilgileri temizler: Proxy’niz, istemcilerden gelen x-forwarded-* üst bilgilerini sona eklemek yerine üzerine yazar.
• TLS sonlandırma: Proxy’niz TLS’yi işler; kullanıcılar HTTPS üzerinden bağlanır.
• allowedOrigins açıkça belirtilmiştir: Geri döngü dışındaki Control UI, açıkça belirtilmiş gateway.controlUi.allowedOrigins kullanır.
• allowUsers ayarlanmıştır (önerilen): Kimliği doğrulanmış herkese izin vermek yerine erişimi bilinen kullanıcılarla sınırlayın.
• Karma 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 kullanmayan uzak istemcilerin doğrudan erişememesi için Gateway portunu güvenlik duvarıyla koruyun.
• Cihazın otomatik onaylanması bilinçli bir tercihtir: deviceAutoApprove.enabled true ise ters proxy hesap güvenliğini cihaz kaydı sınırı olarak değerlendirin ve verilen kapsam listesini yönetici olmayan kapsamlarla ve asgari düzeyde tutun.

​

Güvenlik denetimi

• Temel gateway.trusted_proxy_auth uyarısı/kritik hatırlatması.
• Eksik trustedProxies yapılandırması.
• Eksik userHeader yapılandırması.
• Boş allowUsers (kimliği doğrulanmış tüm kullanıcılara izin verir).
• Aynı ana makinedeki proxy kaynakları için etkinleştirilmiş allowLoopback.
• Etkinleştirilmiş tarayıcı cihazı otomatik onayı (yeni cihaz eşleştirmesini proxy kimliğine devreder).

​

Sorun giderme

​

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

​

İlgili

• Yapılandırma — yapılandırma başvurusu
• Operatör kapsamları — roller, kapsamlar ve onay denetimleri
• Uzaktan erişim — diğer uzaktan erişim kalıpları
• Güvenlik — kapsamlı güvenlik kılavuzu
• Tailscale — yalnızca tailnet erişimi için daha basit alternatif