Claude apps gateway のデプロイと運用

このページでは、Claude apps gateway の運用側について説明します。ID プロバイダー（IdP）で OAuth クライアントを登録し、ゲートウェイをコンテナとしてデプロイし、日々運用します。ゲートウェイが起動時に読み込む gateway.yaml ファイルのすべてのオプションについては、設定リファレンス を参照してください。 本番環境のデプロイメントは順序立てた 4 つのステップに従い、以下のセクションがそれに対応しています。最初の 2 つは選択を行う場所です。後の 2 つは、実行中に参照するリファレンス資料です。

1. ID プロバイダーをセットアップする：OAuth クライアントを登録し、Okta、Entra、Google の IdP 固有の注記を確認します
2. ゲートウェイをデプロイする：ピン留めされたコンテナイメージをビルドし、Kubernetes、Cloud Run、または独自のプラットフォームで実行します。このセクションではコスト、バイパス、複数ゲートウェイ、サーバーレスの決定についても説明します
3. 運用をセットアップする：ログ、ヘルスプローブ、障害時の動作、シークレットローテーション、アップグレード。監視とランブックを配線するときに参照するリファレンス
4. セキュリティ体制を確認する：データがどこを流れるか、脅威モデル、コンプライアンスの回答。セキュリティレビュー用のリファレンス

サインインまたはブート中に失敗が発生した場合は、トラブルシューティング に直接進んでください。これは表示されるエラーに基づいてキー付けされています。

​

ID プロバイダーのセットアップ

単一のリダイレクト URI https://<gateway>/oauth/callback を持つ機密 OAuth/OpenID Connect（OIDC）ウェブアプリケーションを ID プロバイダーに登録し、ゲートウェイアクセスを持つべきユーザーまたはグループに割り当てます。 任意の OIDC 準拠 IdP が機能します：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate など。IdP は 3 つの要件を満たす必要があります：

• /.well-known/openid-configuration を提供します。本番環境では HTTPS 経由です。ゲートウェイは http:// issuer を受け入れ、ループバック issuer は追加で CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 が必要です
• 認可コードフローをサポートします。PKCE（Proof Key for Code Exchange）はデフォルトで有効です。サポートしない IdP の場合は oidc.use_pkce: false で無効にします
• id_token で email と必要に応じて groups を返すか、oidc.userinfo_fallback: true で userinfo エンドポイントから提供します

プライベート PKI の場合は、oidc.ca_cert_pem を設定します。 いくつかのプロバイダーはメールとグループクレームを異なる方法で処理します：

• Okta：https://example.okta.com の org 認可サーバーは、email と groups を省略した薄い id_token を返すため、issuer として使用する場合は常に oidc.userinfo_fallback: true を設定します。https://example.okta.com/oauth2/default などのカスタム認可サーバーは、id_token に email と必要に応じて groups を含め、直接発行し、フォールバックは不要です。Okta は oidc.scopes で groups スコープがリクエストされ、アプリのグループクレームフィルターが許可する場合にのみ groups を発行します。userinfo_fallback は IdP がリクエストされなかったクレームを埋めることはできません。
• Microsoft Entra ID：issuer = https://login.microsoftonline.com/<tenant-id>/v2.0。Entra はグループ名ではなくグループオブジェクト ID を発行するため、managed.policies.match.groups で GUID を使用するか、人間が読める名前のためにアプリロールを使用します。テナントが groups の代わりに roles の下でロールを発行する場合は、oidc.groups_claim: roles を設定します。
• Google Workspace：issuer = https://accounts.google.com。Google の id_token はグループを含みません。Google を IdP として、グループベースの allowed_groups または managed.policies を使用するには、oidc.google_groups を設定します。これは、ドメイン全体の委任を持つサービスアカウントを使用して Admin SDK Directory API を通じて各ユーザーのグループを検索します。これなしで、メンバーシップゲーティングに oidc.allowed_email_domains を使用し、ポリシー割り当てに managed.policies.match.email_domain を使用します。Google は標準の offline_access スコープも無視します。リフレッシュトークンの場合は、oidc.scopes: [openid, profile, email] と oidc.extra_auth_params: { access_type: offline, prompt: consent } を設定します。

