​

Trusted Proxy Auth

⚠️ Güvenliğe duyarlı özellik. Bu mod kimlik doğrulamayı tamamen ters proxy’nize devreder. Yanlış yapılandırma, Gateway’inizi yetkisiz erişime açabilir. Etkinleştirmeden önce bu sayfayı dikkatlice okuyun.

​

Ne zaman kullanılmalı

• OpenClaw’ı kimlik farkında bir proxy’nin arkasında çalıştırıyorsunuz (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
• Proxy’niz tüm kimlik doğrulamayı yapıyor ve kullanıcı kimliğini başlıklar üzerinden iletiyor
• Proxy’nin Gateway’e giden tek yol olduğu bir Kubernetes veya kapsayıcı ortamındasınız
• Tarayıcılar WS yüklerinde token iletemediği için WebSocket 1008 unauthorized hataları alıyorsunuz

​

Ne zaman KULLANILMAMALI

• Proxy’niz kullanıcıların kimliğini doğrulamıyorsa (yalnızca bir TLS sonlandırıcı veya yük dengeleyici ise)
• Gateway’e proxy’yi atlayan herhangi bir yol varsa (güvenlik duvarı boşlukları, iç ağ erişimi)
• Proxy’nizin iletilen başlıkları doğru şekilde sıyırdığından/üzerine yazdığı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 değerlendirin)

​

Nasıl çalışır

1. Ters proxy’niz kullanıcıların kimliğini doğrular (OAuth, OIDC, SAML vb.)
2. Proxy doğrulanmış kullanıcı kimliğini içeren bir başlık ekler (ör. x-forwarded-user: nick@example.com)
3. OpenClaw isteğin güvenilen bir proxy IP’sinden geldiğini denetler (gateway.trustedProxies içinde yapılandırılır)
4. OpenClaw kullanıcı kimliğini yapılandırılmış başlıktan çıkarır
5. Her şey uygunsa isteğe yetki verilir

​

Kontrol UI eşleme davranışı

• Bu modda Kontrol UI erişimi için eşleme artık birincil geçit değildir.
• Etkili erişim denetimi ters proxy kimlik doğrulama ilkeniz ve allowUsers olur.
• Gateway girişini yalnızca güvenilen proxy IP’lerine kilitli tutun (gateway.trustedProxies + güvenlik duvarı).

​

Yapılandırma

{
  gateway: {
    // Trusted-proxy kimlik doğrulaması, loopback olmayan güvenilen bir proxy kaynağından gelen istekleri bekler
    bind: "lan",

    // KRİTİK: Buraya yalnızca proxy'nizin IP(ler)ini ekleyin
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

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

        // İsteğe bağlı: MUTLAKA mevcut olması 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"],
      },
    },
  },
}

• Trusted-proxy kimlik doğrulaması, loopback kaynaklı istekleri (127.0.0.1, ::1, loopback CIDR’leri) reddeder.
• Aynı host üzerindeki loopback ters proxy’ler trusted-proxy kimlik doğrulamasını karşılamaz.
• Aynı host üzerindeki loopback proxy kurulumları için bunun yerine token/parola kimlik doğrulaması kullanın veya OpenClaw’ın doğrulayabileceği loopback olmayan güvenilen bir proxy adresi üzerinden yönlendirin.
• Loopback olmayan Kontrol UI dağıtımları yine de açık gateway.controlUi.allowedOrigins gerektirir.

​

Yapılandırma başvurusu

​

TLS sonlandırma ve HSTS

​

Önerilen desen: proxy TLS sonlandırma

• İnternete açık dağıtımlar için uygundur.
• Sertifika + HTTP güçlendirme ilkesini tek yerde tutar.
• OpenClaw, proxy arkasında loopback HTTP üzerinde kalabilir.

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

​

Gateway TLS sonlandırma

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

​

Kullanıma alma kılavuzu

• Trafiği doğrularken önce kısa bir max age ile başlayın (örneğin max-age=300).
• Güven yüksek olduktan sonra uzun ömürlü değerlere yükseltin (örneğin max-age=31536000).
• includeSubDomains yalnızca her alt alan HTTPS için hazırsa eklenmelidir.
• preload yalnızca tüm alan adınız için preload gereksinimlerini kasıtlı olarak karşılıyorsanız kullanılmalıdır.
• Yalnızca loopback kullanan yerel geliştirme HSTS’den fayda görmez.

​

Proxy kurulum örnekleri

​

Pomerium

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium 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

​

OAuth ile Caddy

{
  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}
    }
}

​

nginx + oauth2-proxy

{
  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";
}

​

Forward Auth ile Traefik

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

• trusted-proxy modunu kullanırken paylaşılan token’ı kaldırın veya
• token tabanlı kimlik doğrulama istiyorsanız gateway.auth.mode değerini "token" yapın

​

Operatör kapsamları başlığı

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

