Güvenilir proxy kimlik doğrulaması

Ne zaman kullanılmalı

• OpenClaw'u kimlik bilgisine duyarlı bir proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + ileri kimlik doğrulama) arkasında çalıştırıyorsunuz.
• Proxy'niz tüm kimlik doğrulama işlemlerini gerçekleştiriyor ve kullanıcı kimliğini başlıklar aracılığıyla iletiyor.
• Proxy'nin Gateway'e giden tek yol olduğu bir Kubernetes veya konteyner ortamındasınız.
• Tarayıcılar WS yüklerinde belirteç iletemediği için WebSocket 1008 unauthorized hataları alıyorsunuz.

Ne zaman KULLANILMAMALI

• Proxy'niz kullanıcıların kimliğini doğrulamıyor (yalnızca TLS sonlandırıcı veya yük dengeleyici olarak çalışıyor).
• Gateway'e proxy'yi atlayan herhangi bir yol var (güvenlik duvarı açıklıkları, dahili ağ erişimi).
• Proxy'nizin iletilen başlıkları doğru şekilde kaldırdığından veya üzerine yazdığından emin değilsiniz.
• Yalnızca kişisel, tek kullanıcılı erişime ihtiyacınız var (bunun yerine Tailscale Serve + local loopback kullanmayı değerlendirin).

Nasıl çalışır

Yapılandırma

