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

​

متى يُستخدم

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

​

متى يجب عدم استخدامه

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

​

آلية العمل

​

الإعداد

{
  gateway: {
    // Trusted-proxy auth expects the proxy's source IP to be non-loopback 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,
      },
    },
  },
}

​

مرجع الإعداد

​

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

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

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

​

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

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

​

إنهاء 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.
• استخدم التحميل المسبق فقط إذا كنت تستوفي عمدًا متطلباته لمجموعة نطاقاتك الكاملة.
• لا تستفيد بيئة التطوير المحلية التي تقتصر على local 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"], // عنوان IP لوكيل Caddy/sidecar
    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"], // عنوان IP لـ nginx/oauth2-proxy
    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"], // عنوان IP لحاوية Traefik
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

إعداد الرموز المميّزة المختلط

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

​

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

• الوكيل هو المسار الوحيد: منفذ Gateway محمي بجدار ناري من كل شيء باستثناء وكيلك.
• trustedProxies في حدها الأدنى: عناوين IP الفعلية لوكيلك فقط، وليس شبكات فرعية كاملة.
• مصدر وكيل local loopback مقصود: تفشل مصادقة الوكيل الموثوق بشكل مغلق للطلبات ذات مصدر local loopback ما لم يُمكّن gateway.auth.trustedProxy.allowLoopback صراحةً لوكيل على المضيف نفسه.
• الوكيل يزيل الترويسات: يستبدل وكيلك ترويسات x-forwarded-* الواردة من العملاء، ولا يلحقها.
• إنهاء TLS: يتولى وكيلك TLS؛ ويتصل المستخدمون عبر HTTPS.
• allowedOrigins محددة صراحةً: تستخدم واجهة التحكم غير المتصلة عبر local 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 لمصادر الوكيل الموجودة على المضيف نفسه.

​

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

​

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

​

ذات صلة

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