احراز هویت پروکسی مورد اعتماد

زمان استفاده

• OpenClaw را پشت یک پروکسی آگاه از هویت اجرا می‌کنید (Pomerium، ‏Caddy + OAuth، ‏nginx + oauth2-proxy، ‏Traefik + forward auth).
• پروکسی شما تمام احراز هویت را انجام می‌دهد و هویت کاربر را از طریق سرآیندها ارسال می‌کند.
• در محیط Kubernetes یا کانتینری هستید که پروکسی تنها مسیر دسترسی به Gateway است.
• با خطاهای WebSocket از نوع 1008 unauthorized مواجه می‌شوید، زیرا مرورگرها نمی‌توانند توکن‌ها را در بارهای WS ارسال کنند.

زمان عدم استفاده

• پروکسی شما کاربران را احراز هویت نمی‌کند و صرفاً پایان‌دهنده TLS یا متعادل‌کننده بار است.
• مسیری برای دسترسی به Gateway وجود دارد که پروکسی را دور می‌زند، مانند حفره‌های دیوار آتش یا دسترسی از شبکه داخلی.
• مطمئن نیستید که پروکسی شما سرآیندهای فورواردشده را به‌درستی حذف یا بازنویسی می‌کند.
• فقط به دسترسی شخصی تک‌کاربره نیاز دارید؛ در عوض Tailscale Serve + local loopback را در نظر بگیرید.

نحوه کار

پیکربندی

