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

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

از حالت احراز هویت 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 را در نظر بگیرید).

# نحوه کار

# رفتار جفت‌سازی Control UI

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

پیامدها:

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

# پیکربندی

{
  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",
      },
    },
  },
}

# راهنمای rollout

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

# پیکربندی 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" تغییر دهید.

headerهای هویت trusted-proxy روی loopback همچنان fail-closed هستند: فراخوان‌های همان میزبان بی‌صدا به‌عنوان کاربران پروکسی احراز هویت نمی‌شوند. فراخوان‌های داخلی OpenClaw که پروکسی را دور می‌زنند می‌توانند به‌جای آن با gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD احراز هویت کنند. fallback مبتنی بر token عمدا در حالت trusted-proxy پشتیبانی نمی‌شود.

# header حوزه‌های operator

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

نمونه‌ها:

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

رفتار:

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

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

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

پیش از فعال‌کردن احراز هویت 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 برای منابع پروکسی روی همان میزبان
• سیاست مبدأ مرورگر wildcard یا مفقود روی سطوح در معرض دسترس رابط کاربری کنترل

# عیب‌یابی

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

اگر از احراز هویت توکن به trusted-proxy منتقل می‌شوید:

# مرتبط

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