信頼済みプロキシ認証

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 を ID 認識プロキシ（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）の背後で実行している。
• プロキシがすべての認証を処理し、ヘッダー経由でユーザー ID を渡す。
• Kubernetes またはコンテナ環境で、プロキシが Gateway への唯一の経路である。
• ブラウザーが WS ペイロードでトークンを渡せないため、WebSocket 1008 unauthorized エラーが発生している。

​

使用しない場面

• プロキシがユーザーを認証しない場合（単なる TLS 終端またはロードバランサー）。
• プロキシを迂回して Gateway に到達できる経路が少しでもある場合（ファイアウォールの穴、内部ネットワークアクセス）。
• プロキシが転送ヘッダーを正しく削除または上書きしているか不明な場合。
• 個人の単一ユーザーアクセスだけが必要な場合（より簡単な設定として Tailscale Serve + ループバックを検討してください）。

​

仕組み

​

Control UI ペアリングの動作

• このモードでは、ペアリングは Control UI アクセスの主なゲートではなくなります。
• リバースプロキシの認証ポリシーと 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（例: max-age=300）から始めます。
• 十分に確信が持てた後でのみ、長期間の値（例: max-age=31536000）へ増やします。
• すべてのサブドメインが HTTPS 対応済みの場合にのみ、includeSubDomains を追加します。
• ドメインセット全体で preload 要件を意図的に満たす場合にのみ、プリロードを使用します。
• ループバック専用のローカル開発では、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",
      },
    },
  },
}

​

混在トークン設定

• trusted-proxy モードを使用する場合は共有トークンを削除する、または
• トークンベースの認証を意図している場合は、gateway.auth.mode を "token" に切り替える。

​

オペレータースコープヘッダー

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

• ヘッダーが存在する場合、OpenClaw は宣言されたスコープセットを尊重します。
• ヘッダーが存在するが空の場合、リクエストはオペレータースコープが ない ことを宣言します。
• ヘッダーが存在しない場合、通常の ID を伴う HTTP API は標準のオペレーター既定スコープセットにフォールバックします。
• Gateway 認証の Plugin HTTP ルート はデフォルトでより狭くなります。x-openclaw-scopes が存在しない場合、そのランタイムスコープは operator.write にフォールバックします。
• ブラウザー送信元の HTTP リクエストは、trusted-proxy 認証に成功した後でも、gateway.controlUi.allowedOrigins（または意図的な Host ヘッダーフォールバックモード）を通過する必要があります。

​

セキュリティチェックリスト

• プロキシが唯一の経路: Gateway ポートは、プロキシ以外のすべてからファイアウォールで遮断されています。
• trustedProxies は最小限: サブネット全体ではなく、実際のプロキシ IP のみです。
• ループバックのプロキシソースは意図的: trusted-proxy 認証は、同一ホストのプロキシ向けに gateway.auth.trustedProxy.allowLoopback が明示的に有効化されていない限り、ループバックソースのリクエストをフェイルクローズします。
• プロキシがヘッダーを除去: プロキシはクライアントからの x-forwarded-* ヘッダーを追記ではなく上書きします。
• TLS 終端: プロキシが TLS を処理し、ユーザーは HTTPS 経由で接続します。
• allowedOrigins は明示的: 非ループバックのコントロール UI は明示的な gateway.controlUi.allowedOrigins を使用します。
• allowUsers が設定されている（推奨）: 認証済みの全員を許可するのではなく、既知のユーザーに制限します。
• トークン設定が混在していない: gateway.auth.token と gateway.auth.mode: "trusted-proxy" の両方を設定しないでください。
• ローカルパスワードのフォールバックは非公開: 内部の直接呼び出し元向けに gateway.auth.password を構成する場合は、非プロキシのリモートクライアントが直接到達できないように Gateway ポートをファイアウォールで遮断してください。

​

セキュリティ監査

• 基本の gateway.trusted_proxy_auth warning/critical リマインダー
• trustedProxies 構成の欠落
• userHeader 構成の欠落
• 空の allowUsers（認証済みユーザーをすべて許可）
• 同一ホストのプロキシソース向けに有効化された allowLoopback
• 公開されたコントロール UI サーフェスでのワイルドカードまたは欠落したブラウザーオリジンポリシー

​

トラブルシューティング

​

トークン認証からの移行

​

関連

• 構成 — 構成リファレンス
• リモートアクセス — その他のリモートアクセスパターン
• セキュリティ — 完全なセキュリティガイド
• Tailscale — tailnet 専用アクセス向けのよりシンプルな代替手段