Workload Identity Federation

解決する課題

Google Cloud の外で動くワークロード（AWS の EC2、Azure の VM、オンプレ、GitHub Actions、外部の Kubernetes など）から GCP のリソースを呼ぶには、従来はサービスアカウントの JSON キーを発行して相手に渡していました。これは長期間有効な秘密情報そのもので、配布・ローテーション・漏洩対策が常につきまといます。Workload Identity Federation は、このキー配布を不要にします。

• 外部の CI/CD やマルチクラウド構成から GCP を呼びたいが、長期キーを置きたくない
• キーがリポジトリや環境変数に漏れて長期間悪用される事故を根本から避けたい
• 相手側がすでに持っている ID トークン（OIDC / SAML）や AWS の署名情報を、そのまま GCP へのアクセス資格に変換したい
• キーのローテーション運用そのものをなくし、管理対象を減らしたい

主要概念と用語

• Workload Identity Federation（ワークロード ID 連携）: 外部 IdP が発行した認証情報を信頼し、短期の GCP アクセストークンへ交換する鍵レス連携の仕組み
• Workload Identity プール（pool）: 外部 ID をまとめる入れ物。プール単位で連携の境界を分ける
• プロバイダ（provider）: プール内に登録する個々の外部 IdP の定義。OIDC・SAML・AWS の3タイプがある
• 属性マッピング（attribute mapping）: 外部トークンのクレーム（例: sub・aud・リポジトリ名）を、GCP 側の属性（google.subject や attribute.*）へ写像するルール
• 属性条件（attribute condition / CEL）: 「このリポジトリ・このブランチ・この AWS アカウントのみ通す」といった、受け入れ可否を判定する条件式
• プリンシパル / プリンシパルセット: 連携した外部 ID を表す IAM の主体。principal://（個別 ID）や principalSet://（属性で束ねた集合）で表す
• サービスアカウントの権限借用（impersonation）: 連携 ID にサービスアカウントを借用させ、その権限で操作する方式
• 直接リソースアクセス（direct resource access）: サービスアカウントを介さず、連携プリンシパルへ直接 IAM ロールを付与する方式
• STS トークン交換: Security Token Service が外部認証情報を受け取り、短期の連携トークンに交換する入口

仕様・制限・クォータ

• 対応プロバイダ種別: OIDC（汎用の OpenID Connect IdP、GitHub Actions・GitLab・外部 Kubernetes 等）、SAML、AWS の3種類
• 位置づけ: GKE 上の Pod から GCP を呼ぶ用途には、同名の混同しやすい機能である Workload Identity（GKE 向け） を使う。本機能は主に GCP の外のワークロード向け
• 発行されるのは短期トークン: 交換で得られるのは有効期間の短い連携トークンで、長期キーは存在しない
• 属性条件は必須に近い運用: 条件を付けないと外部 IdP のすべての ID を受け入れかねないため、aud やリポジトリ等で必ず絞る
• 2つのアクセス方式: サービスアカウントの権限借用（既存ロール資産を流用しやすい）と、直接リソースアクセス（サービスアカウントを介さない）から選べる。直接方式は対応サービスに制限がある場合があるため、要件は公式で確認する
• プール/プロバイダの数や属性数には上限があるため、具体値は公式ドキュメントを参照する

内部の仕組み

横にスクロール

中核は STS によるトークン交換です。外部ワークロードが自分の IdP から受け取った認証情報を GCP の STS に提示すると、属性条件を満たす場合にのみ短期の連携トークンが返ります。

1. 外部ワークロードが自身の IdP から ID トークン（OIDC/SAML）や AWS の署名情報を取得する
2. その認証情報を STS のトークン交換エンドポイントに提示する
3. GCP は対応するプロバイダ定義で署名・発行者・aud を検証し、属性条件（CEL）で受け入れ可否を判定する
4. 通過すると、外部クレームを属性マッピングで GCP 属性に写像した短期の連携トークンが返る
5. そのトークンで、サービスアカウントを借用するか、連携プリンシパルへ直接付与された権限で GCP API を呼ぶ

