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ı

Güvenilir proxy kimlik doğrulaması, isteğe bağlı olarak proxy kimliğini yeni tarayıcı cihazlarının onay sınırı olarak kullanabilir:

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

Varsayılan değer enabled: false. Etkinleştirildiğinde şu kuralların tümü geçerlidir:

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ışı

gateway.auth.mode = "trusted-proxy" etkin olduğunda ve istek güvenilir proxy denetimlerini geçtiğinde, Control UI WebSocket oturumları cihaz eşleştirme kimliği olmadan bağlanabilir.

Kapsam sonuçları:

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

Ters proxy kapsam sınırlaması: Proxy'niz Control UI WebSocket yükseltme isteğinde x-openclaw-scopes gönderirse OpenClaw, oturum kapsamlarını istenen kapsamlarla beyan edilen kapsamların kesişimiyle sınırlar. Bu üstbilgi kapsam vermez; yalnızca oturumun sahip olabileceği kapsamları daraltır. deviceAutoApprove.enabled doğru olduğunda aynı sınır, otomatik cihaz onayı tarafından yazılan kalıcı cihaz yetkisine de uygulanır; böylece otomatik olarak onaylanan bir cihaz hiçbir zaman proxy'nin beyan ettiğinden daha fazla kapsama sahip olmaz.

Sonuçlar:

• 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ı).

Özel WebSocket istemcileri Control UI oturumları değildir. Kullanımdan kaldırılmış Control UI yükseltme girdisi, isteğe bağlı client.mode: "backend" veya CLI biçimli istemcilere geçici erişim sağlamaz. Özel otomasyon; cihaz kimliğini/eşleştirmeyi, ayrılmış doğrudan yerel client.id: "gateway-client" arka uç yardımcı yolunu veya bir HTTP istek/yanıt yüzeyi daha uygunsa yönetici HTTP RPC Plugin'ini kullanmalıdır.

Operatör kapsamları üstbilgisi

Güvenilir proxy kimlik doğrulaması, kimlik taşıyan bir HTTP modudur; bu nedenle çağıranlar, HTTP API isteklerinde x-openclaw-scopes ile isteğe bağlı olarak operatör kapsamları bildirebilir.

Not: WebSocket kapsamları, Gateway protokolü el sıkışması ve cihaz kimliği bağlaması tarafından belirlenir. Control UI WebSocket yükseltme isteklerinde x-openclaw-scopes, bir yetki verme değil, yalnızca üzerinde uzlaşılan oturum kapsamlarına uygulanan bir üst sınırdır. Bkz. Control UI eşleştirme davranışı.

Örnekler:

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

Davranış:

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

Pratik kural: Bir güvenilir proxy isteğinin varsayılanlardan daha dar olmasını istediğinizde veya Gateway kimlik doğrulamalı bir plugin rotası yazma kapsamından daha güçlü bir kapsam gerektirdiğinde x-openclaw-scopes değerini açıkça gönderin.

TLS sonlandırma ve HSTS

Tek bir TLS sonlandırma noktası kullanın ve HSTS'yi orada uygulayın.

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ı

Paylaşılan bir token da yapılandırılmışsa (gateway.auth.token veya OPENCLAW_GATEWAY_TOKEN), Gateway başlangıcı güvenilir proxy kimlik doğrulamasını reddeder. Bu ikisi birbirini dışlar; çünkü paylaşılan bir token, aynı ana makinedeki çağıranların bu modun zorunlu kılmayı amaçladığı proxy tarafından doğrulanmış kimlikten tamamen farklı bir yolla kimlik doğrulamasına olanak tanır.

Başlangıç gateway auth mode is trusted-proxy, but a shared token is also configured benzeri bir hatayla başarısız olursa:

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

Geri döngü güvenilir proxy kimlik üst bilgileri yine güvenli biçimde başarısız olur: aynı ana makinedeki çağıranların kimliği sessizce proxy kullanıcıları olarak doğrulanmaz. Proxy'yi atlayan dahili OpenClaw çağıranları bunun yerine gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD ile kimlik doğrulayabilir. Token geri dönüşü, güvenilir proxy modunda bilinçli olarak desteklenmez.

Güvenlik denetim listesi

Güvenilir proxy kimlik doğrulamasını etkinleştirmeden önce şunları doğrulayın:

• [ ] 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

openclaw security audit, güvenilir proxy kimlik doğrulamasını kritik önem derecesine sahip bir bulgu olarak işaretler. Bu bilinçli bir tercihtir; güvenliği proxy kurulumunuza devrettiğinizi hatırlatır.

Denetim şunları kontrol eder:

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

Control UI kullanıma açıldığında, güvenilir proxy'ye özgü olmayan ayrı bulgular da geçerlidir: joker karakterli veya eksik gateway.controlUi.allowedOrigins ve Host üst bilgisi kaynak geri dönüşü.

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