Claude apps gateway のデプロイと運用

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

​

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

• /.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 エンドポイントから提供します

• 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 } を設定します。

​

デプロイ

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

• provider: anthropic 以外のすべての上流では、ゲートウェイはストリームが約 15 秒間サイレント状態になった後、SSE ping を 1 回書き込みます。
• provider: anthropic では、ゲートウェイは Anthropic API 独自の ping を含む応答をそのまま渡します。

​

コンテナイメージ

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 を開発者マシンにプッシュする

​

大規模なロールアウト

• ゲートウェイはロードバランサーを超えて見ることができません。 listen.trusted_proxies がない場合、すべての開発者はロードバランサーのアドレスから来ているように見え、1 つの制限を共有します。他の何よりも先にそれを設定します。ゲートウェイは、X-Forwarded-For ヘッダーを無視する最初の時間に警告をログに記録します。
• 多くの開発者が少数の NAT または VPN エグレスアドレスを共有しています。 trusted_proxies が正しい場合でも、それらのアドレスの制限を共有します。rate_limits を引き上げて適合させます。

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

​

運用

​

ログ

• 監査イベント：セキュリティ関連イベントごとの単一行 JSON。stderr をログアグリゲーターにパイプします。 発行されるイベントには config.load、session.mint、session.refresh、device.authorize、device.verify、device.callback、auth.denied、access.denied、access.public_client、inference、managed.serve、desktop_bootstrap.serve、desktop_bootstrap.denied、spend.blocked、admin.denied、admin.limit.upsert、admin.limit.delete が含まれます。フィールドはイベントによって異なります：
  • 成功した mint と refresh イベントは sub、email、client_ip、結果を含みます
  • auth.denied と access.denied は理由とクライアント IP を含み、auth.denied ではリクエストパスも含みます。拒否時にはユーザーアイデンティティが存在しないため。2 つの access.denied 理由はイベントが何を含むかを変更します：
    • xff_unparseable：イベントは読み込めなかった X-Forwarded-For エントリも含みます
    • client_ip_unknown：イベントはクライアント IP を含みません。接続にピアアドレスがなく、access_control リストが設定されていたため
  • access.public_client は、access_control.allow_cidrs が空の場合、プロセスごとに最初に公開アドレスから到着したリクエストのクライアント IP を含みます。ゲートウェイはリクエストを通常通り提供します。イベントは、ゲートウェイが公開インターネットから到達可能である可能性があることを示します。公開と見なされるもの、および推奨される許可リストについては、access_control リファレンス を参照してください。
  • inference は、どの上流がリクエストを提供したか、応答ステータスを記録します
  • desktop_bootstrap.denied は、拒否された Claude Desktop ブートストラップフェッチを理由（not_configured、policy_not_opted_in、no_policy_matched）とユーザーのアイデンティティで記録します
  • admin.denied は、拒否された admin-API 認証試行をクライアント IP、メソッド、パス、理由で記録します。提示されたキーマテリアルなし：x-api-key が提示されたが設定されたキーと一致しなかった場合は invalid_key、Authorization ヘッダーのみが提示され、ゲートウェイセッションとして admin.admin_groups で検証されなかった場合は bearer_rejected、どちらのヘッダーも提示されなかった場合は no_credentials
• 運用ログ：ブート、警告、上流エラーの人間が読める [gateway] プレフィックス付きの行。CLAUDE_GATEWAY_LOG_LEVEL 環境変数は詳細度を制御し、debug、info、warn、error を受け入れます。デフォルトは info です。debug では、各サインインと更新は id_token のクレーム名（値ではなく）もログに記録され、userinfo_fallback が提供した場合は userinfo クレーム名もログに記録されるため、PII をログに記録することなく email_claim と groups_claim 設定を診断できます。監査イベントには影響しません。常に発行されます。

​

ヘルス

​

同時上流リクエスト

• レプリカを追加します。
• 各レプリカの制限を上げます。ゲートウェイコンテナで BUN_CONFIG_MAX_HTTP_REQUESTS 環境変数を 1 から 65535 の整数に設定し、コンテナを再起動します。

​

障害時の動作

• 既存セッション：ベアラートークンは JWT シークレットでローカルに検証され、セッション更新はストアに触れず、ゲートウェイプロセスは引き続き推論を提供できます
• 新しいサインイン：Postgres が回復するまで失敗します。デバイスフローとそのレート制限カウンターは Postgres に存在するため
• 支出制限の実装：デフォルトでは障害中に失敗してオープンになるため、推論は引き続き流れます。ブロックするのを好む場合は、失敗を閉じるようにフリップします
• Readiness：デフォルトでは /readyz は Postgres が到達不可能になるとすぐに not-ready を報告するため、すべてのレプリカが一度にその readiness チェックに失敗します。トラフィックがチェックに合格するレプリカにのみ到達する場合、ゲートウェイが引き続き提供できる推論を含むすべてのトラフィックは、Postgres が回復するまで失敗します。/healthz の liveness プローブは全体を通じて合格し続けます。

​

Readiness グレースピリオド

​

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

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

​

Postgres

​

アップグレード

• ドレインウィンドウ：ゲートウェイコンテナで CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS 環境変数を 120000 などのミリ秒の正の整数に設定します。ゲートウェイは 120s などの他の形式の値を無視し、25 秒のデフォルトを保持します
• オーケストレーターのグレースピリオド：Kubernetes の terminationGracePeriodSeconds、または Amazon ECS の stopTimeout

