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

​

متى تستخدمه

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

​

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

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

​

كيف يعمل

​

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

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

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

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

​

التهيئة

{
  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

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

​

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

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

​

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

• 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 حدا أقصى للنطاق عند وجوده في طلب الترقية. تؤدي القيمة الفارغة إلى عدم وجود نطاقات.

​

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

• الوكيل هو المسار الوحيد: منفذ 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 محميا بجدار ناري حتى لا يتمكن العملاء البعيدون غير المارين عبر الوكيل من الوصول إليه مباشرة.

​

تدقيق الأمان

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

​

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

​

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

​

ذات صلة

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