विश्वसनीय प्रॉक्सी प्रमाणीकरण

​

कब उपयोग करें

• आप OpenClaw को किसी identity-aware proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth) के पीछे चलाते हैं।
• आपका proxy पूरा प्रमाणीकरण संभालता है और headers के जरिए user identity पास करता है।
• आप Kubernetes या container परिवेश में हैं जहां proxy ही Gateway तक पहुंचने का एकमात्र रास्ता है।
• आपको WebSocket 1008 unauthorized त्रुटियां मिल रही हैं क्योंकि browsers WS payloads में tokens पास नहीं कर सकते।

​

कब उपयोग न करें

• यदि आपका proxy users को authenticate नहीं करता (सिर्फ TLS terminator या load balancer है)।
• यदि Gateway तक कोई ऐसा रास्ता है जो proxy को bypass करता है (firewall holes, internal network access)।
• यदि आप सुनिश्चित नहीं हैं कि आपका proxy forwarded headers को सही तरह strip/overwrite करता है या नहीं।
• यदि आपको केवल व्यक्तिगत single-user access चाहिए (सरल setup के लिए Tailscale Serve + loopback पर विचार करें)।

​

यह कैसे काम करता है

​

Control UI pairing व्यवहार

• Device-less Control UI WebSocket sessions connect करते हैं लेकिन default रूप से कोई operator scopes प्राप्त नहीं करते। OpenClaw requested scope list को [] पर clear कर देता है ताकि ऐसा session जो approved paired device/token से bound नहीं है, permissions self-declare न कर सके।
• यदि सफल WebSocket connect के बाद methods missing scope के साथ fail हों, तो HTTPS का उपयोग करें ताकि browser device identity generate कर सके और pairing complete कर सके। देखें Control UI insecure HTTP।
• केवल break-glass: gateway.controlUi.dangerouslyDisableDeviceAuth=true device identity के बिना भी requested scopes को preserve करता है। यह गंभीर security downgrade है; जल्दी revert करें। देखें Control UI insecure HTTP।

• यदि आपका proxy Control UI WebSocket upgrade request पर x-openclaw-scopes भेजता है, तो OpenClaw session scopes को requested scopes और declared scopes के intersection तक cap करता है। यह header scopes grant नहीं करता; यह केवल session द्वारा रखे जा सकने वाले scopes को narrow करता है।

• इस mode में Control UI access के लिए pairing अब primary gate नहीं है।
• आपकी reverse proxy auth policy और allowUsers effective access control बन जाते हैं।
• gateway ingress को केवल trusted proxy IPs तक locked रखें (gateway.trustedProxies + firewall)।

​

कॉन्फ़िगरेशन

