信頼されたプロキシ認証 (Trusted Proxy Auth)

⚠️ セキュリティ上の重要な機能です。 このモードでは、認証を完全にリバースプロキシに委任します。設定を誤ると、ゲートウェイが不正アクセスにさらされる可能性があります。有効化する前に、このページをよくお読みください。

​

使用すべきケース

• OpenClawを ID認識プロキシ (Identity-Aware Proxy) （Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward authなど）の背後で実行している場合
• プロキシがすべての認証を処理し、ユーザーの識別情報をヘッダー経由で渡す場合
• Kubernetesやコンテナ環境において、プロキシがゲートウェイへの唯一の経路である場合
• ブラウザがWebSocketのペイロードでトークンを渡せないことが原因で、WebSocketの 1008 unauthorized エラーが発生している場合

​

使用すべきではないケース

• プロキシがユーザー認証を行わない場合（単なるTLS終端やロードバランサーとして動作している場合）
• プロキシを経由せずにゲートウェイにアクセスできる経路（ファイアウォールの穴、内部ネットワークからの直接アクセスなど）がある場合
• プロキシがクライアントからのヘッダーを正しく削除・上書きしているか確信が持てない場合
• 個人のシングルユーザーアクセスのみが必要な場合（よりシンプルなセットアップとして、Tailscale Serve + loopback の使用を検討してください）

​

仕組み

1. リバースプロキシがユーザーを認証します（OAuth, OIDC, SAMLなど）。
2. プロキシは、認証されたユーザーの識別情報（例：x-forwarded-user: nick@example.com）を含むヘッダーを追加します。
3. OpenClawは、リクエストが 信頼できるプロキシのIPアドレス （gateway.trustedProxies で設定）から送信されていることを確認します。
4. OpenClawは、設定されたヘッダーからユーザーの識別情報を抽出します。
5. すべての検証が成功すると、リクエストが認可されます。

​

Control UI のペアリング挙動

• このモードでは、ペアリングはControl UIアクセスの主要なゲートウェイではなくなります。
• リバースプロキシの認証ポリシーと allowUsers 設定が、実質的なアクセス制御となります。
• ゲートウェイへの進入トラフィックは、信頼できるプロキシのIPのみに制限してください（gateway.trustedProxies + ファイアウォール）。

​

設定方法

{
  gateway: {
    // 同一ホスト上のプロキシの場合は loopback を、リモートプロキシの場合は lan/custom を使用します
    bind: "loopback",

    // 重要：プロキシの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"],
      },
    },
  },
}

​

設定リファレンス

​

TLS 終端と HSTS

​

推奨パターン：プロキシでのTLS終端

• インターネット公開デプロイに適しています。
• 証明書管理とHTTPのセキュリティ強化ポリシーを一箇所に集約できます。
• プロキシの背後にあるOpenClawは、ループバックのHTTPで待機させることができます。

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

​

ゲートウェイでのTLS終端

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

​

導入時のガイドライン

• トラフィックの検証中は、まず短い有効期間（例：max-age=300）から始めてください。
• 十分な安全性が確認できてから、長期の有効期間（例：max-age=31536000）に延長してください。
• includeSubDomains を追加するのは、すべてのサブドメインがHTTPSに対応している場合のみにしてください。
• プリロード（preload）は、ドメイン全体でその要件を意図的に満たしている場合のみ使用してください。
• ループバックのみのローカル開発環境では、HSTSによるメリットはありません。

​

プロキシ設定の例

​

Pomerium

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomeriumの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

​

Caddy (OAuth使用時)

{
  gateway: {
    bind: "lan",
    trustedProxies: ["127.0.0.1"], // 同一ホスト内のCaddyの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}
    }
}

​

nginx + oauth2-proxy

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

​

Traefik (Forward Auth使用時)

{
  gateway: {
    bind: "lan",
    trustedProxies: ["172.17.0.1"], // TraefikコンテナのIP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

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

• 経路の限定: ゲートウェイのポートが、プロキシ以外からのアクセスをファイアウォールで遮断していること
• trustedProxies の最小化: サブネット全体ではなく、実際のプロキシIPのみを指定していること
• プロキシによるヘッダーの制御: プロキシがクライアントからの x-forwarded-* ヘッダーを（追加ではなく）上書きしていること
• TLS終端: プロキシがTLSを処理し、ユーザーがHTTPS経由で接続していること
• allowUsers の設定（推奨）: 認証された全員を許可するのではなく、既知のユーザーのみに制限していること

​

セキュリティ監査

• trustedProxies 設定の欠落
• userHeader 設定の欠落
• allowUsers が空（すべての認証済みユーザーを許可している状態）

​

トラブルシューティング

​

”trusted_proxy_untrusted_source”

• プロキシのIPが正しいか（DockerコンテナのIPは変わる場合があります）
• プロキシの前段にロードバランサーがないか
• docker inspect や kubectl get pods -o wide を使用して実際のIPを確認してください

​

”trusted_proxy_user_missing”

• プロキシが識別情報をヘッダーとして渡すように設定されているか
• ヘッダー名が正しいか（大文字小文字は区別されませんが、綴りに注意してください）
• ユーザーが実際にプロキシ側で認証されているか

​

”trusted_proxy_missing_header_*”

• プロキシ設定でそれらのヘッダーが正しく設定されているか
• 通信経路のどこかでヘッダーが削除されていないか

​

”trusted_proxy_user_not_allowed”

​

WebSocket が依然として失敗する場合

• WebSocketのアップグレード（Upgrade: websocket, Connection: upgrade）をサポートしていること
• HTTPリクエストだけでなく、WebSocketアップグレードリクエストでも識別情報ヘッダーを渡していること
• WebSocket接続に対して、個別の認証経路が設定されていないこと

​

トークン認証からの移行

1. ユーザーを認証し、ヘッダーを渡すようにプロキシを設定する
2. プロキシ設定を単体でテストする（curlなどでヘッダーを確認）
3. OpenClawの設定を trusted-proxy 認証に更新する
4. ゲートウェイを再起動する
5. Control UIからWebSocket接続をテストする
6. openclaw security audit を実行し、内容を確認する

​

関連情報

• セキュリティ — セキュリティガイド全般
• 設定 — 設定リファレンス
• リモートアクセス — その他のリモートアクセスパターン
• Tailscale — テールネット限定アクセスのためのよりシンプルな代替案