上記で説明されていない ID プロバイダーのサポートについては、トラブルシューティング を参照してください。

​

デプロイ

ゲートウェイは単一の Linux バイナリです。レプリカはステートレスで Postgres が共有調整層であるため、水平にスケーリングします。環境内でステートレスサービスを実行する方法で実行します。このセクションの残りは、イメージが必要とするもの、Kubernetes と Cloud Run の短い注記を述べています。 ゲートウェイは、上流の認証情報を保持し、推論の単一の出口ポイントとして機能するため、ネットワーク内で実行するように設計されています。開発者と IdP が HTTPS 経由で到達できる任意の場所で実行でき、本番認証情報を保持する他のサービスと同様に扱います。 デプロイメントを実行する場所を超えて形作るいくつかの決定があります：

• コスト：ゲートウェイの個別ライセンスまたはシートごとの料金はありません。これは claude バイナリの一部です。既存のクラウドまたは Anthropic コミットメントを通じて推論に対して支払い、コンテナのコンピュートとテレメトリコレクターを支払います。
• バイパス：ゲートウェイは、モデルへの唯一のルートがそれを通過することを強制しません。独自の認証情報を持つ開発者は引き続きプロバイダーを直接呼び出すことができるため、そのパスを閉じることはネットワークポリシーの決定です。例えば、api.anthropic.com へのエグレスをゲートウェイ以外からブロックします。そのエグレスをブロックすると、各開発者のマシンから api.anthropic.com を呼び出す WebFetch ドメインセーフティチェック も破壊されます。管理ポリシーで skipWebFetchPreflight: true を設定して無効にします。
• 複数ゲートウェイ：各ゲートウェイは独自の設定を持つ個別のデプロイメントです。CLI はゲートウェイホスト名ごとに信頼フィンガープリントと認証情報を保存するため、異なるチームは競合なしに異なるゲートウェイに接続できます。複数の OIDC issuer を提供するには、個別のインスタンスを実行します。
• サーバーレス：Cloud Run は機能します。min-instances: 1 を設定して、コールド OIDC ディスカバリーを回避します。Lambda と Cloud Functions は機能しません。ゲートウェイは長時間実行 HTTP サーバーであるためです。

ここのすべての本番トポロジーは、L7 プロキシ（Ingress、Cloud Run のフロントエンド、ALB など）をプレーン HTTP レプリカの前に配置します。listen.trusted_proxies をプロキシのソース範囲に設定して、ゲートウェイが X-Forwarded-For からクライアント IP を読み込みます。ゲートウェイは TCP ピアが信頼されている場合にのみヘッダーを尊重します。Google Cloud の実装例 はトポロジーごとに具体的な値を持っています。信頼されたプロキシなしでは、すべてのリクエストはプロキシの IP から来ているように見え、IP ごとのレート制限を 1 つの共有バケットに折りたたみ、監査イベントにプロキシの IP を記録します。

​

コンテナイメージ

標準 Claude Code リリースのネイティブ claude バイナリの周りに独自のイメージをビルドします：

1. ピン留めされたリリースからイメージアーキテクチャの Linux ビルドをダウンロードします。ダウンロード URL については、特定のバージョンをインストールする を参照してください。
2. バイナリの整合性とコード署名 で説明されているように、リリースの GPG 署名付き manifest.json に対して検証します。
3. ビルドコンテキストにコピーします。

ビルドがリリースホストに到達できない場合は、リリースを内部レジストリにミラーリングし、フロートが実行するバージョンをピン留めします。 バイナリを超えて、イメージは以下が必要です：