設計パターン / ベストプラクティス

• 属性条件で必ず絞る: GitHub Actions なら特定リポジトリ・特定ブランチ、AWS なら特定アカウント・特定ロールに限定する。aud の検証も外さない
• プリンシパルセットで束ねる: 「このリポジトリの全実行」のような集合を principalSet:// で表し、個別 ID ごとの設定を避ける
• 直接リソースアクセスを優先検討: サービスアカウント借用を挟まず連携プリンシパルへ直接ロールを付けられるなら、経路をひとつ減らせる。既存のロール資産を流用したい場合は借用方式を選ぶ
• 環境ごとにプールを分ける: 本番・検証で連携の境界を分離し、誤って本番権限を渡さないようにする
• 最小権限: 借用させるサービスアカウントにも、付与する直接ロールにも、必要なロールだけを与える
• キー発行を組織ポリシーで封じる: サービスアカウントキーの作成自体を組織ポリシーで禁止し、連携への移行を後戻りさせない

運用・監視

• STS のトークン交換やサービスアカウント借用は Cloud Audit Logs に記録される。誰の・どの外部 ID が・いつ交換したかを追える
• 属性条件の変更は影響範囲が広いため、変更時はどのプリンシパルが通る/通らなくなるかをレビューする
• IdP 側の発行者 URL や署名鍵の変更に追従できているかを監視する（OIDC のメタデータ更新など）
• 連携が失敗するときは、プロバイダの発行者・aud の不一致 → 属性条件で弾かれた → 借用先サービスアカウントへの権限不足の順で切り分ける
• 既存のサービスアカウントキーがまだ残っていないかを棚卸しし、移行後に無効化・削除する

コスト

Workload Identity Federation の連携機能・STS のトークン交換・プールやプロバイダの保持は、基本的に IAM の一部として無料です。連携の結果として呼び出した先の各 API・リソースには、それぞれ通常どおり課金されます。

セキュリティ

• サービスアカウントキーを発行・配布しないことが本機能の最大の効能。鍵レスで漏洩・長期悪用のリスク源を断つ
• 属性条件を必ず設定する。条件なしは外部 IdP のすべての ID を受け入れかねず、最も危険なアンチパターン
• aud（受け手）と発行者を厳密に検証し、別用途のトークンの流用を防ぐ
• 借用させるサービスアカウントの権限を最小化し、連携プリンシパルへ直接付与する場合も同様に絞る
• プールやプロバイダの設定変更は特権操作として監査し、不要になった連携は削除する

関連サービス・比較

最も近い関連は Cloud IAM（特にサービスアカウント）です。Workload Identity Federation は IAM の一機能で、外部 ID を IAM のプリンシパルとして扱えるようにする入口にあたります。なお、名前が似ている Workload Identity（GKE 向け） は、GKE 上の Pod をサービスアカウントに紐づける別機能で、用途が異なります。AWS で近い位置づけは IAM ロールの OIDC / Web ID 連携です。

ハンズオン / CLI例

# 1. Workload Identity プールを作成
gcloud iam workload-identity-pools create my-pool \
  --location="global" \
  --display-name="My external pool"

# 2. GitHub Actions 向けの OIDC プロバイダを作成し、属性をマッピング・条件で限定
gcloud iam workload-identity-pools providers create-oidc github-provider \
  --location="global" \
  --workload-identity-pool="my-pool" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
  --attribute-condition="assertion.repository=='my-org/my-repo'"

# 3. 連携プリンシパル（特定リポジトリ）にサービスアカウントの借用を許可
gcloud iam service-accounts add-iam-policy-binding \
  app-sa@my-project.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/my-pool/attribute.repository/my-org/my-repo"

# 4. 外部ワークロードが使う認証情報設定ファイルを生成（鍵は含まれない）
gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/my-pool/providers/github-provider \
  --service-account="app-sa@my-project.iam.gserviceaccount.com" \
  --output-file="credential-configuration.json" \
  --credential-source-file="path/to/oidc-token"