{  gateway: {    // Güvenilir proxy kimlik doğrulaması, varsayılan olarak proxy'nin kaynak IP'sinin loopback 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 başlık (zorunlu)        userHeader: "x-forwarded-user",         // İsteğe bağlı: MUTLAKA bulunması gereken 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 etkinleştirildikten sonra aynı ana makinedeki loopback proxy'ye izin ver        allowLoopback: false,      },    },  },}

Yapılandırma başvurusu

Control UI eşleştirme davranışı

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

Kapsamla ilgili sonuçlar:

• Cihazsız Control UI WebSocket oturumları bağlanır ancak varsayılan olarak hiçbir operatör kapsamı almaz. OpenClaw, onaylı ve eşleştirilmiş bir cihaza/birtece bağlı olmayan oturumun kendi izinlerini beyan edememesi için istenen kapsam listesini [] olarak temizler.
• 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.
• Yalnızca acil durum için: gateway.controlUi.dangerouslyDisableDeviceAuth=true, cihaz kimliği olmadığında bile istenen kapsamları korur. Bu, güvenliği ciddi ölçüde düşürür; değişikliği hızla geri alın. Bkz. Control UI güvenli olmayan HTTP.

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 başlık kapsam vermez; yalnızca oturumun sahip olabileceği kapsamları daraltır.

Sonuçlar:

• Bu modda eşleştirme artık Control UI erişiminin birincil denetimi değildir.
• 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'lerine açık tutun (gateway.trustedProxies + güvenlik duvarı).

Özel WebSocket istemcileri Control UI oturumları değildir. gateway.controlUi.dangerouslyDisableDeviceAuth, rastgele client.mode: "backend" veya CLI biçimli istemcilere kapsam vermez. Özel otomasyon; cihaz kimliği/eşleştirme, ayrılmış doğrudan yerel client.id: "gateway-client" arka uç yardımcı yolu veya HTTP istek/yanıt yüzeyi daha uygunsa yönetici HTTP RPC plugin'i kullanmalıdır.

Operatör kapsamları başlığı

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

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, kapsam vermek yerine yalnızca anlaşmayla belirlenen oturum kapsamlarını sınırlar. 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ış:

• Başlık mevcut olduğunda OpenClaw, beyan edilen kapsam kümesini dikkate alır.
• Başlık mevcut ancak boş olduğunda istek hiçbir operatör kapsamı beyan etmez.
• Başlık bulunmadığında, kimlik taşıyan normal 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 bulunmadığı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ı olsa bile gateway.controlUi.allowedOrigins denetiminden (veya bilinçli olarak seçilmiş Host başlığı geri dönüş modundan) geçmelidir.

Pratik kural: 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 kapsama ihtiyaç duyduğunda x-openclaw-scopes başlığını 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 azami süreyle başlayın (örneğin max-age=300).
• Yalnızca yeterli güven oluştuğunda uzun süreli değerlere (örneğin max-age=31536000) yükseltin.
• includeSubDomains seçeneğini yalnızca tüm alt etki alanları HTTPS'ye hazırsa ekleyin.
• Ön yüklemeyi yalnızca tüm etki alanı kümeniz için ön yükleme gereksinimlerini bilinçli olarak karşılıyorsanız kullanın.
• Yalnızca loopback kullanan 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/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ı

Paylaşılan bir token da yapılandırılmışsa (gateway.auth.token veya OPENCLAW_GATEWAY_TOKEN), Gateway başlatılırken güvenilen proxy kimlik doğrulaması reddedilir. Bu ikisi birbirini dışlar; çünkü paylaşılan bir token, aynı 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şlatma işlemi gateway auth mode is trusted-proxy, but a shared token is also configured benzeri bir hatayla başarısız olursa:

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

local loopback güvenilen proxy kimlik başlıkları yine güvenli biçimde reddedilir: aynı makinedeki çağıranların kimliği sessizce proxy kullanıcısı olarak doğrulanmaz. Proxy'yi atlayan dahili OpenClaw çağıranları bunun yerine gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD ile kimlik doğrulayabilir. Token'a geri dönüş, güvenilen proxy modunda kasıtlı olarak desteklenmez.

Güvenlik kontrol listesi

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

• [ ] Proxy tek erişim yoludur: Gateway portu, proxy'niz dışındaki her şeye karşı güvenlik duvarıyla korunur.
• [ ] trustedProxies asgari düzeydedir: Tüm alt ağlar değil, yalnızca gerçek proxy IP'leriniz belirtilir.
• [ ] local loopback proxy kaynağı bilinçli olarak seçilmiştir: Aynı makinedeki bir proxy için gateway.auth.trustedProxy.allowLoopback açıkça etkinleştirilmediği sürece, güvenilen proxy kimlik doğrulaması local loopback kaynaklı istekleri güvenli biçimde reddeder.
• [ ] Proxy başlıkları kaldırır: Proxy'niz istemcilerden gelen x-forwarded-* başlıklarının üzerine yazar; bunlara ekleme yapmaz.
• [ ] TLS sonlandırma: TLS işlemlerini proxy'niz yürütür; kullanıcılar HTTPS üzerinden bağlanır.
• [ ] allowedOrigins açıkça belirtilmiştir: local loopback dışındaki Denetim Arayüzü, açıkça belirtilmiş gateway.controlUi.allowedOrigins kullanır.
• [ ] allowUsers ayarlanmıştır (önerilir): Kimliği doğrulanmış herkese izin vermek yerine erişimi bilinen kullanıcılarla sınırlandırı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: Doğrudan bağlanan dahili çağıranlar için gateway.auth.password yapılandırırsanız, proxy dışındaki uzak istemcilerin Gateway portuna doğrudan erişememesi için portu güvenlik duvarıyla koruyun.

Güvenlik denetimi

openclaw security audit, güvenilen proxy kimlik doğrulamasını kritik önem derecesine sahip bir bulgu olarak işaretler. Bu kasıtlıdır; güvenliği proxy kurulumunuza devrettiğinizi hatırlatır.

Denetim şunları kontrol eder:

• 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ış tüm kullanıcılara izin verir).
• Aynı makinedeki proxy kaynakları için etkinleştirilmiş allowLoopback.

Denetim Arayüzü kullanıma açıldığında, güvenilen proxy'ye özgü olmayan ayrı bulgular da geçerlidir: joker karakterli veya eksik gateway.controlUi.allowedOrigins ve Host başlığı kaynak geri dönüşü.

Sorun giderme

Token kimlik doğrulamasından geçiş

İlgili konular

• Yapılandırma — yapılandırma başvurusu
• Operatör kapsamları — roller, kapsamlar ve onay denetimleri
• Uzak erişim — diğer uzak erişim yöntemleri
• Güvenlik — eksiksiz güvenlik kılavuzu
• Tailscale — yalnızca tailnet erişimi için daha basit bir alternatif