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

زمان استفاده

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

زمان‌هایی که نباید استفاده شود

• پراکسی شما کاربران را احراز هویت نمی‌کند و صرفاً پایان‌دهنده TLS یا متعادل‌کننده بار است.
• مسیری برای دسترسی به Gateway وجود دارد که پراکسی را دور می‌زند، مانند حفره‌های دیوار آتش یا دسترسی از شبکه داخلی.
• مطمئن نیستید که پراکسی شما سرآیندهای هدایت‌شده را به‌درستی حذف یا بازنویسی می‌کند.
• فقط به دسترسی شخصی تک‌کاربره نیاز دارید؛ در عوض Tailscale Serve + 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,         // اختیاری: اجازه به کاربران احراز‌شده پراکسی برای ثبت دستگاه‌های مرورگر جدید        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

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

تأیید خودکار دستگاه

احراز هویت پراکسی قابل‌اعتماد می‌تواند به‌صورت اختیاری از هویت پراکسی به‌عنوان مرز تأیید برای دستگاه‌های مرورگر جدید استفاده کند:

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

مقدار پیش‌فرض enabled: false است. هنگام فعال‌بودن، همه قواعد زیر اعمال می‌شوند:

1. WebSocket باید از طریق روش trusted-proxy، با هویت کاربری غیرخالی که در صورت پیکربندی فهرست مجاز از allowUsers عبور کرده است، احراز هویت شده باشد. اتصال‌های مبتنی بر توکن، رمز عبور، Tailscale و اتصال‌های احراز هویت‌نشده هرگز از این سیاست استفاده نمی‌کنند.
2. فقط دستگاه مرورگر جدید رابط کاربری کنترل یا WebChat می‌تواند به‌طور خودکار تأیید شود. هر درخواست برای دستگاه موجود، از جمله ارتقای دامنه، با openclaw devices approve <requestId> در انتظار تأیید دستی باقی می‌ماند.
3. دستگاه با نقش operator تأیید می‌شود. اگر درخواست اتصال شامل دامنه‌ها باشد، مجوز اعطاشده دقیقاً اشتراک دامنه‌های درخواستی و deviceAutoApprove.scopes است. اگر درخواست دامنه‌ها را حذف کند، فهرست پیکربندی‌شده اعطا می‌شود؛ اگر آن فهرست حذف شده باشد، مقدار پیش‌فرض آن operator.read، operator.write و operator.approvals است. سپس مجوز حاصل، در صورت وجود، علاوه‌براین با سرآیند پراکسی x-openclaw-scopes اتصال محدود می‌شود؛ بنابراین پراکسی‌ای که دامنه‌های کاربر را محدود می‌کند، مجوز ماندگار دستگاه را نیز، نه فقط نشست را، محدود می‌کند؛ سرآیند موجود اما خالی هیچ دامنه‌ای اعطا نمی‌کند. این محدودیت حتی زمانی اعمال می‌شود که کلاینت فهرست دامنه‌های خود را حذف کند.
4. operator.admin فقط با فهرست‌شدن صریح در deviceAutoApprove.scopes مجاز است. در صورت فهرست‌شدن، هر کاربر احراز‌شده توسط پراکسی می‌تواند دسترسی کامل مدیر را روی دستگاه مرورگر جدید درخواست کند و به‌طور خودکار دریافت کند؛ درخواست‌های بدون دامنه نیز به‌طور خودکار دسترسی کامل مدیر دریافت می‌کنند. openclaw security audit یافته CRITICAL با شناسه gateway.trusted_proxy_device_auto_approve_admin را گزارش می‌کند و Gateway هنگام راه‌اندازی یک‌بار هشدار ثبت می‌کند. تا زمانی که نقش‌های مختص هر هویت در دسترس قرار گیرند، تأیید دستی مدیر با openclaw devices approve یا openclaw devices rotate را ترجیح دهید.

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

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

پیامدهای دامنه:

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

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

پیامدها:

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

کلاینت‌های سفارشی WebSocket نشست رابط کاربری کنترل نیستند. ورودی بازنشسته ارتقای رابط کاربری کنترل، دسترسی موقت به کلاینت‌های دلخواه client.mode: "backend" یا کلاینت‌های دارای ساختار CLI اعطا نمی‌کند. خودکارسازی سفارشی باید از هویت/جفت‌سازی دستگاه، مسیر کمکی backend رزروشده مستقیم محلی client.id: "gateway-client" یا Plugin مربوط به RPC مدیریتی HTTP استفاده کند، هرگاه سطح درخواست/پاسخ 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 افزونه با احراز هویت Gateway به‌طور پیش‌فرض محدودترند: وقتی x-openclaw-scopes وجود نداشته باشد، دامنه دسترسی زمان اجرای آن‌ها فقط به operator.write بازمی‌گردد.
• درخواست‌های HTTP با مبدأ مرورگر، حتی پس از موفقیت احراز هویت پروکسی مورداعتماد، همچنان باید gateway.controlUi.allowedOrigins (یا حالت بازگشت عامدانه مبتنی بر سرآیند Host) را با موفقیت بگذرانند.

قاعده عملی: هرگاه می‌خواهید درخواست پروکسی مورداعتماد محدودتر از پیش‌فرض‌ها باشد، یا زمانی که یک مسیر افزونه با احراز هویت 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 آماده باشد.
• فقط در صورتی از پیش‌بارگذاری استفاده کنید که عمداً الزامات پیش‌بارگذاری را برای کل مجموعه دامنه‌های خود برآورده می‌کنید.
• توسعه محلیِ محدود به حلقه‌بازگشت از 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"], // نشانی 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.token یا OPENCLAW_GATEWAY_TOKEN) راه‌اندازی Gateway احراز هویت پروکسی مورداعتماد را رد می‌کند. این دو مانعةالجمع‌اند، زیرا یک توکن اشتراکی به فراخواننده‌های همان میزبان اجازه می‌دهد از مسیری کاملاً متفاوت با هویت تأییدشده توسط پروکسی که این حالت برای اجرای آن در نظر گرفته شده است، احراز هویت کنند.

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

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

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

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

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

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

ممیزی امنیتی

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

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

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

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

عیب‌یابی

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

مرتبط

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