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. IdPOAuthクライアントを登録し、IdPごとの癖を確認する
2. 配置アドレスを決め、固定版のコンテナを作り、実行場所に置く
3. 運用ログ、ヘルスチェック、停止時の挙動、鍵の入れ替え、更新を整える
4. 安全データの流れ、脅威の想定、準拠の説明を確認する

手順1:先にアドレスを決める(ここが最大の落とし穴)

Claude Code は、公開のIPアドレスに解決されるホスト名の gateway へのログインを拒否します。 外から届かなくても、公開アドレスなら拒否されます。理由は、gateway が利用者の端末へ、シェルコマンドを動かすフックを含む設定を送れるためです。誤って悪意のある gateway にログインさせないための確認です。

選び方は次の2通りです。

どちらも当てはまらない場合は、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 Workspaceid_token にグループが入らない。グループで制御するなら google_groups を設定するか、メールのドメインで制限する

更新トークン(refresh token)が出せるかも確認します。更新トークンがあれば、再ログインなしでセッションが更新され、IdPで無効にされた人は次の更新で切れます。出せないIdPなら、session.ttl_hours を 8 か 12 に延ばして、ログインの頻度を下げます。代わりに、退職者の失効が遅れます。

手順3:固定版のコンテナを作る

イメージは、標準リリースの claude バイナリを包んで自分で作ります。

  1. 固定したリリースの Linux 版を取得する
  2. 公式の署名つき manifest.json で検証する
  3. ビルドの入力に入れる

そのほか、イメージには次が必要です。

社内のレジストリに複製して版を固定します。 固定した版の修正は、あなたが版を上げて再配置しない限り届きません。他の本番サービスと同じ更新の周期に入れてください。

手順4:Kubernetes か Cloud Run に置く

どの基盤でも、前段にL7のプロキシ(Ingress、Cloud Run のフロント、ALB など)を置き、中は平文HTTPで動かす構成です。

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つが原因になりやすいです。

運用の要点

停止時の動き

JWT秘密鍵の入れ替え

  1. 新しい鍵を作り、session.jwt_secret の配列の先頭に足す
  2. 展開を更新する(新しいトークンは新しい鍵で署名され、古いトークンも検証できる)
  3. 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秒後に止めるため、そこまでです。

戻すときは、移行が追加のみなので古い版に戻せますが、新しい版で足したキーを設定から消さないと起動に失敗します。

展開前のチェックリスト

端末への配布の考え方は 管理設定の記事 もあわせてどうぞ。

まとめ

  1. gateway は公開せず、私的なアドレスの上で使わせる。アドレス設計を先に決める
  2. 順番は、IdPの登録、固定版のコンテナ、基盤への配置、端末への配布
  3. 運用の肝は、準備確認の猶予、JWT鍵の段階的な入れ替え、更新時の排出時間
  4. 固定版は自動では更新されないので、定期的に上げる

出典:Claude apps gateway deployment and operations(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事