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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

متى تستخدمه

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

​

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

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

​

كيف يعمل

​

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

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

​

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

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

​

تدقيق الأمان

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

​

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

​

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

​

ذو صلة

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