信頼済みプロキシ認証

# 使用する場面

次の場合は trusted-proxy 認証モードを使用します。

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

# 使用しない場面

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

# 仕組み

# Control UI ペアリングの動作

gateway.auth.mode = "trusted-proxy" が有効で、リクエストが trusted-proxy チェックを通過した場合、Control UI WebSocket セッションはデバイスペアリング ID なしで接続できます。

影響:

• このモードでは、ペアリングは 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: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# 設定リファレンス

# TLS 終端と HSTS

TLS 終端点を 1 つ使用し、そこで 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: [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",
      },
    },
  },
}

# 混在トークン設定

OpenClaw は、gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）と trusted-proxy モードの両方が同時に有効な曖昧な設定を拒否します。混在トークン設定では、ループバックリクエストが誤った認証経路で暗黙的に認証される可能性があります。

起動時に mixed_trusted_proxy_token エラーが表示される場合:

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

ループバックの trusted-proxy ID ヘッダーは引き続きフェイルクローズします。同一ホストの呼び出し元がプロキシユーザーとして暗黙的に認証されることはありません。プロキシを迂回する内部 OpenClaw 呼び出し元は、代わりに gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD で認証できます。trusted-proxy モードでは、トークンフォールバックは意図的にサポートされていません。

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

Trusted-proxy 認証は ID を伴う HTTP モードであるため、呼び出し元は任意で x-openclaw-scopes によりオペレータースコープを宣言できます。

例:

• 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 ヘッダーフォールバックモード）を通過する必要があります。

実用的なルール: trusted-proxy リクエストをデフォルトより狭くしたい場合、または Gateway 認証 Plugin ルートで write スコープより強いものが必要な場合は、x-openclaw-scopes を明示的に送信してください。

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

trusted-proxy 認証を有効にする前に、次を確認してください。

• [ ] プロキシが唯一の経路: 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 ポートをファイアウォールで遮断してください。

# セキュリティ監査

openclaw security audit は trusted-proxy 認証に critical 重大度の検出結果を付けます。これは意図的です。セキュリティをプロキシ設定に委任していることを思い出すためのものです。

監査では次をチェックします。

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

# トラブルシューティング

# トークン認証からの移行

トークン認証から trusted-proxy に移行する場合:

# 関連

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