{  gateway: {    // احراز هویت پروکسی مورداعتماد به‌طور پیش‌فرض انتظار دارد IP مبدأ پروکسی loopback نباشد    bind: "lan",     // حیاتی: فقط IPهای پروکسی خود را اینجا اضافه کنید    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // سرآیند حاوی هویت کاربر احرازشده (الزامی)        userHeader: "x-forwarded-user",         // اختیاری: سرآیندهایی که باید وجود داشته باشند (تأیید پروکسی)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // اختیاری: محدودسازی به کاربران مشخص (خالی = اجازه به همه)        allowUsers: ["nick@example.com", "admin@company.org"],         // اختیاری: اجازه به پروکسی loopback هم‌میزبان پس از پذیرش صریح        allowLoopback: false,      },    },  },}

مرجع پیکربندی

رفتار جفت‌سازی رابط کنترل

هنگامی که gateway.auth.mode = "trusted-proxy" فعال باشد و درخواست بررسی‌های پروکسی مورداعتماد را بگذراند، نشست‌های WebSocket رابط کنترل می‌توانند بدون هویت جفت‌سازی دستگاه متصل شوند.

پیامدهای محدوده‌ها:

• نشست‌های WebSocket رابط کنترل بدون دستگاه متصل می‌شوند، اما به‌طور پیش‌فرض هیچ محدوده راهبری دریافت نمی‌کنند. OpenClaw فهرست محدوده‌های درخواستی را به [] پاک می‌کند تا نشستی که به دستگاه یا توکن جفت‌شده و تأییدشده‌ای متصل نیست، نتواند مجوزها را خوداظهاری کند.
• اگر پس از اتصال موفق WebSocket، متدها با missing scope شکست می‌خورند، از HTTPS استفاده کنید تا مرورگر بتواند هویت دستگاه را ایجاد و جفت‌سازی را کامل کند. به HTTP ناامن رابط کنترل مراجعه کنید.
• فقط برای شرایط اضطراری: gateway.controlUi.dangerouslyDisableDeviceAuth=true حتی بدون هویت دستگاه نیز محدوده‌های درخواستی را حفظ می‌کند. این کار امنیت را به‌شدت کاهش می‌دهد؛ آن را سریعاً بازگردانید. به HTTP ناامن رابط کنترل مراجعه کنید.

محدودسازی محدوده توسط پروکسی معکوس: اگر پروکسی شما در درخواست ارتقای WebSocket رابط کنترل، x-openclaw-scopes را ارسال کند، OpenClaw محدوده‌های نشست را به اشتراک محدوده‌های درخواستی و محدوده‌های اعلام‌شده محدود می‌کند. این سرآیند محدوده‌ای اعطا نمی‌کند؛ فقط مواردی را که نشست می‌تواند داشته باشد محدودتر می‌کند.

پیامدها:

• در این حالت، جفت‌سازی دیگر دروازه اصلی دسترسی به رابط کنترل نیست.
• خط‌مشی احراز هویت پروکسی معکوس شما و allowUsers به کنترل دسترسی مؤثر تبدیل می‌شوند.
• ورودی Gateway را فقط به IPهای پروکسی مورداعتماد محدود نگه دارید (gateway.trustedProxies + دیوار آتش).

کارخواه‌های سفارشی WebSocket نشست رابط کنترل نیستند. gateway.controlUi.dangerouslyDisableDeviceAuth به کارخواه‌های دلخواه با client.mode: "backend" یا کارخواه‌های دارای ساختار CLI محدوده اعطا نمی‌کند. خودکارسازی سفارشی باید از هویت دستگاه و جفت‌سازی، مسیر کمکی بک‌اند مستقیم و محلی رزروشده با client.id: "gateway-client"، یا در مواردی که سطح درخواست/پاسخ HTTP مناسب‌تر است از Plugin مربوط به RPC مدیریتی HTTP استفاده کند.

سرآیند محدوده‌های راهبری

احراز هویت پروکسی مورداعتماد یک حالت HTTP حامل هویت است؛ بنابراین فراخوان‌ها می‌توانند در صورت نیاز، محدوده‌های راهبری را با x-openclaw-scopes در درخواست‌های API مبتنی بر HTTP اعلام کنند.

نکته: محدوده‌های WebSocket توسط دست‌دهی پروتکل Gateway و اتصال هویت دستگاه تعیین می‌شوند. در درخواست‌های ارتقای WebSocket رابط کنترل، x-openclaw-scopes فقط سقفی برای محدوده‌های توافق‌شده نشست است، نه یک اعطا. به رفتار جفت‌سازی رابط کنترل مراجعه کنید.

نمونه‌ها:

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

رفتار:

• وقتی سرآیند موجود باشد، OpenClaw مجموعه محدوده اعلام‌شده را رعایت می‌کند.
• وقتی سرآیند موجود اما خالی باشد، درخواست هیچ محدوده راهبری را اعلام نمی‌کند.
• وقتی سرآیند وجود نداشته باشد، APIهای HTTP حامل هویت عادی به مجموعه استاندارد محدوده‌های پیش‌فرض راهبری بازمی‌گردند (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 عبور کنند.

قاعده عملی: هنگامی که می‌خواهید درخواست پروکسی مورداعتماد محدودتر از مقادیر پیش‌فرض باشد، یا زمانی که یک مسیر Plugin دارای احراز هویت Gateway به محدوده‌ای قوی‌تر از محدوده نوشتن نیاز دارد، x-openclaw-scopes را صریحاً ارسال کنید.

پایان‌دهی 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 آماده باشند.
• فقط زمانی از preload استفاده کنید که عمداً الزامات آن را برای کل مجموعه دامنه‌های خود برآورده می‌کنید.
• توسعه محلی محدود به loopback از HSTS سودی نمی‌برد.

نمونه‌های راه‌اندازی پروکسی

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP مربوط به Pomerium    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.token یا OPENCLAW_GATEWAY_TOKEN)، راه‌اندازی Gateway احراز هویت پراکسی مورداعتماد را رد می‌کند. این دو متقابلاً ناسازگارند، زیرا توکن مشترک به فراخوانندگان همان میزبان اجازه می‌دهد از مسیری کاملاً متفاوت با هویتی که پراکسی تأیید کرده و این حالت برای اعمال آن طراحی شده است، احراز هویت شوند.

اگر راه‌اندازی با خطایی مانند gateway auth mode is trusted-proxy, but a shared token is also configured شکست خورد:

• هنگام استفاده از حالت پراکسی مورداعتماد، توکن مشترک را حذف کنید، یا
• اگر قصد دارید از احراز هویت مبتنی بر توکن استفاده کنید، gateway.auth.mode را به "token" تغییر دهید.

سربرگ‌های هویت پراکسی مورداعتماد در local loopback همچنان به‌صورت بسته شکست می‌خورند: فراخوانندگان همان میزبان بدون اطلاع به‌عنوان کاربران پراکسی احراز هویت نمی‌شوند. فراخوانندگان داخلی OpenClaw که پراکسی را دور می‌زنند، می‌توانند در عوض با gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD احراز هویت کنند. بازگشت به توکن در حالت پراکسی مورداعتماد همچنان عمداً پشتیبانی نمی‌شود.

چک‌لیست امنیتی

پیش از فعال‌کردن احراز هویت پراکسی مورداعتماد، موارد زیر را بررسی کنید:

• [ ] پراکسی تنها مسیر است: پورت 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 را با فایروال محافظت کنید تا کلاینت‌های راه‌دور خارج از پراکسی نتوانند مستقیماً به آن دسترسی پیدا کنند.

ممیزی امنیتی

openclaw security audit احراز هویت پراکسی مورداعتماد را با یافته‌ای با شدت بحرانی علامت‌گذاری می‌کند. این رفتار عمدی است؛ یادآوری می‌کند که امنیت را به پیکربندی پراکسی خود واگذار کرده‌اید.

ممیزی موارد زیر را بررسی می‌کند:

• هشدار یا یادآوری بحرانی پایه gateway.trusted_proxy_auth.
• نبود پیکربندی trustedProxies.
• نبود پیکربندی userHeader.
• خالی‌بودن allowUsers که به هر کاربر احراز هویت‌شده اجازه دسترسی می‌دهد.
• فعال‌بودن allowLoopback برای مبدأهای پراکسی همان میزبان.

یافته‌های جداگانه‌ای که مختص پراکسی مورداعتماد نیستند نیز هر زمان که رابط کنترل در معرض دسترسی قرار گیرد اعمال می‌شوند: مقدار عام یا نبود gateway.controlUi.allowedOrigins و بازگشت مبدأ به سربرگ Host.

عیب‌یابی

مهاجرت از احراز هویت توکنی

مطالب مرتبط

• پیکربندی — مرجع پیکربندی
• محدوده‌های دسترسی اپراتور — نقش‌ها، محدوده‌های دسترسی و بررسی‌های تأیید
• دسترسی راه‌دور — الگوهای دیگر دسترسی راه‌دور
• امنیت — راهنمای کامل امنیت
• Tailscale — جایگزینی ساده‌تر برای دسترسی محدود به tailnet