مصادقة الوكيل الموثوق

متى تستخدمه

استخدم وضع مصادقة trusted-proxy عندما:

• تشغّل OpenClaw خلف وكيل مدرك للهوية (Pomerium، Caddy + OAuth، nginx + oauth2-proxy، Traefik + forward auth).
• يتولى الوكيل لديك كل المصادقة ويمرر هوية المستخدم عبر الترويسات.
• تكون في بيئة Kubernetes أو حاويات حيث يكون الوكيل هو المسار الوحيد إلى Gateway.
• تواجه أخطاء WebSocket ‏1008 unauthorized لأن المتصفحات لا يمكنها تمرير الرموز في حمولات WS.

متى لا تستخدمه

• إذا كان الوكيل لديك لا يصادق المستخدمين (مجرد منهٍ لـ TLS أو موازن تحميل).
• إذا كان هناك أي مسار إلى Gateway يتجاوز الوكيل (ثغرات في الجدار الناري، وصول عبر الشبكة الداخلية).
• إذا لم تكن متأكدًا مما إذا كان الوكيل لديك يزيل/يستبدل الترويسات المعاد توجيهها بشكل صحيح.
• إذا كنت تحتاج فقط إلى وصول شخصي لمستخدم واحد (فكر في Tailscale Serve + loopback لإعداد أبسط).

كيف يعمل

سلوك الاقتران في واجهة التحكم

عندما يكون gateway.auth.mode = "trusted-proxy" نشطًا ويمر الطلب فحوصات الوكيل الموثوق، يمكن لجلسات WebSocket في واجهة التحكم الاتصال من دون هوية اقتران جهاز.

آثار النطاق:

• تتصل جلسات WebSocket لواجهة التحكم من دون جهاز، لكنها لا تتلقى أي نطاقات مشغّل افتراضيًا. يفرغ OpenClaw قائمة النطاقات المطلوبة إلى [] حتى لا تتمكن جلسة غير مرتبطة بجهاز/رمز مقترن وموافق عليه من إعلان الأذونات ذاتيًا.
• إذا فشلت الطرق مع missing scope بعد اتصال WebSocket ناجح، فاستخدم HTTPS حتى يتمكن المتصفح من إنشاء هوية جهاز وإكمال الاقتران. راجع HTTP غير الآمن لواجهة التحكم.
• لكسر الزجاج فقط: يحافظ gateway.controlUi.dangerouslyDisableDeviceAuth=true على النطاقات المطلوبة حتى من دون هوية جهاز. هذا خفض أمني شديد؛ تراجع عنه سريعًا. راجع HTTP غير الآمن لواجهة التحكم.

تحديد نطاقات الوكيل العكسي:

• إذا أرسل الوكيل لديك x-openclaw-scopes في طلب ترقية WebSocket لواجهة التحكم، فإن OpenClaw يحد نطاقات الجلسة إلى تقاطع النطاقات المطلوبة والنطاقات المعلنة. لا تمنح هذه الترويسة نطاقات؛ إنها تضيق فقط ما يمكن للجلسة امتلاكه.

الآثار:

• لم يعد الاقتران البوابة الأساسية للوصول إلى واجهة التحكم في هذا الوضع.
• تصبح سياسة مصادقة الوكيل العكسي وallowUsers لديك هي التحكم الفعلي في الوصول.
• أبقِ دخول Gateway مقصورًا على عناوين IP الخاصة بالوكلاء الموثوقين فقط (gateway.trustedProxies + الجدار الناري).

عملاء WebSocket المخصصون ليسوا جلسات واجهة التحكم. لا يمنح gateway.controlUi.dangerouslyDisableDeviceAuth نطاقات لعملاء عشوائيين بشكل client.mode: "backend" أو عملاء مشابهين لـ CLI. يجب أن تستخدم الأتمتة المخصصة هوية الجهاز/الاقتران، أو مسار مساعد backend المحلي المباشر المحجوز client.id: "gateway-client"، أو Plugin ‏admin HTTP RPC عندما يكون سطح طلب/استجابة HTTP أكثر ملاءمة.

التهيئة

