Güvenilir proxy kimlik doğrulaması

# Ne zaman kullanılır?

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

• OpenClaw'ı kimlik farkındalığı olan bir proxy arkasında çalıştırıyorsanız (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + ileri kimlik doğrulama).
• Proxy'niz tüm kimlik doğrulamayı işliyor 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 geçiremediği için WebSocket 1008 unauthorized hataları alıyorsanız.

# Ne zaman kullanılmamalıdır?

• 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çıklıkları, dahili ağ erişimi).
• Proxy'nizin iletilen başlıkları doğru şekilde kaldırıp/ü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 seçeneğini değerlendirin).

# Nasıl çalışır?

# Control UI eşleştirme davranışı

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

Sonuçlar:

• Bu modda eşleştirme artık Control UI erişimi için birincil kapı değildir.
• Ters proxy kimlik doğrulama politikanız ve allowUsers fiili erişim denetimi haline gelir.
• Gateway girişini yalnızca güvenilir proxy IP'lerine kilitli tutun (gateway.trustedProxies + güvenlik duvarı).

# Yapılandırma

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // CRITICAL: Only add your proxy's IP(s) here
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header containing authenticated user identity (required)
        userHeader: "x-forwarded-user",

        // Optional: headers that MUST be present (proxy verification)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: restrict to specific users (empty = allow all)
        allowUsers: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# Yapılandırma başvurusu

# 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 yönergeleri

• Trafiği doğrularken önce kısa bir maksimum yaş ile başlayın (örneğin max-age=300).
• Uzun ömürlü değerlere (örneğin max-age=31536000) yalnızca güven yüksek olduğunda artırın.
• includeSubDomains değerini yalnızca her alt etki alanı HTTPS'ye hazırsa ekleyin.
• Preload'u 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 fayda sağlamaz.

# Proxy kurulum örnekleri

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium's IP
    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: [email protected]
    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ı

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 yanlış kimlik doğrulama yolunda sessizce kimlik doğrulaması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 istiyorsanız gateway.auth.mode değerini "token" olarak değiştirin.

Loopback trusted-proxy kimlik başlıkları yine kapalı şekilde başarısız olur: aynı ana makine çağıranları 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ğrulaması yapabilir. Token geri dönüşü trusted-proxy modunda bilinçli olarak desteklenmemeye devam eder.

# Operatör kapsamları başlığı

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

Ö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 bildirilen kapsam kümesini dikkate alır.
• Başlık mevcut ancak boş olduğunda istek hiçbir 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ı kapsamları operator.write kapsamına geri döner.
• Tarayıcı kökenli HTTP istekleri, trusted-proxy kimlik doğrulaması başarılı olduktan sonra bile gateway.controlUi.allowedOrigins değerinden (veya bilinçli Host başlığı geri dönüş modundan) geçmek zorundadır.

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 ihtiyacı olduğunda x-openclaw-scopes değerini açıkça gönderin.

# Güvenlik denetim 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 minimumdur: Tüm alt ağlar değil, yalnızca gerçek proxy IP'leriniz.
• [ ] Loopback proxy kaynağı bilinçlidir: trusted-proxy kimlik doğrulaması, aynı ana makinedeki bir proxy için gateway.auth.trustedProxy.allowLoopback açıkça etkinleştirilmedikçe loopback kaynaklı isteklerde kapalı kalacak şekilde başarısız olur.
• [ ] Proxy başlıkları temizler: Proxy'niz istemcilerden gelen x-forwarded-* başlıklarının üzerine yazar, ekleme yapmaz.
• [ ] TLS sonlandırması: Proxy'niz TLS'i işler; kullanıcılar HTTPS üzerinden bağlanır.
• [ ] allowedOrigins açıktır: Loopback olmayan 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 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 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ı kritik önem derecesine sahip bir bulgu olarak işaretler. Bu bilinçli bir davranıştı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ış herhangi bir kullanıcıya izin verir)
• Aynı ana makine proxy kaynakları için etkin allowLoopback
• Açığa çıkarılmış Control UI yüzeylerinde joker karakterli veya eksik tarayıcı kaynak politikası

# Sorun giderme

# Token kimlik doğrulamasından geçiş

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

# İlgili

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