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

زمان استفاده

از حالت احراز هویت trusted-proxy زمانی استفاده کنید که:

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

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

• اگر پراکسی شما کاربران را احراز هویت نمی‌کند (فقط یک TLS terminator یا load balancer است).
• اگر هر مسیری به Gateway وجود دارد که پراکسی را دور می‌زند (حفره‌های firewall، دسترسی شبکه داخلی).
• اگر مطمئن نیستید پراکسی شما headerهای forwarded را درست حذف/بازنویسی می‌کند.
• اگر فقط به دسترسی شخصی تک‌کاربره نیاز دارید (برای راه‌اندازی ساده‌تر، Tailscale Serve + loopback را در نظر بگیرید).

نحوه کار

رفتار pairing در Control UI

وقتی gateway.auth.mode = "trusted-proxy" فعال است و درخواست بررسی‌های trusted-proxy را با موفقیت می‌گذراند، نشست‌های WebSocket در Control UI می‌توانند بدون هویت pairing دستگاه وصل شوند.

پیامدهای scope:

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

محدودسازی scope توسط پراکسی معکوس:

• اگر پراکسی شما در درخواست upgrade WebSocket مربوط به Control UI، x-openclaw-scopes را ارسال کند، OpenClaw scopeهای نشست را به اشتراک scopeهای درخواستی و scopeهای اعلام‌شده محدود می‌کند. این header scope اعطا نمی‌کند؛ فقط آنچه نشست می‌تواند نگه دارد را محدودتر می‌کند.

پیامدها:

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

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

پیکربندی

{  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

از یک نقطه پایان‌دهی TLS استفاده کنید و HSTS را همان‌جا اعمال کنید.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

راهنمای rollout

• ابتدا با max age کوتاه شروع کنید (برای مثال max-age=300) در حالی که ترافیک را اعتبارسنجی می‌کنید.
• فقط پس از بالا رفتن اطمینان، آن را به مقادیر بلندمدت افزایش دهید (برای مثال max-age=31536000).
• فقط اگر هر subdomain آماده HTTPS است، includeSubDomains را اضافه کنید.
• فقط اگر عمداً الزامات preload را برای مجموعه کامل دامنه‌های خود برآورده می‌کنید، از preload استفاده کنید.
• توسعه محلی فقط روی 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",      },    },  },}

پیکربندی token مختلط

OpenClaw پیکربندی‌های مبهمی را که در آن‌ها هم gateway.auth.token (یا OPENCLAW_GATEWAY_TOKEN) و هم حالت trusted-proxy هم‌زمان فعال هستند رد می‌کند. پیکربندی‌های token مختلط می‌توانند باعث شوند درخواست‌های loopback بی‌صدا در مسیر احراز هویت اشتباه احراز هویت شوند.

اگر هنگام startup خطای mixed_trusted_proxy_token دیدید:

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

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

هدر دامنه‌های اپراتور

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

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

نمونه‌ها:

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

رفتار:

• وقتی هدر وجود دارد، OpenClaw مجموعه دامنه اعلام‌شده را رعایت می‌کند.
• وقتی هدر وجود دارد اما خالی است، درخواست هیچ دامنه اپراتوری اعلام نمی‌کند.
• وقتی هدر وجود ندارد، APIهای HTTP عادیِ حامل هویت به مجموعه دامنه پیش‌فرض استاندارد اپراتور fallback می‌کنند.
• مسیرهای HTTP Plugin با احراز هویت Gateway به‌صورت پیش‌فرض محدودترند: وقتی x-openclaw-scopes وجود ندارد، دامنه زمان اجرای آن‌ها به operator.write fallback می‌کند.
• درخواست‌های HTTP با مبدأ مرورگر همچنان باید از gateway.controlUi.allowedOrigins (یا حالت fallback عمدی Host-header) عبور کنند، حتی پس از موفقیت احراز هویت پراکسی معتمد.
• برای نشست‌های WebSocket در Control UI، وقتی x-openclaw-scopes در درخواست ارتقا وجود داشته باشد، سقف دامنه است. مقدار خالی به هیچ دامنه‌ای منجر نمی‌شود.

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

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

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

• [ ] پراکسی تنها مسیر است: پورت Gateway از همه‌چیز به‌جز پراکسی شما پشت فایروال است.
• [ ] trustedProxies حداقلی است: فقط IPهای واقعی پراکسی شما، نه کل زیرشبکه‌ها.
• [ ] مبدأ پراکسی local loopback عمدی است: احراز هویت پراکسی معتمد برای درخواست‌های با مبدأ local loopback در حالت fail closed شکست می‌خورد، مگر اینکه gateway.auth.trustedProxy.allowLoopback صریحاً برای پراکسی همان میزبان فعال شده باشد.
• [ ] پراکسی هدرها را حذف می‌کند: پراکسی شما هدرهای x-forwarded-* از کلاینت‌ها را بازنویسی می‌کند (نه اینکه به آن‌ها اضافه کند).
• [ ] پایان‌دهی TLS: پراکسی شما TLS را مدیریت می‌کند؛ کاربران از طریق HTTPS وصل می‌شوند.
• [ ] allowedOrigins صریح است: Control UI غیر local loopback از gateway.controlUi.allowedOrigins صریح استفاده می‌کند.
• [ ] allowUsers تنظیم شده است (توصیه‌شده): به‌جای اجازه‌دادن به هر کاربر احراز هویت‌شده، دسترسی را به کاربران شناخته‌شده محدود کنید.
• [ ] پیکربندی توکن ترکیبی وجود ندارد: هم‌زمان gateway.auth.token و gateway.auth.mode: "trusted-proxy" را تنظیم نکنید.
• [ ] fallback رمز عبور محلی خصوصی است: اگر gateway.auth.password را برای فراخواننده‌های مستقیم داخلی پیکربندی می‌کنید، پورت Gateway را پشت فایروال نگه دارید تا کلاینت‌های راه‌دور غیرپراکسی نتوانند مستقیماً به آن برسند.

ممیزی امنیت

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

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

• هشدار/یادآوری critical پایه gateway.trusted_proxy_auth
• نبود پیکربندی trustedProxies
• نبود پیکربندی userHeader
• allowUsers خالی (اجازه به هر کاربر احراز هویت‌شده)
• فعال بودن allowLoopback برای مبدأهای پراکسی همان میزبان
• سیاست مبدأ مرورگر wildcard یا مفقود در سطح‌های درمعرض‌دسترسی Control UI

عیب‌یابی

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

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

مرتبط

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