{  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 و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.
• استخدم التحميل المسبق فقط إذا كنت تستوفي عمدًا متطلبات التحميل المسبق لمجموعة نطاقاتك الكاملة.
• لا تستفيد بيئة التطوير المحلية عبر loopback فقط من HSTS.

أمثلة إعداد الوكيل

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

تهيئة الرموز المختلطة

يرفض OpenClaw التهيئات الملتبسة حيث يكون كل من gateway.auth.token (أو OPENCLAW_GATEWAY_TOKEN) ووضع trusted-proxy نشطين في الوقت نفسه. يمكن أن تتسبب تهيئات الرموز المختلطة في مصادقة طلبات loopback بصمت عبر مسار المصادقة الخاطئ.

إذا رأيت خطأ mixed_trusted_proxy_token عند بدء التشغيل:

• أزل الرمز المشترك عند استخدام وضع الوكيل الموثوق، أو
• بدّل gateway.auth.mode إلى "token" إذا كنت تقصد المصادقة القائمة على الرموز.

تظل ترويسات هوية الوكيل الموثوق عبر loopback تفشل مغلقة: لا تتم مصادقة المستدعين من المضيف نفسه بصمت كمستخدمي وكيل. يمكن لمستدعي OpenClaw الداخليين الذين يتجاوزون الوكيل المصادقة باستخدام gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD بدلا من ذلك. يظل الرجوع إلى الرمز غير مدعوم عمدا في وضع الوكيل الموثوق.

ترويسة نطاقات المشغل

مصادقة الوكيل الموثوق هي وضع HTTP حامل للهوية، لذلك يمكن للمستدعين اختياريا إعلان نطاقات المشغل باستخدام x-openclaw-scopes في طلبات HTTP API.

ملاحظة: تحدد نطاقات WebSocket بواسطة مصافحة بروتوكول Gateway وربط هوية الجهاز. في طلبات ترقية WebSocket الخاصة بـ Control UI، يكون 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 العادية الحاملة للهوية إلى مجموعة نطاقات المشغل الافتراضية القياسية.
• تكون مسارات HTTP الخاصة بالـ Plugin لمصادقة Gateway أضيق افتراضيا: عند غياب x-openclaw-scopes، يرجع نطاق التشغيل لديها إلى operator.write.
• لا تزال طلبات HTTP من أصل المتصفح مطالبة باجتياز gateway.controlUi.allowedOrigins (أو وضع الرجوع المتعمد لترويسة Host) حتى بعد نجاح مصادقة الوكيل الموثوق.
• بالنسبة إلى جلسات WebSocket الخاصة بـ Control UI، يكون x-openclaw-scopes حدا أقصى للنطاق عند وجوده في طلب الترقية. تؤدي القيمة الفارغة إلى عدم وجود نطاقات.

قاعدة عملية: أرسل x-openclaw-scopes صراحة عندما تريد أن يكون طلب الوكيل الموثوق أضيق من الافتراضيات، أو عندما يحتاج مسار Plugin لمصادقة Gateway إلى شيء أقوى من نطاق الكتابة.

قائمة تدقيق الأمان

قبل تفعيل مصادقة الوكيل الموثوق، تحقق مما يلي:

• [ ] الوكيل هو المسار الوحيد: منفذ Gateway محمي بجدار ناري من كل شيء باستثناء وكيلك.
• [ ] trustedProxies في الحد الأدنى: عناوين IP الخاصة بوكيلك الفعلي فقط، وليس شبكات فرعية كاملة.
• [ ] مصدر وكيل loopback متعمد: تفشل مصادقة الوكيل الموثوق مغلقة لطلبات مصدر loopback ما لم يتم تفعيل gateway.auth.trustedProxy.allowLoopback صراحة لوكيل على المضيف نفسه.
• [ ] الوكيل يزيل الترويسات: يكتب وكيلك فوق ترويسات x-forwarded-* الواردة من العملاء (ولا يضيف إليها).
• [ ] إنهاء TLS: يتولى وكيلك TLS؛ ويتصل المستخدمون عبر HTTPS.
• [ ] allowedOrigins صريح: يستخدم Control UI غير loopback قيمة gateway.controlUi.allowedOrigins صريحة.
• [ ] allowUsers مضبوط (مستحسن): قيد الوصول على المستخدمين المعروفين بدلا من السماح لأي شخص تمت مصادقته.
• [ ] لا يوجد إعداد مختلط للرموز: لا تضبط كلا من gateway.auth.token و gateway.auth.mode: "trusted-proxy".
• [ ] رجوع كلمة المرور المحلية خاص: إذا هيأت gateway.auth.password للمستدعين الداخليين المباشرين، فأبق منفذ Gateway محميا بجدار ناري حتى لا يتمكن العملاء البعيدون غير المارين عبر الوكيل من الوصول إليه مباشرة.

تدقيق الأمان

سيبلغ openclaw security audit عن مصادقة الوكيل الموثوق بنتيجة شدة حرجة. هذا مقصود، فهو تذكير بأنك تفوض الأمان إلى إعداد وكيلك.

يتحقق التدقيق من:

• تذكير/تحذير حرج أساسي gateway.trusted_proxy_auth
• إعداد trustedProxies مفقود
• إعداد userHeader مفقود
• allowUsers فارغ (يسمح لأي مستخدم تمت مصادقته)
• تفعيل allowLoopback لمصادر الوكيل على المضيف نفسه
• سياسة أصل المتصفح ذات بدل شامل أو مفقودة على أسطح Control UI المكشوفة

استكشاف الأخطاء وإصلاحها

الترحيل من مصادقة الرمز

إذا كنت تنتقل من مصادقة الرمز إلى الوكيل الموثوق:

ذات صلة

• الإعداد — مرجع الإعداد
• الوصول البعيد — أنماط وصول بعيدة أخرى
• الأمان — دليل الأمان الكامل
• Tailscale — بديل أبسط للوصول المحصور في tailnet