Claude apps gatewayの使い方 — SSOで複数クラウドを統合

Claude apps gatewayは何を解決するか

Claude apps gatewayは、開発者のClaude Codeとモデルプロバイダーの間に立つセルフホスト型サービスです。claudeバイナリに含まれているため、claude gateway --config gateway.yamlを実行するだけで、ノートPCでClaude Codeを動かすのと同じ実行ファイルがゲートウェイサーバーとして立ち上がります。

開発者はAPIキーやクラウドの認証情報を持たず、企業のIDプロバイダー(IdP)でサインインします。ゲートウェイが上流の認証情報を保持し、IdPグループ単位でモデルアクセスとmanaged settingsを強制し、利用状況のテレメトリを組織自身の可観測性スタックへ中継します。上流にはAmazon Bedrock・Claude Platform on AWS・Google Cloud's Agent Platform・Microsoft Foundry・Anthropic APIを選べ、複数を組み合わせたフェイルオーバーにも対応します。

データレジデンシー要件で自社クラウド経由の推論が必須、あるいは必須ではないが望ましいという組織向けの機能です。そうした要件が無く、SCIMプロビジョニングやWeb・モバイル版のClaude Codeも使いたいのであれば、Claude Enterpriseの方が適していることもあります。社内にすでに別のLLMゲートウェイがあり、そちらを継続すべきか迷う場合は選び方の比較を先に確認しておくと、この構築が自組織に合っているかを判断しやすくなります。

前提条件

プライベートアドレス限定の制約は意図的なガードレールです。信頼されたゲートウェイは開発者端末でコマンドを実行できる設定を配布できるため、公開アドレスに置くと第三者からの悪用経路になります。

ステップ1: OAuthクライアントをIdPに登録する

先にゲートウェイのホスト名を決めます。リダイレクトURIがそのホスト名に一致する必要があるためです。IdP側で新しいOIDC Webアプリケーションを作成し、リダイレクトURIをhttps://<gatewayのホスト>/oauth/callbackに設定して、発行されたclient_idとclient_secretを控えます。

ステップ2: PostgreSQLを用意する

Postgres 14以降であればマネージドサービスの最小プランでも構いません。ゲートウェイは起動時に自分のスキーマをマイグレーションするため、データベースロールにはテーブルの作成・変更権限が必要です。

ステップ3: gateway.yamlを書く

最小構成は5つのセクションだけで、それ以外の項目にはすべて既定値があります。シークレットは${ENV_VAR}展開で読み込むため、設定ファイル自体はバージョン管理に置けます。

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
 
oidc:
  issuer: https://login.example.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
 
session:
  jwt_secret: ${GATEWAY_JWT_SECRET}
  ttl_hours: 1
 
store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
 
upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}

この設定だけでAmazon Bedrockの既定モデルカタログを使ったサインインが動きます。Bedrockの上流にはbedrock:InvokeModelとbedrock:InvokeModelWithResponseStreamをinference-profile/us.anthropic.*とfoundation-model/anthropic.*の両方のARNに持つAWSプリンシパルが必要です。静的キーよりIRSA・ECSタスクロール・EC2インスタンスプロファイルでの認証情報供給が推奨されます。IdPグループ別のRBAC・managed settings・複数上流のフェイルオーバーは、この最小構成を土台に追加していきます。

Note: 対象アカウントでBedrockコンソールのモデルカタログから一度だけ利用申請フォームを提出しておく必要があります。IAMの権限設定だけでは呼び出せず、この申請が承認されていないとゲートウェイ起動後の推論リクエストが拒否されます。

ステップ4: 起動して確認する

claudeバイナリを含むコンテナイメージをビルドし、Postgresと一緒に起動します。ゲートウェイは設定を読み込み、Postgresへ接続してスキーママイグレーションを適用し、IdPに対してOIDCディスカバリーを実行し、上流クライアントを構築してからリッスンを始めます。設定・Postgres接続(5秒タイムアウト)・OIDCディスカバリー・上流クライアント構築のいずれかが失敗すると、ゲートウェイは劣化した状態でトラフィックを受け付けるのではなく、エラーを出して終了します。コンテナ化せず直接実行して動作確認する場合は、listenをループバックまたはクラスタ内部アドレスに束ねてから外部公開の設定に進みます。

起動を確認する検証は3段階です。まずディスカバリードキュメントを取得してゲートウェイが起動し設定が有効であることを確認します。次にデバイス認可をリクエストしてPostgresが書き込み可能であることを確認します。最後にブラウザで検証URLを開いてIdPのサインイン画面にリダイレクトされ、サインイン後にゲートウェイへ戻ってくることを確認します。3つ目のチェックでIdPまで到達できない場合はリダイレクトURIの不一致、IdPまで到達してエラーで戻る場合はゲートウェイの監査ログに拒否理由(許可されていないメールドメイン等)が記録されています。