• glibc ベースのイメージ：glibc ビルドの唯一の動的依存関係は glibc ライブラリです。Musl ベースのイメージは linux-x64-musl または linux-arm64-musl ビルドと追加パッケージが必要です。Alpine Linux セットアップ を参照してください。
• 書き込み可能な状態ディレクトリ：ゲートウェイは任意のユーザーとして実行されますが、最小限のイメージには書き込み可能なホームがありません。CLAUDE_CONFIG_DIR を /tmp/.claude などの書き込み可能なパスに設定します。
• コンテナコマンド：claude gateway --config /etc/claude/gateway.yaml。設定ファイルは読み取り専用でマウントされ、シークレットは環境変数として提供されます。ゲートウェイは listen.port でリッスンします。デフォルトは 8080 です。

​

Kubernetes

ゲートウェイをデプロイメントとして実行します。他のステートレスサービスと同様です：

• ConfigMap から設定をマウントし、Secret からシークレットをマウントします。YAML で ${file:/path/to/secret} または環境変数を通じてシークレットを参照します
• Ingress で TLS を終了し、listen.public_url を Ingress ホスト名に設定します
• readiness プローブを GET /readyz に、liveness プローブを GET /healthz に指定します

​

Cloud Run

サービスを以下のように設定します：

• listen.port をデフォルトの 8080 のままにします。これは Cloud Run のデフォルト PORT と一致するか、port: ${PORT} を設定します
• public_url を外部到達可能なオリジンに設定します。本番環境では、これは通常、内部ロードバランサーのホスト名です。/login は パブリックアドレスを拒否 し、*.run.app URL はそれに解決するため、Cloud Run URL だけは curl またはブラウザスモークテストにのみ機能します。例外は、*.run.app が Private Service Connect と Cloud DNS プライベートゾーンを通じてプライベートに解決するネットワークです。そのトポロジーでは、Cloud Run URL は有効な public_url です。Google Cloud の実装例 は両方をカバーしています。
• シークレットボリュームとして設定をマウントします
• min-instances: 1 を設定して、最初のリクエストでコールド OIDC ディスカバリーを回避します

​

ゲートウェイ URL を開発者マシンにプッシュする

ゲートウェイがサービスを提供したら、MDM を通じて、または OS ごとの managed-settings.json を直接書き込むことで、管理設定を通じて各開発者のマシンに forceLoginMethod と forceLoginGatewayUrl をプッシュします。これなしでは、/login はゲートウェイオプションなしで標準アカウントピッカーを表示します。ファイルパスについては、クライアント側の管理設定 を参照してください。

​

運用

ゲートウェイがトラフィックを提供したら、日々の運用はそのログを読み込み、その健全性をプローブし、スケジュールに従ってシークレットをローテーションすることです。サブセクションは各々をカバーし、Postgres が保持するもの、アップグレードとロールバックがどのように動作するかをカバーします。

​

ログ

ゲートウェイは stderr に 2 つのストリームを書き込みます。両方とも JSON フレンドリーです：

• 監査イベント：セキュリティ関連イベントごとの単一行 JSON。stderr をログアグリゲーターにパイプします。発行されるイベントには config.load、session.mint、session.refresh、device.authorize、device.verify、auth.denied、access.denied、inference、managed.serve、spend.blocked、admin.denied が含まれます。フィールドはイベントによって異なります：
  • 成功した mint と refresh イベントは sub、email、client_ip、結果を含みます
  • 拒否イベントは理由、パス、クライアント IP を含みます。拒否時にはアイデンティティが存在しないため
  • inference は、どの上流がリクエストを提供したか、応答ステータスを記録します
  • admin.denied は、拒否された admin-API 認証試行を理由（invalid_key または no_credentials）、クライアント IP、メソッド、パスで記録します。提示されたキーマテリアルなし
• 運用ログ：ブート、警告、上流エラーの人間が読める [gateway] プレフィックス付きの行。CLAUDE_GATEWAY_LOG_LEVEL 環境変数は詳細度を制御し、info、warn、error を受け入れます。デフォルトは info です。監査イベントには影響しません。常に発行されます。

