Claude apps gatewayを実際に立てる手順と運用の要点

この記事の要点
- gateway は Postgres を使う単一のバイナリ。公開インターネットには置かず、社内の私的なアドレスから使わせる
- 手順は、IdPの登録、公開しないアドレスの決定、固定版のコンテナ作成、Kubernetes か Cloud Run への配置、利用者の端末への設定配布の順
- 運用では、ヘルスチェックの分離、Postgres停止時の動き、JWT秘密鍵の段階的な入れ替え、更新時の排出時間の設定がつまずきやすい
活用例:全社のClaude Codeの利用を、社内のゲートウェイ経由でログインさせて統制する
- 部署
- 情報システム・インフラ
- 使うもの
- Claude apps gateway・IdP・Postgres
- AIに任せる
- 設定ファイルの下書き・手順書の整理
- 人が決める
- どこに置くか・誰に使わせるか・停止時の方針
Claude apps gateway は、社内に立てる「Claudeの入口」です。ただ、立てる場所を間違えると、そもそもログインできません。 手順より先に、置き場所の決め方から押さえる必要があります。
この記事は、公式ドキュメント「Claude apps gateway deployment and operations」(2026年11月20日確認)にもとづいて、立てる手順と、動かし始めてから困りやすい点をまとめます。gateway の概要は gatewayの記事、使用量の上限の設定は 上限設定の記事、導入の進め方は LLMゲートウェイの展開の記事 をご覧ください。
結論:公開しない。順番は「IdP、アドレス、コンテナ、配置、配布」
公式は、本番の構築を4段階で示しています。IdPの登録、配置、運用の整備、セキュリティの確認です。このうち前半の2つが判断の要で、後半は動いたあとに参照する資料になります。
| 段階 | やること |
|---|---|
| 1. IdP | OAuthクライアントを登録し、IdPごとの癖を確認する |
| 2. 配置 | アドレスを決め、固定版のコンテナを作り、実行場所に置く |
| 3. 運用 | ログ、ヘルスチェック、停止時の挙動、鍵の入れ替え、更新を整える |
| 4. 安全 | データの流れ、脅威の想定、準拠の説明を確認する |
手順1:先にアドレスを決める(ここが最大の落とし穴)
Claude Code は、公開のIPアドレスに解決されるホスト名の gateway へのログインを拒否します。 外から届かなくても、公開アドレスなら拒否されます。理由は、gateway が利用者の端末へ、シェルコマンドを動かすフックを含む設定を送れるためです。誤って悪意のある gateway にログインさせないための確認です。
選び方は次の2通りです。
- 私的なアドレス:内部ロードバランサーやVPNの後ろに置き、ホスト名が私的なアドレス(RFC 1918 や 100.64.0.0/10)だけに解決されるようにする。利用者の端末の側は、どのアドレスでもよい
- 宣言したブロック:社内で自社所有の公開IPv4を使っているなら、そのブロックを gatewayInternalNetworks という管理設定に書く。gateway と端末の両方がそのブロックに入っている必要がある
どちらも当てはまらない場合は、gateway に私的なアドレスを与え直します。Cloud Run の既定のURLも公開アドレスなので、動作確認以外には使えません。
手順2:IdPにOAuthクライアントを登録する
登録するのは、秘密情報を持てる(confidential)OAuth/OIDC のウェブアプリケーションです。リダイレクトURIは1つで、gateway の /oauth/callback になります。使わせる人やグループに割り当てます。
IdPが満たす条件は3つです。OpenID の構成情報を配信している、認可コードの流れに対応している、id_token か userinfo から email(任意で groups)を返せる。主要なIdPの注意点は次のとおりです。
| IdP | 注意点 |
|---|---|
| Okta | 組織の認可サーバーは email と groups を id_token に載せない。userinfo_fallback を true にする。groups は scope で要求する必要がある |
| Microsoft Entra ID | グループはオブジェクトIDで返る。方針の条件にはそのID(GUID)を使う。ロールが roles に入る場合は groups_claim を roles にする |
| Google Workspace | id_token にグループが入らない。グループで制御するなら google_groups を設定するか、メールのドメインで制限する |
更新トークン(refresh token)が出せるかも確認します。更新トークンがあれば、再ログインなしでセッションが更新され、IdPで無効にされた人は次の更新で切れます。出せないIdPなら、session.ttl_hours を 8 か 12 に延ばして、ログインの頻度を下げます。代わりに、退職者の失効が遅れます。
手順3:固定版のコンテナを作る
イメージは、標準リリースの claude バイナリを包んで自分で作ります。
- 固定したリリースの Linux 版を取得する
- 公式の署名つき manifest.json で検証する
- ビルドの入力に入れる
そのほか、イメージには次が必要です。
- glibc 系のイメージ:musl 系なら、musl 用のビルドを使う
- 書き込める状態ディレクトリ:最小のイメージは書けるホームがない。CLAUDE_CONFIG_DIR を書ける場所に設定する
- 起動コマンド:claude gateway --config と設定ファイルのパス。設定は読み取り専用でマウントし、秘密情報は環境変数で渡す。待ち受けの既定は 8080
社内のレジストリに複製して版を固定します。 固定した版の修正は、あなたが版を上げて再配置しない限り届きません。他の本番サービスと同じ更新の周期に入れてください。
手順4:Kubernetes か Cloud Run に置く
どの基盤でも、前段にL7のプロキシ(Ingress、Cloud Run のフロント、ALB など)を置き、中は平文HTTPで動かす構成です。
- trusted_proxies を設定する:プロキシの送信元の範囲を入れる。入れないと、全員がプロキシのIPから来たように見え、IPごとの回数制限が1つの枠に潰れ、監査の記録にもプロキシのIPが残る
- ログインのエンドポイントはリダイレクトしない:デバイス認可とトークンのエンドポイントを、HTTPからHTTPSなどに転送すると、Claude Code が追従しないためログインと更新が壊れる
- プロキシの待機時間を長めにする:gateway は無音が約15秒続くと keepalive の ping を送る(anthropic 以外の上流)。ALBの60秒でも足りる
Kubernetes では、Deployment で動かし、設定は ConfigMap、秘密は Secret に置きます。TLS は Ingress で終わらせ、public_url に Ingress のホスト名を入れます。準備確認は /readyz、生存確認は /healthz に向けます。Cloud Run では、min-instances を 1 にして初回のOIDC探索の遅れを避け、設定は秘密のボリュームでマウントします。Lambda や Cloud Functions は、gateway が常駐のHTTPサーバーなので使えません。
手順5:利用者の端末へ配る
動き始めたら、管理設定(MDMか managed-settings.json)で forceLoginMethod、forceLoginGatewayUrl、parentSettingsBehavior を merge にして配ります。配ると、端末に残っていたAPIキーや claude.ai のログインは使われなくなります。 ログイン手順の案内とセットで配ってください。
大人数の展開では、ログインの回数制限が最初の朝に詰まります。既定は、IPごとに10分間でログイン開始30回、コード入力10回です。次の2つが原因になりやすいです。
- gateway がロードバランサーの先を見られない:trusted_proxies で解決する
- 多数の端末が少数のNATやVPN出口を共有している:rate_limits を上げる。目安は、1つの出口を共有する人数のうち10分間にログインする人数を見積もり、その2倍
運用の要点
停止時の動き
- Postgres が止まったら:ログイン済みの人は、トークンがJWT秘密鍵でその場で検証できるため使い続けられる。新しいログインは失敗する。上限の管理は、既定では検査を通す側(fail open)に倒れる
- 準備確認の罠:既定では、Postgres に届かなくなると全レプリカが一斉に未準備になり、トラフィックが全部止まる。短い切り替えをしのぐなら、store.readiness_grace_seconds を切り替え時間より長く(例:300)設定する。v2.1.282 以降が必要で、古い gateway は設定を見つけると起動を拒否する
- IdP が止まったら:既存のセッションは ttl_hours の間は動き、新しいログインは失敗する
JWT秘密鍵の入れ替え
- 新しい鍵を作り、session.jwt_secret の配列の先頭に足す
- 展開を更新する(新しいトークンは新しい鍵で署名され、古いトークンも検証できる)
- ttl_hours に余裕を足した時間が過ぎてから、古い鍵を消してもう一度更新する
入れ替えは、セッションを期限前に切る唯一の方法でもあります。個人の退職には、IdP側で無効にします。
Postgres
PostgreSQL 本体が必要で、Postgres 互換の分散データベースは対象外です。ゲートウェイの権限で表を作ったり変えたりするため、専用のデータベースやスキーマを用意します。表は5つで、デバイス認可と回数制限(kv)、支出の集計(spend)、上限(spend_limits)、管理操作の監査(admin_audit)、最後に見たメールと名前とグループ(principal_emails)です。最後の表には個人情報が入り、既定で最後の利用から90日保持されます。上限を使うなら、失うと追跡が消えるのでバックアップを取ります。
接続数は、レプリカ数と store.max_connections の掛け算です。更新中に増える分も足し、データベースの残りの接続数に収まるようにします。
更新
レプリカに状態はなく、ローリング更新で動きます。起動時にスキーマ移行が走り、複数のレプリカは Postgres のロックで順番に進みます。SIGTERM を受けると、新しい接続を止め、既存のものを最大25秒待って閉じます。長い生成を守るなら、CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS を増やし、オーケストレーターの猶予(Kubernetes の terminationGracePeriodSeconds など)を5秒以上長くします。Cloud Run は SIGTERM の10秒後に止めるため、そこまでです。
戻すときは、移行が追加のみなので古い版に戻せますが、新しい版で足したキーを設定から消さないと起動に失敗します。
展開前のチェックリスト
- [ ] gateway のホスト名が私的なアドレスだけに解決される(または宣言したブロックの内側)
- [ ] IdP に登録し、email と groups が取れる。更新トークンの有無を確認した
- [ ] 固定した版を検証してイメージにした。更新の担当を決めた
- [ ] trusted_proxies と、ログインのエンドポイントの転送なしを確認した
- [ ] 準備確認と生存確認を別に向けた
- [ ] Postgres の接続数を計算した。バックアップを取る
- [ ] JWT鍵の入れ替え手順と、更新時の排出時間を決めた
端末への配布の考え方は 管理設定の記事 もあわせてどうぞ。
まとめ
- gateway は公開せず、私的なアドレスの上で使わせる。アドレス設計を先に決める
- 順番は、IdPの登録、固定版のコンテナ、基盤への配置、端末への配布
- 運用の肝は、準備確認の猶予、JWT鍵の段階的な入れ替え、更新時の排出時間
- 固定版は自動では更新されないので、定期的に上げる
出典:Claude apps gateway deployment and operations(公式ドキュメント)
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


