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

कब उपयोग करें

• आप OpenClaw को किसी पहचान-जागरूक प्रॉक्सी (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth) के पीछे चलाते हैं।
• आपका प्रॉक्सी सभी प्रमाणीकरण संभालता है और हेडर के माध्यम से उपयोगकर्ता की पहचान भेजता है।
• आप किसी Kubernetes या कंटेनर परिवेश में हैं, जहाँ Gateway तक पहुँचने का एकमात्र मार्ग प्रॉक्सी है।
• आपको WebSocket 1008 unauthorized त्रुटियाँ मिल रही हैं क्योंकि ब्राउज़र WS पेलोड में टोकन नहीं भेज सकते।

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

• आपका प्रॉक्सी उपयोगकर्ताओं को प्रमाणित नहीं करता (यह केवल TLS टर्मिनेटर या लोड बैलेंसर है)।
• Gateway तक पहुँचने का कोई भी ऐसा मार्ग मौजूद है जो प्रॉक्सी को बायपास करता है (फ़ायरवॉल में छिद्र, आंतरिक नेटवर्क पहुँच)।
• आप सुनिश्चित नहीं हैं कि आपका प्रॉक्सी फ़ॉरवर्ड किए गए हेडर को सही ढंग से हटाता/ओवरराइट करता है।
• आपको केवल व्यक्तिगत एकल-उपयोगकर्ता पहुँच चाहिए (इसके बजाय Tailscale Serve + loopback पर विचार करें)।

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

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