​

ヘルス

ゲートウェイは GET /healthz を liveness プローブとして、GET /readyz を readiness プローブとして提供します。/readyz はストアが到達可能であることを検証します。両方とも access_control.allow_cidrs から除外されるため、プローブはロックダウンされたリスナーで機能し続けます。 /.well-known/oauth-authorization-server の OAuth ディスカバリードキュメントは、設定ロード、OIDC ディスカバリー、上流クライアント構築、Postgres マイグレーションがすべて成功した後にのみ 200 を返すため、エンドツーエンドのブートチェックとしても機能します。 実行中のゲートウェイは、実行しているバージョンに一致する <public_url>/protocol でそれが受け入れるパスとリクエスト形状の説明も提供します。内容はリリース間で安定していません。

​

障害時の動作

Postgres がダウンした場合、ゲートウェイ自体はサインイン済みの開発者にサービスを提供し続け、新しいサインインは失敗します。開発者が実際に機能し続けるかどうかは、オーケストレーターが readiness をどのように処理するかに依存します：

• 既存セッション：ベアラートークンは JWT シークレットでローカルに検証され、セッション更新はストアに触れず、ゲートウェイプロセスは引き続き推論を提供できます
• 新しいサインイン：Postgres が回復するまで失敗します。デバイスフローとそのレート制限カウンターは Postgres に存在するため
• 支出制限の実装：デフォルトでは障害中に失敗してオープンになるため、推論は引き続き流れます。ブロックするのを好む場合は、失敗を閉じるようにフリップします
• Readiness：/readyz は障害中に not-ready を報告するため、readiness でトラフィックをゲートするオーケストレーターはすべてのレプリカを一度にローテーションから削除します。そのトポロジーでは、ゲートウェイが引き続き提供できる推論を含むすべてのトラフィックは、Postgres が回復するまでロードバランサーで失敗します。/healthz の liveness プローブは引き続き合格するため、レプリカは再起動されません。ストア障害を通じてサインイン済みの開発者が機能し続けるようにしたい場合は、readiness プローブを /healthz に指定します。コストは新しいサインインが引き続き ready を報告するレプリカに対して失敗することです。

IdP がダウンした場合、既存セッションは ttl_hours まで機能し、新しいログインと更新は失敗します。IdP が頻繁なメンテナンスウィンドウを持つ場合は、より長い ttl_hours を設定します。

​

JWT シークレットローテーション

既存セッションが有効なままになるように、3 つのステップで署名シークレットをローテーションします：

1. 新しいシークレットを生成します。session.jwt_secret 配列の前に付加します。
2. デプロイメントをロールします。新しいトークンは新しいシークレットで署名します。古いトークンは引き続き検証されます。
3. ttl_hours とマージンの後、古いシークレットを削除してもう一度ロールします。

ローテーションは、有効期限が切れる前にセッションを強制的に削除する唯一の方法でもあります。ベアラートークンは JWT シークレットに対してローカルに検証されるため、セッションごとの取り消しはありません。シークレットを完全に置き換え、配列に古いものを保持しないと、すべての未処理セッションが一度に無効になります。個別のオフボーディングの場合は、IdP でユーザーをプロビジョニング解除します。セッションは ttl_hours 内に終了します。

​

Postgres

ゲートウェイは 5 つのテーブルを保持し、すべてはブート時マイグレーションで作成されます： 30 秒ループは TTL を超えた kv 行を期限切れにし、1 時間のスイープは支出テーブルの保持ウィンドウを実装するため、何も無制限に成長しません。支出制限 が設定されていない場合、kv のみが書き込まれます。セキュリティポリシーがアプリケーションロールからの DDL を禁止する場合は、これらのテーブルと _migrations を管理ロールで事前作成し、各テーブルに SELECT, INSERT, UPDATE, DELETE をアプリロールに付与します。 支出制限が使用されている場合、失われたデータベースは失われた支出追跡とキャップを意味し、開発者の再ログインだけではないため、定期的なバックアップを実行します。保持を待つのではなく、出発した開発者を直ちに削除するには、DELETE FROM principal_emails WHERE principal = '<sub>' を直接実行します。これはメール、名前、グループを保持する唯一のテーブルを削除します。spend と admin_audit 行は疑似匿名 OIDC sub のみを参照します。

