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

कब उपयोग करें

trusted-proxy auth मोड का उपयोग तब करें जब:

• आप 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 व्यवहार

जब gateway.auth.mode = "trusted-proxy" सक्रिय हो और request trusted-proxy checks पास कर ले, तो Control UI WebSocket sessions device pairing identity के बिना connect कर सकते हैं।

Scope implications:

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

Reverse-proxy scope capping:

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

Implications:

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

Custom WebSocket clients Control UI sessions नहीं हैं। gateway.controlUi.dangerouslyDisableDeviceAuth arbitrary client.mode: "backend" या CLI-shaped clients को scopes grant नहीं करता। Custom automation को device identity/pairing, reserved direct-local client.id: "gateway-client" backend helper path, या admin HTTP RPC plugin का उपयोग करना चाहिए जब HTTP request/response surface बेहतर fit हो।

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

{  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

एक TLS termination point का उपयोग करें और HSTS वहीं apply करें।

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

OpenClaw ऐसी ambiguous configurations को reject करता है जहां gateway.auth.token (या OPENCLAW_GATEWAY_TOKEN) और trusted-proxy mode दोनों एक साथ active हों। Mixed token configs loopback requests को गलत auth path पर चुपचाप authenticate करा सकते हैं।

यदि startup पर आपको mixed_trusted_proxy_token error दिखे:

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

Loopback विश्वसनीय-प्रॉक्सी पहचान हेडर अब भी बंद-रूप में विफल होते हैं: समान-होस्ट कॉलर को चुपचाप प्रॉक्सी उपयोगकर्ताओं के रूप में प्रमाणित नहीं किया जाता। आंतरिक OpenClaw कॉलर जो प्रॉक्सी को बायपास करते हैं, इसके बजाय gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD से प्रमाणित हो सकते हैं। विश्वसनीय-प्रॉक्सी मोड में टोकन फ़ॉलबैक जानबूझकर असमर्थित रहता है।

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

विश्वसनीय-प्रॉक्सी प्रमाणीकरण एक पहचान-वहन करने वाला HTTP मोड है, इसलिए कॉलर HTTP API अनुरोधों पर x-openclaw-scopes के साथ वैकल्पिक रूप से ऑपरेटर स्कोप घोषित कर सकते हैं।

ध्यान दें: WebSocket स्कोप Gateway प्रोटोकॉल हैंडशेक और डिवाइस पहचान बाइंडिंग से निर्धारित होते हैं। Control UI WebSocket अपग्रेड अनुरोधों पर, x-openclaw-scopes केवल सहमति प्राप्त सत्र स्कोप पर एक सीमा है, अनुदान नहीं। विश्वसनीय-प्रॉक्सी के साथ WebSocket स्कोप व्यवहार के लिए, Control UI पेयरिंग व्यवहार देखें।

उदाहरण:

• 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-auth plugin रूट को write स्कोप से अधिक मजबूत कुछ चाहिए, तब 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 रिमोट क्लाइंट सीधे उस तक न पहुंच सकें।

सुरक्षा ऑडिट

openclaw security audit विश्वसनीय-प्रॉक्सी प्रमाणीकरण को critical गंभीरता वाली खोज के साथ फ़्लैग करेगा। यह जानबूझकर है — यह याद दिलाता है कि आप सुरक्षा को अपनी प्रॉक्सी सेटअप को सौंप रहे हैं।

ऑडिट इनकी जांच करता है:

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

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

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

यदि आप टोकन प्रमाणीकरण से विश्वसनीय-प्रॉक्सी पर जा रहे हैं:

संबंधित

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