実践導入ガイド

Claude Apps Gateway実践導入ガイド
OIDC設定・gateway.yaml解説

前提条件からgateway.yamlの書き方、認証フローの動作確認まで、実際にゼロから立ち上げる手順を解説します。

以前の記事で、企業向けにClaude Codeを一元統制するClaude Apps Gatewayの概要を紹介しました。本記事はその実践編として、実際にゲートウェイを構築するための前提条件・設定ファイルの書き方・起動確認手順まで具体的に解説します。

導入前提条件

必要なもの	詳細
Claude Code v2.1.195以降	ゲートウェイサーバー・開発者端末の両方でこのバージョン以上が必要
OIDC対応IDプロバイダー	Okta・Microsoft Entra ID・Google Workspace・Keycloak・Dexなど。SAML・LDAPは非対応
PostgreSQL 14以降	サインインフロー・レート制限カウンター・支出上限データを保持
モデルの接続先	Amazon Bedrock／Claude Platform on AWS／Google Cloud／Microsoft Foundry／Anthropic APIのいずれか（複数指定でフェイルオーバーも可能）
HTTPS	開発者端末・サインイン用ブラウザの両方から到達可能である必要がある
プライベートネットワークのアドレス	Claude Codeはゲートウェイのホスト名がプライベートIPにのみ解決されることを要求する（セキュリティガード）
Linux実行環境	サーバーはネイティブLinuxバイナリでのみ動作。macOSはローカル開発用、Windowsサーバーは非対応

「プライベートネットワークのみ」は意図的な制約

信頼されたゲートウェイは開発者端末上でコマンドを実行する設定をプッシュできるため、外部から到達可能な状態は重大なセキュリティリスクになります。内部ロードバランサーやVPNの内側に配置し、プライベートIPにのみ解決されるホスト名を割り当ててください。

セットアップ手順

STEP 1：IdPでOAuthクライアントを登録

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

STEP 2：PostgreSQLデータベースを準備

PostgreSQL 14以降であれば、最小構成の管理サービスでも動作します。ゲートウェイは起動時に自らスキーママイグレーションを実行するため、データベースユーザーにはCREATE TABLE権限が必要です。

STEP 3：gateway.yamlを作成

シークレットは${環境変数}展開で読み込まれるため、ファイル自体はバージョン管理下に置いて構いません。最小構成は5つのセクションです。

gateway.yaml（最小構成・Bedrock接続の例）

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]
  userinfo_fallback: true

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}
  ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}

auto_include_builtin_models: true

upstreamsのproviderを差し替えるだけで、Claude Platform on AWS・Google Cloud・Foundry・Anthropic APIのいずれにも対応できます。組織単位のロールベースアクセス制御（RBAC）やテレメトリー送信先などは、この最小構成が動いてから追加していく流れで問題ありません。

STEP 4：起動する

ゲートウェイはclaudeバイナリに組み込まれているため、専用のコンテナイメージを用意し、Docker ComposeなどでPostgreSQLと一緒に起動します。

docker-compose.yaml（抜粋）

services:
  gateway:
    image: <registry>/claude-gateway:<version>
    ports: ["8080:8080"]
    volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
    environment:
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
      GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }

起動時の検証は「フェイルクローズ」設計です。設定ファイル・PostgreSQL接続（5秒タイムアウト）・OIDCディスカバリー・アップストリームクライアントの構築のいずれかが失敗すると、劣化した状態でトラフィックを受け付けるのではなく、エラーで即座に終了します。

STEP 5：認証フローを検証する

開発者に渡す前に、3段階のチェックで動作確認します。

① ディスカバリードキュメントの確認

curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

② デバイス認可リクエストの確認

curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

③ 返ってきたverification_uri_completeをブラウザで開き、IdPのサインイン画面にリダイレクトされて認証後にゲートウェイへ戻ってくることを確認します。

いずれかが失敗した場合の切り分け方：

①が失敗：起動処理が完了していない。標準エラー出力を確認
②が失敗：PostgreSQLに到達できない、または書き込み権限がない
③でIdPに到達しない：IdP側のリダイレクトURIがhttps://<gateway>/oauth/callbackと完全一致しているか確認
③でIdPからエラーが返る：ゲートウェイの監査ログに拒否理由（例：許可されていないメールドメイン）が記録される

STEP 6：開発者をログインさせる

開発者端末のmanaged settingsファイルに以下を設定すると、/login実行時に自動でゲートウェイ経由のサインイン画面が開きます。

managed settings への追加設定

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

開発者はAPIキーやクラウド認証情報を一切持たず、社内アカウントでのブラウザサインインだけでClaude Codeを使えるようになります。

できること・できないこと

ゲートウェイ経由の接続では、一部のClaude Code機能が利用できません。事前に把握しておくべき主な制限は以下の通りです。

機能	状態	備考
推論のフォワーディング	✅利用可	Bedrock・Claude Platform on AWS・Google Cloud・Foundry・Anthropic APIに対応、フェイルオーバーも可
IdPグループ単位のモデルアクセス制御	✅利用可	サーバー側で強制。許可されていないモデルへのリクエストは拒否される
標準のプロンプトキャッシュ	✅利用可	`cache_control`は各アップストリームへ転送される
サーバー側のWeb検索	❌利用不可	CLIがどのアップストリームに接続されているか判別できないため無効化される
1時間キャッシュTTL	❌利用不可	全アップストリームが対応しているわけではないため、5分TTLに固定
マルチテナント（複数OIDC発行者）	❌非対応	1ゲートウェイにつき1つの発行者。複数必要な場合は別インスタンスを構築
SAML・LDAP認証	❌非対応	OIDCのみ対応
管理UI	❌なし	設定はYAMLファイルのみ。変更には再デプロイが必要