gatewayInternalNetworksとは — 自社IPのgatewayへのログイン許可

gatewayInternalNetworksでできること

gatewayInternalNetworksは、組織がパブリックIPv4ブロックで内部ネットワークを採番しているとき、/loginがそこにあるClaude apps gatewayへの接続を許可するための管理設定です。Claude Code v2.1.268以降が必要で、対象は開発者マシン側のバージョンになります。

この設定を入れなければ、/loginはプライベートアドレスのgatewayしか受け付けません。キャリア資産の/8のような、正規に割り当てられたパブリックIPv4を社内の採番に使っている組織は、既定のままではgatewayにサインインできません。このキーは、その例外を宣言したブロックだけに開けます。

自社のgatewayにこの設定が要るか

要否はgatewayのアドレスで決まります。

前者の構成で足りるなら、このキーに触る理由はありません。後者でも、gatewayをインターネットへ公開してよいことにはなりません。信頼されたgatewayは開発者マシン上でコマンドを実行する設定を配れるため、到達範囲はファイアウォールやロードバランサで閉じておく前提です。

設定方法

managed-settings.jsonに、対象のCIDRブロックを配列で指定します。

{
  "gatewayInternalNetworks": ["203.0.113.0/24"]
}

例の203.0.113.0/24はドキュメント用レンジで、実際には拒否されます。自社が保有するブロックに置き換えてください。

置く場所はOSごとに決まっています。macOSは/Library/Application Support/ClaudeCode/managed-settings.json、LinuxとWSLは/etc/claude-code/managed-settings.json、WindowsはC:\Program Files\ClaudeCode\managed-settings.jsonです。

どの管理ソースの値が読まれるか

gatewayInternalNetworksのスコープはManagedで、マシン上の管理ソースからしか読み込まれません。対象はmanaged-settings.json(とmanaged-settings.dのドロップイン)、macOSのplist、WindowsのHKLMレジストリ、ポリシーヘルパーです。HKCU(ユーザー単位のレジストリ)、server-managed settings、開発者自身のsettings.jsonに書いた値は無視されます。

管理ソースが複数あるときは、managedSourcesBehaviorの既定値"first-wins"のもとで、優先度の高いソースが1つだけ採用されます。順位は次のとおりです。

ここから起きやすい落とし穴が1つあります。ログインキーは「ポリシーキーを持つ最上位の管理ソース」から読まれます。MDMのplistに別のポリシーキーが1つでも入っていると、managed-settings.jsonにだけ書いたgatewayInternalNetworksは読まれません。追加したキーが効かないときは、まず採用されているソースを調べます。

1台のマシンで/statusを開き、Setting sourcesの行を読みます。Enterprise managed settings (file)ならmanaged-settings.json、(plist)や(HKLM)ならMDMのポリシー、(file + drop-ins)ならファイルとドロップインの両方が採用されています。採用されなかった管理ソースはSkipped sourcesの行に名前が出ます。Skipped sourcesの行はv2.1.242以降で表示されます。

「ファイルは配ったのに効かない」という報告では、ファイルが届いていないのか、上位のMDMに負けているのかをこの2行で切り分けられます。

値のバリデーションルール

配列で指定できるCIDRブロックは最大4つ、プレフィックス長は/8から/32です。/loginは接続前に次のルールでチェックします。

240.0.0.0/4のような、一部の大規模ネットワークが内部ユニキャスト用途に使うレンジは宣言できます。

managed-settings.json本体とドロップインのブロックは1つのリストに結合され、上限とルールは結合後のリストに適用されます。範囲を狭めたいときは、ドロップインに重複するブロックを足すのではなく、元のエントリを書き換えます。本体で203.0.113.0/24を宣言済みのとき、ドロップインに203.0.113.0/25を足すと、/loginは重複と判断して拒否します。

値が不正な場合(ルール違反、または文字列の配列でない値)は、そのマシンの新規gatewayサインインがすべて拒否され、/loginが問題箇所を名指しします。プライベートアドレスのgatewayへの新規サインインも同時に失敗します。すでに完了しているサインインは維持されます。

不正な型の値は、Claude Codeが報告する不正な管理設定の一覧にも載ります。Claude Codeのclaude doctorは、不正なエントリごとに出どころのソースとフィールドを示します。ログインキーは採用された最上位ソースからしか読まれないので、下位のソースに書いた値は、不正でもサインインに影響しません。展開前に1台のマシンで値を試すのが安全です。

