Claude CodeでGCPサービスアカウントキーを棚卸しし、鍵なし認証へ移す

GCPのユーザー管理サービスアカウントキーは、全プロジェクトを横断して一覧にし、経過日数と使用実績で仕分けると移行の順番が決まります。その作業の大半は読み取り専用の gcloud コマンドで済むので、Claude Codeに集計を任せやすい題材です。この記事では、一覧化のスクリプト、使われているかの確かめ方、鍵なしの手段への振り分け、削除までの順序を並べます。

棚卸しの対象は「ユーザー管理キー」だけ

サービスアカウントのキーには、Google管理とユーザー管理の2種類があります。棚卸しの対象はユーザー管理キーです。漏えいや権限昇格のリスクが問題になるのは、利用者が自分で管理するこちらのキーです。

gcloud iam service-accounts keys list の --managed-by は user / system / any を取り、既定は any です。指定を忘れるとGoogle管理のキーまで混ざるため、棚卸しでは --managed-by=user を必ず付けます。

もう1点、このコマンドは --iam-account が必須です。プロジェクト単位で「全部出して」とは言えず、サービスアカウントを1つずつ指定します。そのため全プロジェクトを回すには、プロジェクト、サービスアカウント、キーの三重ループが要ります。存在しないサービスアカウントを指定すると PERMISSION_DENIED が返る点も、公式のコマンド説明に書かれています。権限不足と名前の打ち間違いが同じエラーに見える、という意味です。

全プロジェクトのキーを経過日数順に並べる

次のスクリプトは、見えるプロジェクトを順に回し、ユーザー管理キーをCSVに書き出します。末尾の sort で作成日の古い順に並びます。

for p in $(gcloud projects list --format='value(projectId)'); do
  for sa in $(gcloud iam service-accounts list --project "$p" \
      --format='value(email)'); do
    gcloud iam service-accounts keys list \
      --iam-account "$sa" --managed-by=user \
      --format='csv[no-heading](name.basename(),validAfterTime,validBeforeTime)' \
      | sed "s|^|$p,$sa,|"
  done
done | sort -t, -k4 > user-managed-keys.csv

列は、プロジェクト、サービスアカウント、キーID、作成日時(validAfterTime)、有効期限(validBeforeTime)の順です。キーのリソース定義には keyType として USER_MANAGED と SYSTEM_MANAGED があり、disabled も持ちます。無効化済みのキーを別枠で見たいときは、--format に disabled を足してください。

Google Cloudの組織は、2024年5月3日以降に作られたものならキー作成の禁止が既定で有効です。それ以前の組織では古いキーが残っている前提で、この一覧が出発点になります。

使われているかを調べる

作成日が古いだけでは、削除してよいとは言えません。公式の移行ガイドは、使用状況の確認に使える情報源を2つ挙げています。

• サービスアカウントのインサイト: 過去90日間に認証していないサービスアカウントを洗い出す
• Cloud Monitoringの鍵ごとの認証回数: 指標 iam.googleapis.com/service_account/key/authn_events_count で、キーが最後にいつ、どれだけ使われたかを見る

どちらもプロジェクトごとに追う必要があります。サービスアカウントはプロジェクトに属するからです。ここに3つの落とし穴があります。

1. Monitoringの保持期間は6週間。半年に1度しか動かない鍵は、指標に出てこないことがあります。長期の確認が要るなら、BigQueryへ定期エクスポートします。
2. インサイトは万能ではない。サービスアカウントにひも付いたAPIキー経由のリクエストは、使用状況の指標に記録されません。そのサービスアカウントが「未使用」と誤判定される場合があります。
3. Google Cloud外のAPI利用は追跡外。Google Workspace APIへのドメイン全体の委任などは、インサイトの対象外です。公式は、無効化や削除の前にMonitoringの指標と突き合わせるよう勧めています。

Cloud StorageのHMAC認証キーも、サービスアカウントとキーのどちらの指標にも現れません。HMACキーを使っているプロジェクトでは、別の一覧が必要です。

組織全体を継続的に追うなら、移行ガイドが紹介する参照アーキテクチャがあります。Cloud Asset Inventoryからキーを集め、使用状況と結合してBigQueryの表 sa_key_usage に毎日書き出す構成です。数十プロジェクト程度なら、上のスクリプトで足ります。

用途別に鍵なしの手段へ振り分ける

一覧と使用実績がそろったら、キーごとに「何のために使っているか」を決め、置き換え先を当てます。

impersonationは、呼び出し元の本人が認証し、サービスアカウントの短期トークンを受け取る方式です。トークンの寿命は数時間かそれ以下で、自動更新はされません。長期の鍵より漏えい時の被害が小さくなります。必要な権限は iam.serviceAccounts.getAccessToken で、roles/iam.serviceAccountTokenCreator に含まれます。監査ログには、本人とサービスアカウントの両方が残ります。

コマンドでは --impersonate-service-account フラグで指定できます。ADCの設定ファイルを作るときにも同じフラグが使え、対応するクライアントライブラリは自動でなりすまします。