​

アップグレード

レプリカはステートレスであるため、ローリング再起動はいつでも安全です。ゲートウェイはブート時にスキーママイグレーションを実行します。つまり、新しいバイナリをデプロイするとデータベースが自動的にマイグレーションされます。データベースロールが DDL を実行できない場合は、スキーマを事前作成します。_migrations テーブルを現在のバージョンにシードします。そうしないと、CREATE TABLE を試みるブートが失敗します。 マイグレーションは追加のみであるため、より少ないマイグレーションを知っている以前のバイナリにロールバックするのは安全です。余分な行を無視します。ロールバックは YAML を古いバイナリのスキーマに対して再検証するため、新しいリリースで導入されたキーを採用した設定は古いバイナリでのブートに失敗します。ロールバックする前に新しいキーを削除します。 独自のイメージでゲートウェイのバージョンをピン留めするため、新しい Claude Code リリースのセキュリティ修正を含む修正は、ピンを更新して再デプロイするときにのみデプロイメントに到達します。ゲートウェイを、本番認証情報を保持する他のサービスに使用するのと同じパッチングケーデンスに含めます。

​

セキュリティ

このセクションは、セキュリティレビューが尋ねる質問に答えます：ゲートウェイを通じてどのデータが流れ、どこに行くか、設計が防御する攻撃、コンプライアンスアンケートに属する回答。

​

データフロー

​

脅威モデルの概要

ゲートウェイはネットワーク境界内に位置しますが、個々の開発者ラップトップは信頼されていないと見なされます。設計はこれを 3 つの方法で説明します：

• 開発者は生の上流キーの代わりに短命の JWT を保持します。CLI からゲートウェイへのレッグは RFC 8628 デバイスグラントを使用し、ゲートウェイの IdP との認可コード交換はデフォルト設定で PKCE を実行するため、インターセプトされた IdP 認可コードは無用です。
• デバイス検証ページは同一オリジン POST と RFC 8628 §5.1 ごとの IP ごとのレート制限を実装します。ユーザーコードブルートフォース耐性 を参照してください。
• アウトバウンドリクエストはサーバー側リクエストフォージェリ（SSRF）ガードを通じて行われます。DNS を解決し、リンクローカルとクラウドメタデータアドレスをブロックし、デフォルトではループバックをブロックし、接続を解決された IP にピン留めします。IdP と OTLP 宛先などのオペレーター影響 URL はクラウドメタデータエンドポイントにリダイレクトできません。RFC 1918 プライベート範囲は意図的に許可されます。IdP と OTLP コレクターは一般的にプライベート IP に存在するため。ローカル開発でループバック IdP またはコレクターに対して、CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 をゲートウェイの環境に設定します。本番環境では設定しないままにします。

独自のエグレス制御を追加する場合、ゲートウェイはワークロードアイデンティティなどのインスタンスメタデータ認証情報を使用するときはいつでもメタデータサーバーに到達する必要があります。 2 つの脅威は、インフラストラクチャを保護するためのものであるため、スコープ外です：

• 侵害されたゲートウェイホスト：ホストは上流認証情報を保持し、管理設定 をすべての接続された開発者に配布するため、ゲートウェイの設定の制御は MDM の制御に匹敵します。CLI の 1 回限りの承認ダイアログはシェル対応設定のサイレント変更を制限しますが、ホストセキュリティに置き換わりません。
• 悪意のある OIDC プロバイダー：プロバイダーはゲートウェイが信頼する id_token に署名するため、任意のアイデンティティを主張できます。IdP の検証と保護はあなたの責任です。

​

ユーザーコードブルートフォース耐性