/loginが接続前に行う3つのチェック

値がバリデーションを通っても、宣言したブロックの中にあるgatewayへ接続するときは、/loginが追加で3つの条件を見ます。

3つとも通ると、トラスト確認画面に開発者マシンのアドレス、gatewayのアドレス、該当するブロックの3点が表示されます。このチェックは宣言したブロック内のgatewayにだけ働きます。プライベートアドレスのgatewayや、宣言外のパブリックアドレスのgatewayの扱いは変わりません。

チェックが絞るのは「誰がサインインできるか」で、マシンの所在の証明ではありません。クラウド事業者の公開レンジのように複数のテナントが共有するブロックを宣言すると、同じブロックにいる無関係な第三者も同じ条件を通ります。宣言は、自社が単独で管理するアドレス空間に限ります。

3つの設定の役割の違い

gatewayInternalNetworks・forceLoginGatewayUrl・access_control.allow_cidrsは、gatewayのログイン周りでまとめて語られがちですが、役割は別々です。

gatewayInternalNetworksに宣言したブロックは、そのままgateway側のaccess_control.allow_cidrsにも設定します。そうすれば、gateway自身が宣言外のクライアントを断ります。ロードバランサやIngressの配下に置くなら、listen.trusted_proxiesもそのフロントエンドに設定してください。設定しないと、allow_cidrsは開発者マシンの実アドレスではなくフロントエンド自身のアドレスと照合されます。

片方だけ入れた場合の症状は対照的です。

• access_control.allow_cidrsだけを絞ると、/login側がそのブロックを許可していないので、開発者がサインインできません。症状が出るので気づけます。
• gatewayInternalNetworksだけを入れてallow_cidrsを空のままにすると、サインインは通ります。gatewayは宣言外のアドレスからのリクエストも受け付け続けます。

後者の抜けはgatewayの起動時ログに出ます。v2.1.268で、allow_cidrsが空のときの起動時警告が加わりました。プライベート範囲外のアドレスから最初のリクエストが届いたときにも、1回きりの警告が出ます。gatewayのログに警告が残っていないかを、展開後の点検項目にできます。

gateway本体はclaudeバイナリのサブコマンドとして動きます。v2.1.289のclaude gateway --helpは次のとおりです。

$ claude gateway --help
Usage: claude gateway [options]
 
Run the enterprise auth/telemetry gateway
 
Options:
  --config <path>  Path to gateway YAML config
  -h, --help       Display help for command

allow_cidrsやtrusted_proxiesは、この--configで渡すYAMLに書きます。gateway自体が晒すリスクの範囲はClaude apps gatewayの脅威モデルに、この構成をTerraformで組む場合の勘所はClaude apps gatewayをTerraformで構築するにまとまっています。

forceLoginGatewayUrl・forceLoginMethodとの関係

gatewayInternalNetworksは、gatewayへのログインを強制するforceLoginGatewayUrl・forceLoginMethodの"gateway"値と合わせて使うことが多い設定です。この3つは同じ「ログインキー」で、同じ管理ソースに置きます。開発者側で手動設定する経路はありません。ログインピッカーにgatewayの選択肢は出ず、forceLoginGatewayUrlを開発者自身のsettingsに書いても無視されます。

forceLoginMethodだけを置いてURLを置かないと、開発者には「Contact your IT administrator」のメッセージが出ます。gatewayのmanaged policiesのcliブロックに置いても届きません。このブロックが届くのは、すでに接続済みのクライアントだけです。

つまずきやすい点

古いバージョンのClaude Codeは、gatewayInternalNetworksを無視してプライベートアドレスのルールをそのまま適用します。キーを無視したことは知らされず、プライベートアドレスのルールで接続を拒否されます。「設定は入れたのに一部のマシンだけサインインできない」という形で表に出ます。展開前に、対象マシンがv2.1.268以降かをclaude --versionで揃えます。

もう一つは、前述の管理ソースの優先順位です。MDMとファイルを併用している環境では、/statusのSetting sourcesで採用ソースを見てから展開します。

まとめ

gatewayInternalNetworksが要るのは、自社所有のパブリックIPv4で社内を採番していて、そのブロックにgatewayを置く組織だけです。展開の順序は3段です。まず対象マシンをv2.1.268以降に揃え、次に/statusで採用される管理ソースを確かめてそこにキーを置き、最後にgateway側のaccess_control.allow_cidrsを同じブロックに揃えます。