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

# متى تستخدمه

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

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

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

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

# كيف يعمل

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

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

الآثار:

• لم يعد الإقران بوابة الوصول الأساسية إلى واجهة التحكم في هذا الوضع.
• تصبح سياسة مصادقة الوكيل العكسي و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: ["[email protected]", "[email protected]"],

        // 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: [email protected]
    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.

أمثلة:

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

السلوك:

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

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

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

قبل تمكين مصادقة trusted-proxy، تحقّق مما يلي:

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

# تدقيق الأمان

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

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

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

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

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

إذا كنت تنتقل من مصادقة الرمز إلى trusted-proxy:

# ذو صلة

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