• Amazon ECS on Fargate：stopTimeout は最大 120 秒を許可します
• Cloud Run：SIGTERM の 10 秒後にインスタンスを停止するため、開いているストリームはドレインウィンドウが何であれ最大 10 秒を取得します

​

セキュリティ

​

データフロー

​

脅威モデルの概要

• 開発者は生の上流キーの代わりに短命の JWT を保持します。CLI からゲートウェイへのレッグは RFC 8628 デバイスグラントを使用し、ゲートウェイの IdP との認可コード交換はデフォルト設定で PKCE を実行するため、インターセプトされた IdP 認可コードは無用です。
• デバイス検証ページは同一オリジン POST と RFC 8628 §5.1 ごとの IP ごとのレート制限を実装します。ユーザーコードブルートフォース耐性 を参照してください。
• ゲートウェイの IdP、OTLP コレクター、および provider: anthropic 上流へのリクエストは、サーバー側リクエストフォージェリ（SSRF）ガードを通じて行われます。DNS を解決し、リンクローカルとクラウドメタデータアドレスをブロックし、デフォルトではループバックをブロックし、接続を解決された IP にピン留めするため、オペレーター影響 URL はクラウドメタデータエンドポイントにリダイレクトできません。RFC 1918 プライベート範囲は意図的に許可されます。IdP と OTLP コレクターは一般的にプライベート IP に存在するため。その他のプロバイダーの場合、ゲートウェイは設定をロードするときにそれらのアドレスまたはメタデータホスト名を指定する base_url を拒否し、プロバイダーの SDK は DNS チェックなしで接続します。 プロキシのみのエグレス をオンにすると、そのアドレスチェックはフォワードプロキシに移動します：ゲートウェイはホスト名を渡し、プロキシのアロウリストはそれらの宛先を拒否する必要があります。 ゲートウェイが正当に到達する必要があるもの（ローカル開発 IdP やサイドカー OTLP コレクター（localhost など））がループバック上に存在する場合にのみ、ゲートウェイの環境で CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 を設定します。変数はすべてのオペレーター設定 URL のループバックブロックを緩和し、ポッドがクラウドメタデータエンドポイントに到達できるかどうかをチェックするブート時警告もスキップするため、コレクターに独自の内部アドレスを与えることをお勧めします。

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

​

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

​

コンプライアンス体制

• データレジデンシー：ゲートウェイ自体のデータプレーンは、Anthropic API が設定された上流の場合を除き、Anthropic に何も送信しません。その場合、既存のデータ処理契約が推論パスに適用されます。テレメトリ、監査、アイデンティティ、設定は設定した宛先にのみ行きます。
• ホストプロセストラフィック：ホストプロセスは Claude Code CLI です。claude gateway は Amazon Bedrock および Google Cloud の Agent Platform デプロイメントと同じサードパーティルールの下で実行され、Anthropic に何も送信しません。v2.1.227 より前では、ホストプロセスは製品バージョンとプラットフォームなどのスタートアップテレメトリを送信していました。これはコンテナ環境で CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 を設定することでオフにできました。これらのリリースはまた、ボート時に本文または認証情報なしで 1 つの HEAD リクエストを https://api.anthropic.com の /api/hello に送信していました。または環境が ANTHROPIC_BASE_URL を設定した場合はそれに、環境が HTTPS_PROXY などのプロキシ変数または mTLS クライアント証明書も設定していない限り。彼らは応答を無視したため、エグレスファイアウォールでそのリクエストをブロックしてもゲートウェイに影響しませんでした。
• クライアント分析：CLI はゲートウェイにサインインしている間、独自の使用分析とエラー報告を無効にします。最初のサインイン前に、CLI はまだ Anthropic にスタートアップイベントを送信します。これには、管理設定がゲートウェイサインインを強制するマシンも含まれます。これらもオフにするには、ゲートウェイサインインを強制する同じ クライアント側管理設定 で DISABLE_TELEMETRY を配信します。
• エラー報告：CLI はモデルリクエストが Anthropic のファーストパーティ API 以外のエンドポイント（Amazon Bedrock やカスタム ANTHROPIC_BASE_URL など）に行くときはいつでもエラー報告をオフにします。
• クライアントマシン：開発者の CLI は、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 と skipWebFetchPreflight: true が設定されていない限り、WebFetch ホスト名チェックとバージョンチェックを Anthropic に送信し続けます。データ使用 を参照してください。
• サーベイ評価：ゲートウェイにサインインしている間、CLI は 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 を設定します。
• 脆弱性開示：セキュリティ問題の報告 に従います

​

トラブルシューティング

• Gateway の問題: gateway の stderr（該当するウィンドウの）、gateway.yaml（シークレットは削除）、gateway のバージョン（ランディングページの / と /managed/settings の x-cc-gateway-version レスポンスヘッダーに表示）、および最近の変更内容
• ログイン問題: 開発者が claude --debug-file ./claude-debug.txt を実行して再現し、そのファイルと同じウィンドウの gateway の監査ログを送信
• 推論の問題: リクエストされたモデル、設定されたアップストリーム、およびリクエストの gateway 監査ログ（どのアップストリームがそれを処理したか、およびレスポンスステータスを記録）

​

関連

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