Güvenilir proxy kimlik doğrulaması

Ne zaman kullanılmalı

trusted-proxy kimlik doğrulama modunu şu durumlarda kullanın:

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

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

Kapsam etkileri:

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

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 kapsamlar ile beyan edilen kapsamların kesişimiyle sınırlar. Bu başlık kapsam vermez; yalnızca oturumun sahip olabileceklerini daraltır.

Etkiler:

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

Ö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" backend yardımcı yolu veya HTTP istek/yanıt yüzeyi daha uygunsa admin HTTP RPC plugin kullanmalıdır.

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

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

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ı

OpenClaw, hem gateway.auth.token (veya OPENCLAW_GATEWAY_TOKEN) hem de trusted-proxy modunun aynı anda etkin olduğu belirsiz yapılandırmaları reddeder. Karma token yapılandırmaları, loopback isteklerinin sessizce yanlış kimlik doğrulama yolunda doğrulanmasına neden olabilir.

Başlangıçta mixed_trusted_proxy_token hatası görürseniz:

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

Loopback trusted-proxy kimlik üstbilgileri hâlâ güvenli kapalı şekilde başarısız olur: aynı ana makinedeki çağıranlar sessizce proxy kullanıcıları olarak kimlik doğrulamasından geçirilmez. Proxy'yi atlayan dahili OpenClaw çağıranları bunun yerine gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD ile kimlik doğrulayabilir. Belirteç yedeği trusted-proxy modunda kasıtlı olarak desteklenmemeye devam eder.

Operatör kapsamları üstbilgisi

Trusted-proxy kimlik doğrulaması kimlik taşıyan bir HTTP modudur, bu yüzden çağıranlar HTTP API isteklerinde isteğe bağlı olarak x-openclaw-scopes ile 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 yalnızca görüşülen oturum kapsamları için bir üst sınırdır, bir yetki vermez. trusted-proxy ile WebSocket kapsam davranışı için 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ış:

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

Pratik kural: Bir trusted-proxy isteğinin varsayılanlardan daha dar olmasını istediğinizde veya gateway kimlik doğrulamalı bir plugin rotasının yazma kapsamından daha güçlü bir şeye ihtiyaç duyduğunda x-openclaw-scopes değerini açıkça gönderin.

Güvenlik kontrol listesi

trusted-proxy kimlik doğrulamasını etkinleştirmeden önce şunları doğrulayın:

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

openclaw security audit, trusted-proxy kimlik doğrulamasını critical önem derecesinde bir bulgu olarak işaretler. Bu kasıtlıdır — güvenliği proxy kurulumunuza devrettiğinize dair bir hatırlatmadı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ış 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ş

Belirteç kimlik doğrulamasından trusted-proxy'ye geçiyorsanız:

İ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