起動が成功しても推論経路までは検証されない点に注意します。BedrockとGoogle Cloud's Agent Platformのインスタンス認証情報は起動時ではなく最初のリクエストで解決されるため、起動確認の3段階を通過した後も、実際にモデルへリクエストを送るまでは上流の認証情報が正しいかどうかは分かりません。

ステップ5: 開発者をサインインさせる

開発者端末のmanaged settingsファイルでforceLoginMethodを"gateway"に、forceLoginGatewayUrlをゲートウェイのpublic_urlに設定します。この状態で/loginを実行すると、Cloud gateway画面がURL入力済みの状態で直接開きます。開発者はこの画面でEnterキーを押し、ブラウザでのサインインを完了させます。この2つのキーは開発者自身の設定ファイルでは無視される仕組みになっており、配布用のmanaged settingsに書かない限り、開発者が手動でゲートウェイサインインを設定することはできません。

CLIはゲートウェイのTLSサーバー証明書をホスト名ごとに初回接続時にフィンガープリント認証(pinning)します。/loginのプロンプトにはフィンガープリントの先頭16文字が小文字16進数で表示されるため、管理者はゲートウェイURLと一緒にこの値を周知し、開発者が照合できるようにします。証明書をローテーションするたびに全開発者がこの信頼プロンプトを再度目にするため、ローテーションは計画されたイベントとして扱います。

複数クラウドをどうまとめるか

upstreamsブロックは複数のプロバイダーを並べてフェイルオーバーさせられます。リージョンやプロバイダーを切り替えても、開発者は気づかずゲートウェイの背後で変更が適用されます。モデルアクセスはIdPグループ単位でavailableModels許可リストにマッピングされ、ゲートウェイがサーバー側で許可されていないモデルへのリクエストを拒否します。

Claude Desktopもこのゲートウェイに接続できます。ただしbootstrapUrlという別のMDMキーを使い、ポリシー側でdesktopキーによるオプトインが必要です。Desktop側のこのSSOは、claude.aiアカウントのTeam・Enterprise向けSSOとは別の仕組みで、IdPの識別情報をゲートウェイ経由で受け取る点が異なります。サインインしたユーザーはCowork・Codeタブ(既定で有効)からのモデルリクエストがゲートウェイを通るようになり、Chatタブも設定で有効化できます。

使えない機能・制限

一方で標準のプロンプトキャッシュ・Auto mode(サードパーティプロバイダーのルールに従う対象モデルのみ)・IdPグループ単位のモデルアクセス統制・OTLPテレメトリのファンアウトは利用できます。

よくあるつまずき

• パブリックアドレスでの拒否: /loginはゲートウェイのホスト名が解決する全アドレスをチェックし、1つでも公開アドレスなら拒否します。VPNや内部ロードバランサーの背後に置く前提を崩さないようにします
• CIパイプラインでの誤用: ゲートウェイのサインインはブラウザのデバイスフローのみでサービストークンが無いため、承認する開発者がいないCIジョブは認証できません。こうしたパイプラインはプロバイダーへの直接構成(/setup-bedrockウィザードのような手順)に切り分けます
• Desktopだけの端末でのegress抜け: Claude Desktopしか動かさない端末では、モデル一覧とツール無効化リストはDesktopが自分で適用しますが、egress許可リスト(WebFetchのドメインルールやサンドボックスのネットワークルール)は親プロセスの設定としてしか届きません。parentSettingsBehavior: "merge"のオプトインを入れ忘れると、この制限が効かないまま気づかれずに動き続けます
• 証明書ローテーションの周知漏れ: TLS証明書を更新すると全開発者に信頼プロンプトが再表示されるため、事前周知なしに更新すると「不審な警告が出た」という問い合わせが集中します

よくある質問

開発者ごとの支出上限は設定できますか

設定できます。ユーザー単位・グループ単位の支出上限がゲートウェイの機能として用意されており、暴走したワークロードが組織全体の契約枠を食いつぶすのを防げます。支出上限を使う構成では、Postgresが短命な認証状態だけでなく支出・監査・IDの永続テーブルも保持するため、バックアップの対象に含めます。

組織はどこまで利用状況を見られますか

利用状況テレメトリには開発者の識別情報・トークン数・モデル・レイテンシが組織のコレクターに届きますが、ゲートウェイ自体はプロンプトや応答の内容をログにも保存にも残しません。ログやトレースのようなより詳細なテレメトリを収集するかどうかは、転送先ごとに組織が選べる設定です。個々のセッションが枯渇や異常なリトライを起こしていないかを追う運用は、retry exhaustionの検知で扱っている考え方がそのまま当てはまります。

まとめ

Claude apps gatewayは、OAuthクライアントの登録・PostgreSQLの用意・5セクションだけのgateway.yaml・起動確認の3段階チェック・開発者のSSOサインインという流れで、複数クラウド上流をSSO1本にまとめられます。データレジデンシー要件が主目的でなければClaude Enterpriseの方が適する場合もあるため、導入前にどちらの要件に該当するかを確認しておくと構築の手戻りを避けられます。