{  gateway: {    // विश्वसनीय-प्रॉक्सी प्रमाणीकरण डिफ़ॉल्ट रूप से अपेक्षा करता है कि प्रॉक्सी का स्रोत IP non-loopback हो    bind: "lan",     // अत्यंत महत्वपूर्ण: यहाँ केवल अपने प्रॉक्सी के IP जोड़ें    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // प्रमाणित उपयोगकर्ता पहचान वाला हेडर (आवश्यक)        userHeader: "x-forwarded-user",         // वैकल्पिक: वे हेडर जिनका मौजूद होना आवश्यक है (प्रॉक्सी सत्यापन)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // वैकल्पिक: विशिष्ट उपयोगकर्ताओं तक सीमित करें (खाली = सभी को अनुमति दें)        allowUsers: ["nick@example.com", "admin@company.org"],         // वैकल्पिक: स्पष्ट रूप से स्वीकार करने के बाद समान-होस्ट loopback प्रॉक्सी को अनुमति दें        allowLoopback: false,         // वैकल्पिक: प्रमाणित प्रॉक्सी उपयोगकर्ताओं को नए ब्राउज़र डिवाइस नामांकित करने दें        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

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

स्वचालित डिवाइस स्वीकृति

विश्वसनीय-प्रॉक्सी प्रमाणीकरण वैकल्पिक रूप से नए ब्राउज़र डिवाइसों के लिए प्रॉक्सी पहचान को स्वीकृति सीमा के रूप में उपयोग कर सकता है:

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

डिफ़ॉल्ट enabled: false है। सक्षम होने पर ये सभी नियम लागू होते हैं:

1. WebSocket को किसी गैर-रिक्त उपयोगकर्ता पहचान के साथ trusted-proxy विधि के माध्यम से प्रमाणित होना चाहिए, और अनुमतिसूची कॉन्फ़िगर होने पर उस पहचान को allowUsers में सफल होना चाहिए। टोकन, पासवर्ड, Tailscale और अप्रमाणित कनेक्शन कभी भी इस नीति का उपयोग नहीं करते।
2. केवल नए Control UI या WebChat ब्राउज़र डिवाइस को स्वतः स्वीकृत किया जा सकता है। स्कोप अपग्रेड सहित किसी मौजूदा डिवाइस का कोई भी अनुरोध openclaw devices approve <requestId> के साथ मैन्युअल स्वीकृति के लिए लंबित रहता है।
3. डिवाइस को operator भूमिका के साथ स्वीकृत किया जाता है। यदि कनेक्ट अनुरोध में स्कोप शामिल हैं, तो अनुदान अनुरोधित स्कोप और deviceAutoApprove.scopes का सटीक प्रतिच्छेद होता है। यदि अनुरोध में स्कोप नहीं हैं, तो कॉन्फ़िगर की गई सूची प्रदान की जाती है; वह सूची न दिए जाने पर यह डिफ़ॉल्ट रूप से operator.read, operator.write, और operator.approvals होती है। इसके बाद परिणामी अनुदान को कनेक्शन के x-openclaw-scopes प्रॉक्सी हेडर द्वारा, उसके मौजूद होने पर, अतिरिक्त रूप से सीमित किया जाता है। इसलिए किसी उपयोगकर्ता के स्कोप को सीमित करने वाला प्रॉक्सी केवल सत्र ही नहीं, बल्कि स्थायी डिवाइस अनुदान भी सीमित करता है—मौजूद लेकिन खाली हेडर से कोई स्कोप नहीं मिलता। यह सीमा तब भी लागू होती है जब क्लाइंट अपनी स्कोप सूची नहीं देता।
4. operator.admin की अनुमति केवल deviceAutoApprove.scopes में स्पष्ट रूप से सूचीबद्ध किए जाने पर है। सूचीबद्ध होने पर प्रत्येक प्रॉक्सी-प्रमाणित उपयोगकर्ता नए ब्राउज़र डिवाइस पर पूर्ण एडमिन का अनुरोध कर सकता है और उसे स्वतः प्राप्त कर सकता है; बिना स्कोप वाले अनुरोधों को स्वतः पूर्ण एडमिन मिलता है। openclaw security audit CRITICAL gateway.trusted_proxy_device_auto_approve_admin निष्कर्ष रिपोर्ट करता है और Gateway स्टार्टअप पर एक बार चेतावनी लॉग करता है। प्रति-पहचान भूमिकाएँ उपलब्ध होने तक openclaw devices approve या openclaw devices rotate के साथ मैन्युअल एडमिन स्वीकृति को प्राथमिकता दें।

Control UI पेयरिंग व्यवहार

जब gateway.auth.mode = "trusted-proxy" सक्रिय हो और अनुरोध विश्वसनीय-प्रॉक्सी जाँचों में सफल हो, तब Control UI WebSocket सत्र डिवाइस पेयरिंग पहचान के बिना कनेक्ट हो सकते हैं।

स्कोप संबंधी प्रभाव:

• डिवाइस-रहित Control UI WebSocket सत्र कनेक्ट होते हैं, लेकिन डिफ़ॉल्ट रूप से उन्हें कोई ऑपरेटर स्कोप नहीं मिलता। OpenClaw अनुरोधित स्कोप सूची को [] पर साफ़ कर देता है, ताकि किसी स्वीकृत पेयर्ड डिवाइस/टोकन से आबद्ध न होने वाला सत्र स्वयं अनुमतियाँ घोषित न कर सके।
• यदि सफल WebSocket कनेक्शन के बाद विधियाँ missing scope के साथ विफल होती हैं, तो HTTPS का उपयोग करें ताकि ब्राउज़र डिवाइस पहचान बना सके और पेयरिंग पूरी कर सके। Control UI का असुरक्षित HTTP देखें।
• जिन पुराने कॉन्फ़िगरेशन में अब भी सेवानिवृत्त gateway.controlUi.dangerouslyDisableDeviceAuth=true कुंजी मौजूद है, वे सीमित Control UI अपग्रेड माइग्रेशन का उपयोग करते हैं।

रिवर्स-प्रॉक्सी स्कोप सीमा: यदि आपका प्रॉक्सी Control UI WebSocket अपग्रेड अनुरोध पर x-openclaw-scopes भेजता है, तो OpenClaw सत्र स्कोप को अनुरोधित स्कोप और घोषित स्कोप के प्रतिच्छेद तक सीमित कर देता है। यह हेडर स्कोप प्रदान नहीं करता; यह केवल सत्र द्वारा रखे जा सकने वाले स्कोप को सीमित करता है। जब deviceAutoApprove.enabled true हो, तो यही सीमा स्वचालित डिवाइस स्वीकृति द्वारा लिखे गए स्थायी डिवाइस अनुदान पर भी लागू होती है, इसलिए स्वतः स्वीकृत डिवाइस के पास प्रॉक्सी द्वारा घोषित स्कोप से अधिक स्कोप कभी नहीं होते।

प्रभाव:

• डिवाइस-रहित Control UI पहुँच के लिए पेयरिंग अब प्राथमिक गेट नहीं है। जब deviceAutoApprove.enabled true हो, तो प्रॉक्सी पहचान नए ब्राउज़र डिवाइस नामांकन के लिए भी स्वीकृति गेट बन जाती है।
• आपकी रिवर्स प्रॉक्सी प्रमाणीकरण नीति और allowUsers प्रभावी पहुँच नियंत्रण बन जाते हैं।
• Gateway प्रवेश को केवल विश्वसनीय प्रॉक्सी IP तक सीमित रखें (gateway.trustedProxies + फ़ायरवॉल)।

कस्टम WebSocket क्लाइंट Control UI सत्र नहीं हैं। सेवानिवृत्त Control UI अपग्रेड इनपुट मनमाने client.mode: "backend" या CLI-आकार वाले क्लाइंट को अस्थायी पहुँच प्रदान नहीं करता। कस्टम स्वचालन को डिवाइस पहचान/पेयरिंग, आरक्षित प्रत्यक्ष-स्थानीय client.id: "gateway-client" बैकएंड सहायक पथ, या जब HTTP अनुरोध/प्रतिक्रिया सतह अधिक उपयुक्त हो तब एडमिन HTTP RPC Plugin का उपयोग करना चाहिए।

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

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

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

उदाहरण:

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

व्यवहार:

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

व्यावहारिक नियम: जब आप किसी विश्वसनीय-प्रॉक्सी अनुरोध को डिफ़ॉल्ट से अधिक सीमित रखना चाहते हों, या किसी Gateway-प्रमाणीकरण वाली Plugin रूट को लेखन स्कोप से अधिक शक्तिशाली अनुमति चाहिए, तो x-openclaw-scopes स्पष्ट रूप से भेजें।

TLS समाप्ति और HSTS

एक TLS समाप्ति बिंदु का उपयोग करें और वहीं HSTS लागू करें।

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

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

चरणबद्ध लागू करने का मार्गदर्शन

• ट्रैफ़िक सत्यापित करते समय पहले छोटी अधिकतम अवधि (उदाहरण के लिए max-age=300) से शुरुआत करें।
• पूरा विश्वास होने के बाद ही दीर्घकालिक मानों (उदाहरण के लिए max-age=31536000) तक बढ़ाएँ।
• केवल तभी includeSubDomains जोड़ें, जब प्रत्येक सबडोमेन HTTPS के लिए तैयार हो।
• प्रीलोड का उपयोग केवल तभी करें, जब आप जानबूझकर अपने पूरे डोमेन सेट के लिए प्रीलोड आवश्यकताओं को पूरा करते हों।
• केवल-लूपबैक स्थानीय विकास को HSTS से लाभ नहीं मिलता।

प्रॉक्सी सेटअप के उदाहरण

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Pomerium का 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/साइडकार प्रॉक्सी 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 कंटेनर IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

मिश्रित टोकन कॉन्फ़िगरेशन

यदि कोई साझा टोकन भी कॉन्फ़िगर किया गया हो (gateway.auth.token या OPENCLAW_GATEWAY_TOKEN), तो Gateway स्टार्टअप विश्वसनीय-प्रॉक्सी प्रमाणीकरण को अस्वीकार कर देता है। दोनों परस्पर अनन्य हैं, क्योंकि साझा टोकन समान होस्ट वाले कॉलर को उस प्रॉक्सी-सत्यापित पहचान से पूरी तरह अलग मार्ग पर प्रमाणित होने देगा, जिसे यह मोड लागू करने के लिए बनाया गया है।

यदि स्टार्टअप gateway auth mode is trusted-proxy, but a shared token is also configured जैसी त्रुटि के साथ विफल होता है:

• विश्वसनीय-प्रॉक्सी मोड का उपयोग करते समय साझा टोकन हटाएँ, या
• यदि आप टोकन-आधारित प्रमाणीकरण चाहते हैं, तो gateway.auth.mode को "token" पर बदलें।

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

सुरक्षा जाँच-सूची

विश्वसनीय-प्रॉक्सी प्रमाणीकरण सक्षम करने से पहले सत्यापित करें:

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

सुरक्षा ऑडिट

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

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

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

Control UI उजागर होने पर अलग, गैर-विश्वसनीय-प्रॉक्सी-विशिष्ट निष्कर्ष भी लागू होते हैं: वाइल्डकार्ड या अनुपस्थित gateway.controlUi.allowedOrigins, और Host-हेडर मूल फ़ॉलबैक।

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

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

संबंधित

• कॉन्फ़िगरेशन — कॉन्फ़िगरेशन संदर्भ
• ऑपरेटर स्कोप — भूमिकाएँ, स्कोप और अनुमोदन जाँच
• दूरस्थ पहुँच — दूरस्थ पहुँच के अन्य पैटर्न
• सुरक्षा — संपूर्ण सुरक्षा मार्गदर्शिका
• Tailscale — केवल टेलनेट पहुँच के लिए सरल विकल्प