{
  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: ["nick@example.com", "admin@company.org"],

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

​

कॉन्फ़िगरेशन संदर्भ

​

TLS termination और HSTS

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

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

​

Rollout मार्गदर्शन

• Traffic validate करते समय पहले short max age से start करें (उदाहरण के लिए max-age=300)।
• केवल confidence high होने के बाद long-lived values तक बढ़ाएं (उदाहरण के लिए max-age=31536000)।
• includeSubDomains केवल तब add करें जब हर subdomain HTTPS-ready हो।
• Preload का उपयोग केवल तब करें जब आप अपने full domain set के लिए जानबूझकर preload requirements पूरी करते हों।
• Loopback-only local development को HSTS से लाभ नहीं होता।

​

Proxy setup examples

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

​

Mixed token configuration

• Trusted-proxy mode का उपयोग करते समय shared token remove करें, या
• यदि आप token-based auth चाहते हैं तो gateway.auth.mode को "token" पर switch करें।

​

ऑपरेटर स्कोप हेडर

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

• जब हेडर मौजूद होता है, OpenClaw घोषित स्कोप सेट का सम्मान करता है।
• जब हेडर मौजूद होता है लेकिन खाली होता है, अनुरोध कोई ऑपरेटर स्कोप घोषित नहीं करता।
• जब हेडर अनुपस्थित होता है, सामान्य पहचान-वहन करने वाले HTTP API मानक ऑपरेटर डिफ़ॉल्ट स्कोप सेट पर वापस जाते हैं।
• Gateway-प्रमाणीकरण plugin HTTP रूट डिफ़ॉल्ट रूप से अधिक संकरे हैं: जब x-openclaw-scopes अनुपस्थित होता है, उनका रनटाइम स्कोप operator.write पर वापस जाता है।
• ब्राउज़र-मूल HTTP अनुरोधों को विश्वसनीय-प्रॉक्सी प्रमाणीकरण सफल होने के बाद भी gateway.controlUi.allowedOrigins (या जानबूझकर Host-हेडर फ़ॉलबैक मोड) पास करना होता है।
• Control UI WebSocket सत्रों के लिए, अपग्रेड अनुरोध पर मौजूद होने पर x-openclaw-scopes एक स्कोप सीमा है। खाली मान से कोई स्कोप नहीं मिलता।

​

सुरक्षा चेकलिस्ट

• प्रॉक्सी ही एकमात्र पथ है: Gateway पोर्ट आपके प्रॉक्सी के अलावा हर चीज़ से फ़ायरवॉल किया गया है।
• trustedProxies न्यूनतम है: केवल आपके वास्तविक प्रॉक्सी IP, पूरे सबनेट नहीं।
• Loopback प्रॉक्सी स्रोत जानबूझकर है: loopback-स्रोत अनुरोधों के लिए विश्वसनीय-प्रॉक्सी प्रमाणीकरण बंद-रूप में विफल होता है, जब तक कि समान-होस्ट प्रॉक्सी के लिए gateway.auth.trustedProxy.allowLoopback स्पष्ट रूप से सक्षम न हो।
• प्रॉक्सी हेडर हटाता है: आपका प्रॉक्सी क्लाइंट से आने वाले x-forwarded-* हेडर को ओवरराइट करता है (जोड़ता नहीं)।
• TLS समाप्ति: आपका प्रॉक्सी TLS संभालता है; उपयोगकर्ता HTTPS से कनेक्ट करते हैं।
• allowedOrigins स्पष्ट है: non-loopback Control UI स्पष्ट gateway.controlUi.allowedOrigins का उपयोग करता है।
• allowUsers सेट है (अनुशंसित): किसी भी प्रमाणित व्यक्ति को अनुमति देने के बजाय ज्ञात उपयोगकर्ताओं तक सीमित करें।
• मिश्रित टोकन कॉन्फ़िग नहीं है: gateway.auth.token और gateway.auth.mode: "trusted-proxy" दोनों सेट न करें।
• स्थानीय पासवर्ड फ़ॉलबैक निजी है: यदि आप आंतरिक प्रत्यक्ष कॉलरों के लिए gateway.auth.password कॉन्फ़िगर करते हैं, तो Gateway पोर्ट को फ़ायरवॉल रखें ताकि non-proxy रिमोट क्लाइंट सीधे उस तक न पहुंच सकें।

​

सुरक्षा ऑडिट

• आधार gateway.trusted_proxy_auth चेतावनी/critical रिमाइंडर
• अनुपस्थित trustedProxies कॉन्फ़िगरेशन
• अनुपस्थित userHeader कॉन्फ़िगरेशन
• खाली allowUsers (किसी भी प्रमाणित उपयोगकर्ता को अनुमति देता है)
• समान-होस्ट प्रॉक्सी स्रोतों के लिए सक्षम allowLoopback
• उजागर Control UI सतहों पर वाइल्डकार्ड या अनुपस्थित ब्राउज़र-मूल नीति

​

समस्या निवारण

​

टोकन प्रमाणीकरण से माइग्रेशन

​

संबंधित

• कॉन्फ़िगरेशन — कॉन्फ़िग संदर्भ
• रिमोट एक्सेस — अन्य रिमोट एक्सेस पैटर्न
• सुरक्षा — पूर्ण सुरक्षा गाइड
• Tailscale — केवल-tailnet एक्सेस के लिए सरल विकल्प