IapAuther 0.3.0
dotnet tool install --global IapAuther --version 0.3.0
dotnet new tool-manifest
dotnet tool install --local IapAuther --version 0.3.0
#tool dotnet:?package=IapAuther&version=0.3.0
nuke :add-package IapAuther --version 0.3.0
IapAuther
Google Cloud Identity-Aware Proxy (Cloud IAP) でのさまざまな認証に対応する .NET 10 製 CLI ツールです。
- トークン発行 (
token): OIDC ID トークンや自己署名サービスアカウント JWT を発行して標準出力へ出力 (curl等との連携に最適) - headersHelper 用 JSON 出力 (
headers):Proxy-Authorizationと任意の追加ヘッダ (-H/--header) を含む JSON オブジェクトを標準出力へ出力 (Claude Code 等のheadersHelper向け) - MCP Proxy (
mcp-proxy): stdio クライアント (Claude Desktop / Claude Code / Cursor 等) と IAP 保護された HTTP MCP サーバー (Streamable HTTP / Legacy HTTP+SSE) を公式 MCP C# SDK (ModelContextProtocol.Core) 経由でつなぐブリッジ - クレデンシャルストアのクリア (
logout/clear-tokens): 各 OS のクレデンシャルストアおよび従来ファイルストアに保存された OAuth リフレッシュトークンを削除
必要環境
ビルド・インストール
ソースから実行
dotnet run --project src/IapAuther -- --help
NuGet から dotnet tool としてインストール
dotnet tool install -g IapAuther
iap-auther --help
ローカルビルドから dotnet tool としてインストール
dotnet pack src/IapAuther/IapAuther.csproj -c Release -o ./nupkg
dotnet tool install -g IapAuther --add-source ./nupkg
iap-auther --help
使い方
1. トークン発行モード (token)
iap-auther token [options] [UPSTREAM_URL]
例:
# 外部 Application Load Balancer 配下の IAP (カスタム OAuth クライアント)
TOKEN=$(iap-auther token --audience 1234567890-abc.apps.googleusercontent.com)
curl -H "Proxy-Authorization: Bearer ${TOKEN}" https://app.internal.example.com/
# Direct Cloud Run IAP (Google-managed OAuth クライアント → signjwt が必須)
iap-auther token \
--credentials signjwt \
--impersonate-service-account mcp-caller@my-project.iam.gserviceaccount.com \
https://my-svc-xxxx.a.run.app/mcp
# ローカルのサービスアカウント JSON キーを使って自己署名 JWT を発行
iap-auther token \
--credentials signjwt \
--credential-file ./sa-key.json \
--format json \
https://my-svc-xxxx.a.run.app/mcp
--format オプション:
raw(デフォルト): JWT トークン本体のみを出力header:Proxy-Authorization: Bearer <token>形式で出力json: トークン・audience・有効期限 (expires_at)・claims (subject,issuer,email) 等を JSON で出力
2. headersHelper 用 JSON 出力モード (headers)
iap-auther headers [options] [UPSTREAM_URL]
Proxy-Authorization: Bearer <token> と、-H / --header で指定した任意の追加ヘッダをまとめた JSON オブジェクトを 1 行で標準出力へ出力します(Claude Code 等の HTTP/WebSocket MCP headersHelper からそのまま呼び出せます)。
# 基本形 ({"Proxy-Authorization":"Bearer ..."} を出力)
iap-auther headers --audience 1234567890-abc.apps.googleusercontent.com
# 追加ヘッダ付き (下流の Authorization を環境変数から渡す例)
iap-auther headers \
--credentials signjwt \
--impersonate-service-account mcp-caller@my-project.iam.gserviceaccount.com \
-H "Authorization: env:DOWNSTREAM_TOKEN" \
-H "X-Tenant-Id: team-a" \
https://my-svc-xxxx.a.run.app/mcp
Claude Code (~/.claude.json 等) の設定例:
{
"mcpServers": {
"my-iap-mcp": {
"type": "http",
"url": "https://my-svc-xxxx.a.run.app/mcp",
"headersHelper": "iap-auther headers --credentials signjwt --impersonate-service-account mcp-caller@my-project.iam.gserviceaccount.com -H \"Authorization: env:DOWNSTREAM_TOKEN\" https://my-svc-xxxx.a.run.app/mcp"
}
}
}
Claude Code 等の headersHelper で使う場合の注意点
-H/--headerによる追加ヘッダ指定:-H "Name: Value"を複数回指定でき、値にenv:VAR_NAMEを書くと環境変数から展開します(Proxy-Authorizationは IAP トークンで自動設定されるため-Hでの上書きはできません)。stdout汚染の防止と--log-output: デフォルト(--log-output stderr)ではログ・エラー・OAuth 認証案内はすべてstderrに出力され、ブラウザ起動プロセス(open/xdg-open)の出力も/dev/nullへ破棄されるため、stdoutには JSON(tokenではトークン/JSON)のみが出力されます。切り分け・デバッグ等でstdoutにもログを出したい場合は--log-output both(またはstdout)を指定してください。- タイムアウト対策(OAuth の事前サインイン):
headersHelperには短い実行タイムアウト(Claude Code では約 10 秒)があります。--credentials oauth(またはautoからのフォールバック)を使う場合は、事前にターミナルから一度iap-auther headers ...またはiap-auther token ...を手動実行してブラウザ認証を完了し、リフレッシュトークンをキャッシュさせてからheadersHelperを動かしてください(2 回目以降はキャッシュ済みリフレッシュトークンで高速に更新されます)。 - プロジェクトスコープの環境変数制限: プロジェクトスコープの
.mcp.jsonでは、クライアント側のセキュリティ制限によりTOKEN/SECRET/KEY/AUTH等を含む環境変数(IAP_AUTHER_OAUTH_CLIENT_SECRETやenv:DOWNSTREAM_TOKEN等)がheadersHelperに渡らない場合があります。ラッパースクリプトやユーザースコープ設定を利用するか、トークン更新と 401/302 リトライを内蔵したmcp-proxyモード の利用を検討してください。
3. MCP Proxy モード (mcp-proxy)
iap-auther mcp-proxy [options] <UPSTREAM_URL>
stdio ⇄ HTTP (Streamable HTTP / Legacy HTTP+SSE 自動判別) ブリッジとして動作し、リクエストに Proxy-Authorization: Bearer <token> を自動付与・自動リフレッシュします。
Claude Desktop 設定例:
{
"mcpServers": {
"internal-tools": {
"command": "iap-auther",
"args": [
"mcp-proxy",
"--audience", "1234567890-abc.apps.googleusercontent.com",
"https://mcp.internal.example.com/mcp"
]
}
}
}
Direct Cloud Run IAP (Google-managed OAuth クライアント) の場合:
{
"mcpServers": {
"cloud-run-mcp": {
"command": "iap-auther",
"args": [
"mcp-proxy",
"--credentials", "signjwt",
"--impersonate-service-account", "mcp-caller@my-project.iam.gserviceaccount.com",
"https://my-mcp-xxxx.a.run.app/mcp"
]
}
}
}
4. クレデンシャルストアのクリア (logout / clear-tokens)
OAuth 認証で保存されたリフレッシュトークンは、iap-auther logout(エイリアス: clear-tokens)で各 OS クレデンシャルストアおよび従来ファイルストアから削除できます。
# 特定の OAuth クライアント ID に紐づくトークンのみ削除 (--oauth-client-id または IAP_AUTHER_OAUTH_CLIENT_ID)
iap-auther logout --oauth-client-id 1234567890-abc.apps.googleusercontent.com
# IapAuther が保存したすべての OAuth リフレッシュトークンを一括削除
iap-auther logout --all
# 削除対象ストアを明示して JSON で結果を表示 (--token-store: auto / os / file)
iap-auther logout --all --token-store os --format json
--token-store auto(デフォルト)では、OS クレデンシャルストアと従来ファイルストア(Windows:%APPDATA%\iap-autherの.dpapiファイル / Linux・macOS:~/.config/iap-auther等)の両方から削除します(OS ストア利用不可時は警告を出してファイルストアのみ削除)。--token-store osは OS クレデンシャルストアのみを対象とし、利用不可時は終了コード2で失敗します。- 該当トークンが 0 件の場合もエラーにはならず、冪等に終了コード
0で完了します(gcloudの ADC やサービスアカウントキー自体は削除しません)。
<details> <summary>OS 標準ツールで手動確認・削除する場合の格納キー仕様</summary>
- Windows (資格情報マネージャー): 汎用資格情報
TargetName = iap-auther:oauth-refresh-token:<CLIENT_ID>(cmdkey /listや コントロールパネルで確認可) - macOS (Keychain): 汎用パスワード
service = iap-auther,account = <CLIENT_ID>(security find-generic-password -s iap-auther/ キーチェーンアクセスで確認可) - Linux (Secret Service / GNOME Keyring 等): 属性
application=iap-auther,account=<CLIENT_ID>,xdg:schema=org.iapauther.OAuthRefreshToken(secret-tool search application iap-auther xdg:schema org.iapauther.OAuthRefreshTokenで確認可) - ファイルストア (
--token-store file/ フォールバック):refresh-token-<CLIENT_ID>(Windows は.dpapi拡張子)
</details>
対応する認証パターン (--credentials)
| モード | トークン種別 | 仕組み / 用途 |
|---|---|---|
auto (デフォルト) |
自動選択 | --impersonate-service-account 指定時は impersonate。未指定時は adc を試し、ADC が authorized_user (gcloud ユーザー認証情報) の場合は oauth (デスクトップ OAuth) へフォールバック。 |
adc |
OIDC ID トークン | Application Default Credentials (SA キー、Workload Identity、GCE メタデータ等) または --credential-file から OIDC ID トークンを取得。 |
impersonate |
OIDC ID トークン | IAM Credentials API (generateIdToken) を呼び出し、指定 SA として OIDC ID トークンを発行 (roles/iam.serviceAccountTokenCreator が必要)。 |
signjwt |
自己署名 SA JWT | Direct Cloud Run IAP (Google-managed OAuth クライアント) 向け。--impersonate-service-account 指定時は IAM signJwt API を使用し、未指定かつ ADC/--credential-file が SA キーの場合はローカルの秘密鍵で直接署名 (RS256)。 |
oauth |
OIDC ID トークン | デスクトップ OAuth 2.0 (PKCE + ローカルループバック /authorize/ + ブラウザ認証)。リフレッシュトークンは各 OS のクレデンシャルストア(Windows Credential Manager / macOS Keychain / Linux Secret Service over D-Bus)に保存し、利用不可時は従来ファイル(Windows: DPAPI、Linux/macOS: 0600)へフォールバック(--token-store で切替可)。 |
オプション・環境変数一覧
| フラグ | 環境変数 (IAP_AUTHER_* / IAP_MCP_*) |
デフォルト | 説明 |
|---|---|---|---|
-a, --audience |
IAP_AUTHER_AUDIENCE / IAP_MCP_AUDIENCE |
UPSTREAM_URL の origin (signjwt はエンドポイント URL または <origin>/*) |
トークンの aud |
-c, --credentials |
IAP_AUTHER_CREDENTIALS / IAP_MCP_CREDENTIALS |
auto |
auto / adc / impersonate / oauth / signjwt |
-s, --impersonate-service-account |
IAP_AUTHER_IMPERSONATE_SA / IAP_MCP_IMPERSONATE_SA |
— | 対象サービスアカウントのメールアドレス |
--credential-file |
IAP_AUTHER_CREDENTIAL_FILE |
— | SA JSON キーまたは ADC ファイルのパス |
--oauth-client-id |
IAP_AUTHER_OAUTH_CLIENT_ID / IAP_MCP_OAUTH_CLIENT_ID |
— | デスクトップ OAuth クライアント ID |
--oauth-client-secret |
IAP_AUTHER_OAUTH_CLIENT_SECRET / IAP_MCP_OAUTH_CLIENT_SECRET |
— | デスクトップ OAuth クライアントシークレット |
--token-store |
IAP_AUTHER_TOKEN_STORE / IAP_MCP_TOKEN_STORE |
auto |
OAuth リフレッシュトークンの保存先・クリア対象 (auto / os / file)。auto は OS ストア優先(既存のファイル保存分を自動移行し旧ファイルを削除、OS ストア利用不可時はファイル保存へフォールバック)、os は OS ストア必須、file は従来ファイル (DPAPI / 0600) |
--all (logout) |
— | false |
iap-auther が保存したすべての OAuth リフレッシュトークンを一括削除 (--oauth-client-id と併用不可) |
--no-browser |
— | false |
ブラウザを自動起動せず認証 URL をログ出力先 (デフォルト stderr) に表示 |
-l, --log-level |
IAP_AUTHER_LOG / IAP_MCP_LOG |
warn |
debug / info / warn / error |
--log-output |
IAP_AUTHER_LOG_OUTPUT / IAP_MCP_LOG_OUTPUT |
stderr |
ログ・エラー・認証案内の出力先 (stderr / stdout / both)。stdout / both はデバッグ用途向け (token / headers / mcp-proxy の機械処理用 stdout に混ざるため通常利用時は非推奨) |
-f, --format (token / logout) |
— | raw (token) / text (logout) |
出力形式 (token: raw / header / json、logout: text / json) |
-H, --header (headers) |
— | — | 追加 HTTP ヘッダ (Name: Value 形式、複数指定可、env:VAR_NAME 参照対応) |
--downstream-auth (mcp-proxy) |
IAP_AUTHER_DOWNSTREAM_AUTH / IAP_MCP_DOWNSTREAM_AUTH |
— | 上流 Authorization ヘッダーに転送する値 (env:VAR_NAME 参照対応) |
--refresh-margin (mcp-proxy) |
IAP_AUTHER_REFRESH_MARGIN / IAP_MCP_REFRESH_MARGIN |
5m |
有効期限の指定時間前にトークンを更新 |
--timeout (mcp-proxy) |
IAP_AUTHER_TIMEOUT / IAP_MCP_TIMEOUT |
120s |
JSON レスポンスの全体タイムアウト / SSE ストリームのアイドルタイムアウト |
--transport (mcp-proxy) |
IAP_AUTHER_TRANSPORT / IAP_MCP_TRANSPORT |
auto |
トランスポート方式 (auto / streamable-http / sse) |
MCP Proxy の主な機能
- MCP C# SDK ベースのトランスポートブリッジ: 公式
ModelContextProtocol.CoreのHttpClientTransport(AutoDetect/StreamableHttp/Sse) とカスタムTransportBaseを組み合わせ、stdio ⇄ HTTP 間でプロトコル透過な JSON-RPC ブリッジを実行します (stdoutは JSON-RPC 専用、SDK ログはstderrへルーティング)。 - 認証エラー時の自動リトライ: 401 または
accounts.google.comへの 302 リダイレクトを受信した場合、キャッシュを破棄してトークンを再取得し 1 回だけリトライします。再失敗時はX-Goog-Iap-Generated-Responseやレスポンス本文を解析し、原因に応じたメッセージを stderr に出力します。 - 透過的なセッション復旧: Cloud Run の再デプロイ等で上流が
404(セッション期限切れ) を返した場合、キャッシュ済みinitialize/notifications/initializedを自動再生してセッションを再確立し、元のリクエストをリトライします。 - SSE ストリーム再開 (
Last-Event-ID): レスポンス中の SSE 切断時に、受信済みid:を使ってGETで途中再開します。 - サーバー主導通知の受信:
initialize後にスタンドアロンGETSSE ストリームを開き、指数バックオフとLast-Event-IDで再接続します (405の場合は静かに停止)。 - クリーンシャットダウン: 終了時に
DELETEリクエストで MCP セッションを終了します。 - 終了コード:
0正常終了、1設定エラーまたは致命的エラー、2認証ブートストラップ失敗。
テスト
dotnet test
各 OS(Linux ubuntu-latest + GNOME Keyring / Windows windows-latest + Credential Manager / macOS macos-latest + Keychain)での実ストア結合テストを含むマトリクステストは、test-matrix.yml の workflow_dispatch から手動実行できます(GitHub Actions 無料枠の節約のため push / PR では自動実行しません)。
リリース (NuGet Trusted Publishing)
publish.yml により、v* タグのプッシュ(例: v0.1.0)または GitHub Actions の workflow_dispatch から production Environment 経由の OIDC Trusted Publishing で NuGet.org へ公開されます(タグプッシュ時は GitHub Release も自動作成)。
git tag v0.1.0
git push origin v0.1.0
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.