外部のIDから使う場合はWorkload Identity Federationです。AWSやAzure、GitHubやGitLab、一般のOIDC・SAMLのIDプロバイダーが対象になります。GitLab CI/CDでの組み方はClaude CodeのBedrock OIDC認証をGitLab CI/CDで組むで、GCP側の設定まで扱っています。なお、ClaudeのAPIを鍵なしにするWorkload Identity Federationは別の仕組みで、WIFをGoogle Cloudと連携するが主題にしています。ここで置き換えるのは、GCPのサービスアカウントキーのほうです。

Claude Codeに任せる範囲と権限設定

棚卸しの前半は、読み取りだけで進みます。Claude Codeには、一覧の作成、CSVの集計、キーIDとリポジトリ内の参照箇所の突き合わせを任せられます。参照箇所は、環境変数 GOOGLE_APPLICATION_CREDENTIALS をCI設定やシェルスクリプトから検索するのが手がかりです。

書き込みの伴う操作は、最初から止めておくほうが安全です。権限ルールはdeny、ask、allowの順に評価され、先に一致したものが結果を決めます。これを使って、読み取りだけを許可します。

{
  "permissions": {
    "allow": [
      "Bash(gcloud projects list *)",
      "Bash(gcloud iam service-accounts list *)",
      "Bash(gcloud iam service-accounts keys list *)"
    ],
    "ask": [
      "Bash(gcloud iam service-accounts keys disable *)"
    ],
    "deny": [
      "Bash(gcloud iam service-accounts keys create *)",
      "Bash(gcloud iam service-accounts keys delete *)"
    ]
  }
}

キーの無効化だけは確認つきで通し、作成と削除は拒否します。削除は人が判断してから、手元で実行する運用です。

CIから claude -p で棚卸しの集計を回す場合は、--allowedTools で許可するツールを列挙します。Bashを丸ごと許可すると gcloud の書き込み系も通ってしまうため、上のような個別ルールを設定ファイルに置いて併用してください。

無効化、待機、削除の順で進める

公式の勧めは、不要になったキーをまず無効化し、確実に要らないと分かってから削除する順序です。無効化は元に戻せますが、削除は戻せません。

最後の組織ポリシーは、既存のキーの使用を止めません。ただし、キーを定期的にローテーションしているワークロードは、新しいキーを作れなくなって止まる可能性があります。公式は、最初は開発用のフォルダーなど範囲を絞って適用するよう案内しています。例外を許す案件には、タグで適用を外す方法が使えます。例外を申請する窓口も、あらかじめ決めておく項目に挙げられています。

移行後のClaude Code側の設定

Claude CodeをVertex経由で使う場合、認証はGoogle Cloudの標準の仕組みに従います。/setup-vertex のウィザードは、gcloud のADC、サービスアカウントのキーファイル、環境にある認証情報から選ぶ形です。鍵なしにするなら、ADCかWorkload Identity Federationを選びます。X.509証明書ベースのWorkload Identity Federationは、GOOGLE_APPLICATION_CREDENTIALS に認証構成ファイルのパスを入れれば、同じADCの流れで使えます。

CIで --bare を付けた非対話実行でも、Google Cloud側の認証情報は通常どおり読まれます。鍵ファイルを置き換えれば、CIの実行方法は変えずに済みます。

ADCの期限が切れた端末では、gcpAuthRefresh に gcloud auth application-default login を設定しておくと、切れたときだけ更新が走ります。設定の書き方はClaude CodeのawsAuthRefreshとgcpAuthRefreshで認証切れを自動更新にあります。Vertex側に与える権限の絞り方はClaude Code Vertex AI IAM設定とチーム展開ガイドで扱っています。

よくあるつまずき

• 一覧が空になる。 gcloud projects list が見せるのは、実行者が閲覧できるプロジェクトだけです。権限が足りないと、キーがあっても出てきません。
• 古いのに消せない。年に1度の決算バッチなど、頻度の低い用途が裏にあります。Monitoringの保持が6週間なので、実績がないことは使われていない証拠になりません。担当者への聞き取りと併用します。
• 移行後も鍵が復活する。手元の旧手順書が keys create を案内していると、新しい鍵が作られます。組織ポリシーで作成を止めるまでは、棚卸しが終わったとは言えません。
• インサイトが「未使用」と言うのに動いている。サービスアカウントにひも付いたAPIキー経由の利用は記録されないためです。

Entra IDのゲストユーザーのように、アカウント系の棚卸しにも同じ「古さで並べて、使用実績で仕分ける」型が使えます。手順はEntraゲストユーザーの棚卸しをClaude Codeで進めるにまとめています。

まとめ

棚卸しの要点は、古い順に並べることではなく、使用実績で「消してよい鍵」と「置き換えが要る鍵」を切り分けることです。前者は無効化から削除へ進めるだけで減らせます。後者は用途ごとに、ADC、impersonation、添付サービスアカウント、Workload Identity Federationのどれかに替わります。Claude Codeには読み取りの集計までを任せ、無効化は確認つき、削除は人の手で行う線引きが取り回しやすい構成です。