開発者が /device 検証ページに入力する user_code は、20 文字のアルファベットから引き出された 8 文字です。これは 20⁸ または約 2.56×10¹⁰ の組み合わせを生成し、10 分後に期限切れになります。 ゲートウェイは rate_limits を通じて設定可能なデバイスグラントエンドポイントに IP ごとのレート制限を適用します。多くの開発者が単一の共有企業 NAT アドレスからサインインする場合は、制限を上げます。制限はサインインフローにのみ適用され、推論には適用されません。

​

コンプライアンス体制

• データレジデンシー：ゲートウェイ自体のデータプレーンは、Anthropic API が設定された上流の場合を除き、Anthropic に何も送信しません。その場合、既存のデータ処理契約が推論パスに適用されます。テレメトリ、監査、アイデンティティ、設定は設定した宛先にのみ行きます。
• ホストプロセストラフィック：ホストプロセスは Claude Code CLI です。スタートアップ分析と更新チェックを Anthropic に送信できます。厳密なエグレスデプロイメントの場合は、ゲートウェイのコンテナ環境で CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 を設定します。
• クライアント分析：CLI はゲートウェイにサインインしている間、独自の使用分析を無効にし、エラー報告はサードパーティ API サーフェスでデフォルトでオフです。
• クライアントマシン：開発者の CLI は、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 と skipWebFetchPreflight: true が設定されていない限り、WebFetch ホスト名チェックとバージョンチェックを Anthropic に送信し続けます。データ使用 を参照してください。
• サーベイ評価：ゲートウェイ認証情報は Anthropic バウンド評価シンクを無効にするため、評価は Anthropic に送信されません。
• トランスクリプト共有：サーベイのトランスクリプト共有プロンプトで「はい」を選択すると、Anthropic にアップロードする代わりに ~/.claude/feedback-bundles/ の下にローカルファイルを書き込みます。
• クライアント更新：更新チェックはゲートウェイトラフィックとは別です。独自の配布を通じてバージョンをピン留めし、ラップトップがリリースをフェッチしてはいけない場合は DISABLE_UPDATES を設定します。DISABLE_AUTOUPDATER はバックグラウンド更新のみを停止し、claude update は引き続き機能します。
• TLS：本番環境で public_url を HTTPS 経由で提供します。ゲートウェイ自体のリスナー経由で listen.tls を使用するか、プレーン HTTP レプリカの前の TLS 終了 ingress から listen.public_url を設定します。ゲートウェイはプレーン HTTP を拒否しません。IdP は本番環境で HTTPS を提供する必要があり、Postgres は ?sslmode=require をサポートします。ingress で Strict-Transport-Security を設定します。
• 脆弱性開示：セキュリティ問題の報告 に従います

​

トラブルシューティング

質問とフィードバックについては、Claude Code サポート を使用するか、Claude Code GitHub リポジトリ で issue を開きます。問題を報告するときは、以下を含めます：

• ゲートウェイの問題：関連するウィンドウのゲートウェイの stderr、シークレットが削除された gateway.yaml、ゲートウェイバージョン（/ のランディングページに表示、/managed/settings の x-cc-gateway-version レスポンスヘッダー）、最近変更されたもの
• ログイン問題：開発者は claude --debug-file ./claude-debug.txt を実行し、再現し、そのファイルとゲートウェイの同じウィンドウの監査ログを送信します
• 推論問題：リクエストされたモデル、設定された上流、リクエストのゲートウェイ監査ログ。どの上流がそれを提供したか、応答ステータスを記録します

ゲートウェイの stderr には監査イベントストリームが含まれ、監査ログには開発者の ID が記録され、デバッグファイルには開発者のマシンからの hook と MCP サーバーの出力が記録されます。公開 issue に投稿する前に、これらを確認して秘密情報を削除してください。

​

関連

• Claude apps gateway の概要：クイックスタートと開発者接続
• 設定リファレンス：すべての gateway.yaml オプション