• Başlık mevcut olduğunda, OpenClaw bildirilen kapsam kümesini dikkate alır.
• Başlık mevcut ama boş olduğunda, istek hiç operatör kapsamı bildirmez.
• Başlık yoksa, normal kimlik taşıyan HTTP API’leri standart operatör varsayılan 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ı kapsamı operator.write değerine geri döner.
• Tarayıcı kaynaklı HTTP istekleri, trusted-proxy kimlik doğrulaması başarılı olduktan sonra bile gateway.controlUi.allowedOrigins (veya bilinçli Host-header fallback modu) denetimini geçmek zorundadır.

• Bir trusted-proxy isteğinin varsayılanlardan daha dar olmasını istediğinizde veya bir gateway-auth plugin rotası için write kapsamından daha güçlü bir şey gerektiğinde x-openclaw-scopes başlığını açıkça gönderin.

​

Güvenlik kontrol listesi

• Proxy tek yoldur: Gateway portu, proxy’niz dışındaki her şeye karşı güvenlik duvarıyla kapalıdır
• trustedProxies minimaldir: tüm alt ağlar değil, yalnızca gerçek proxy IP’leriniz
• Loopback proxy kaynağı yoktur: trusted-proxy kimlik doğrulaması loopback kaynaklı isteklerde güvenli şekilde kapanır
• Proxy başlıkları sıyırır: proxy’niz istemcilerden gelen x-forwarded-* başlıklarının üzerine yazar (sona eklemez)
• TLS sonlandırma: proxy’niz TLS’yi işler; kullanıcılar HTTPS üzerinden bağlanır
• allowedOrigins açıktır: loopback olmayan Kontrol 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
• Karma token yapılandırması yoktur: hem gateway.auth.token hem gateway.auth.mode: "trusted-proxy" ayarlamayın

​

Güvenlik denetimi

• Temel gateway.trusted_proxy_auth warning/critical hatırlatıcısı
• Eksik trustedProxies yapılandırması
• Eksik userHeader yapılandırması
• Boş allowUsers (kimliği doğrulanmış her kullanıcıya izin verir)
• Açığa çıkarılmış Kontrol UI yüzeylerinde joker veya eksik tarayıcı kaynak ilkesi

​

Sorun giderme

​

”trusted_proxy_untrusted_source”

• Proxy IP’si doğru mu? (Docker kapsayıcı IP’leri değişebilir)
• Proxy’nizin önünde bir yük dengeleyici var mı?
• Gerçek IP’leri bulmak için docker inspect veya kubectl get pods -o wide kullanın

​

”trusted_proxy_loopback_source”

• Proxy 127.0.0.1 / ::1 üzerinden mi bağlanıyor?
• trusted-proxy kimlik doğrulamasını aynı host üzerindeki bir loopback ters proxy ile kullanmaya mı çalışıyorsunuz?

• Aynı host üzerindeki loopback proxy kurulumları için token/parola kimlik doğrulaması kullanın veya
• Loopback olmayan güvenilen bir proxy adresi üzerinden yönlendirin ve bu IP’yi gateway.trustedProxies içinde tutun.

​

”trusted_proxy_user_missing”

• Proxy’niz kimlik başlıklarını iletecek şekilde yapılandırılmış mı?
• Başlık adı doğru mu? (büyük/küçük harf duyarsızdır ama yazım önemlidir)
• Kullanıcı gerçekten proxy üzerinde kimliği doğrulanmış mı?

​

“trustedproxy_missing_header*”

• Bu belirli başlıklar için proxy yapılandırmanız
• Başlıkların zincirin bir yerinde sıyrılıp sıyrılmadığı

​

”trusted_proxy_user_not_allowed”

​

”trusted_proxy_origin_not_allowed”

• gateway.controlUi.allowedOrigins, tam tarayıcı kaynağını içeriyor mu
• Bilerek herkese izin verme davranışı istemiyorsanız joker kaynaklara güvenmiyor olmanız
• Bilerek Host-header fallback modu kullanıyorsanız gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true değerinin açıkça ayarlanmış olması

​

WebSocket hâlâ başarısız oluyor

• WebSocket yükseltmelerini desteklemesi (Upgrade: websocket, Connection: upgrade)
• Kimlik başlıklarını WebSocket yükseltme isteklerinde de iletmesi (yalnızca HTTP’de değil)
• WebSocket bağlantıları için ayrı bir kimlik doğrulama yoluna sahip olmaması

​

Token kimlik doğrulamasından geçiş

1. Proxy’nizi kullanıcı kimliği doğrulayacak ve başlıkları iletecek şekilde yapılandırın
2. Proxy kurulumunu bağımsız olarak test edin (başlıklarla curl)
3. OpenClaw yapılandırmasını trusted-proxy kimlik doğrulamasıyla güncelleyin
4. Gateway’i yeniden başlatın
5. Kontrol UI’dan WebSocket bağlantılarını test edin
6. openclaw security audit çalıştırın ve bulguları gözden geçirin

​

İlgili

• Security — tam güvenlik kılavuzu
• Configuration — yapılandırma başvurusu
• Remote Access — diğer uzak erişim kalıpları
• Tailscale — yalnızca tailnet erişimi için daha basit alternatif