Workload Identity Federationとは、外の身元でGoogle Cloudへ鍵なしで入る仕組みです。
- workload identity pool・provider・属性の対応と条件・サービスアカウントへの権限・workflow の permissions という、公式の文書にある設定の並び
- CI に置いていた固定のサービスアカウントの鍵を、対照を取りながら撤去した当社の順番
- 属性の条件がタグの deploy を止めた記録と、逆にタグが門をすり抜ける穴の記録
当社は AIエージェント の席に CI の workflow を書かせ、直させています。GitHub Actions から Google Cloud へ入る所は、以前は JSON の鍵を GitHub の secret に置く形でした。この頁は、それを Workload Identity Federation(以下 WIF)に替えて鍵を消すまでの記録です。人の口座とサービスアカウントの違いそのものは gcloud auth の頁 にあります。
WIF の仕組みと、出てくる言葉
GitHub Actions の job は、GitHub が発行する OIDC のトークン(短い寿命の身元の証明)を求められます。WIF はそのトークンを Google Cloud の Security Token Service で受け取り、Google Cloud の短い寿命の資格情報に引き換えます。公式の文書は、これでサービスアカウントの鍵に伴う保守と安全の負担がなくなるとしています。
| 言葉 | 公式の文書の意味 | GitHub Actions での中身 |
|---|---|---|
workload identity pool | 外の身元をまとめて扱う入れ物。外の環境ごと(開発・検証・本番など)に分けるのが勧め | GitHub Actions 用の pool を 1 つ作る |
workload identity pool provider | Google Cloud と外の IdP の関係を書いた物 | OIDC の provider。発行者の URL は https://token.actions.githubusercontent.com/ |
属性の対応(attribute mapping) | 外のトークンの中身から、Google のトークンの属性を CEL の式で作る。 google.subject は必須で、一意・127 文字以内・ログに出る。attribute.NAME は 50 個まで | 少なくとも google.subject=assertion.sub。条件や権限で使う claim(repository・repository_owner・ref など)も対応させる |
属性の条件(attribute condition) | CEL の式。真なら受け入れ、そうでなければ資格情報を拒む | GitHub の組織が発行したトークンに絞る条件が必須。 main の枝に絞る例も載っている |
principal・principalSet | IAM で外の身元を指す書き方。プロジェクトの ID ではなく番号を使う | 属性の値で指すなら principalSet://…/attribute.repository/リポ の形 |
出典: Workload Identity Federation・Configure Workload Identity Federation with deployment pipelines(いずれも 2026-11-11 に見た)。
GitHub の側では、job に permissions: id-token: write が無いと OIDC のトークンを求められません。この権限はトークンを取るためだけの物で、他の物への書き込みは許しません。トークンの sub は、枝なら repo:組織/リポ:ref:refs/heads/枝、タグなら repo:組織/リポ:ref:refs/tags/タグ の形です(GitHub Docs「OpenID Connect reference」・2026-11-11 に見た)。この違いが、下の当社の詰まりの元になりました。
GitHub Actions から入る設定の手順
公式の文書にある並びを、そのまま表にします。名前は example の架空の値です。
| 順 | やる事 | コマンド・書き方 | メモ |
|---|---|---|---|
1 | 前の準備 | IAM・Resource Manager・Service Account Credentials・Security Token Service の API を有効にする | プロジェクトに Workload Identity Pool 管理者( roles/iam.workloadIdentityPoolAdmin)か同等の権限が要る。GitHub の側の変更は要らない |
2 | pool を作る | gcloud iam workload-identity-pools create example-pool --location="global" | 説明と表示名も付けられる |
3 | OIDC の provider を作る | gcloud iam workload-identity-pools providers create-oidc example-provider --location="global" --workload-identity-pool="example-pool" --issuer-uri="https://token.actions.githubusercontent.com/" --attribute-mapping="…" --attribute-condition="…" | audience は既定のまま |
4 | 属性の対応と条件を書く | 対応: google.subject=assertion.sub,attribute.repository=assertion.repository,…条件: assertion.repository_owner=='example-org' | 組織で絞る条件は必須。名前より、使い回されない数の ID( *_id)が勧め |
5 | サービスアカウントに入る権限を渡す | gcloud iam service-accounts add-iam-policy-binding 例のサービスアカウント --role=roles/iam.workloadIdentityUser --member="principalSet://iam.googleapis.com/projects/プロジェクト番号/locations/global/workloadIdentityPools/example-pool/attribute.repository/example-org/example-repo" | 公式は、できるならサービスアカウントを挟まず物へ直に権限を渡す形を勧める。API の制限があるときはサービスアカウントのなりすましにする |
6 | workflow に書く | job に permissions: id-token: write・contents: read。google-github-actions/auth に workload_identity_provider(provider の完全な道)と、挟むなら service_account | README の例は auth@v3。actions/checkout は auth より前に置く |
出典: Configure Workload Identity Federation with deployment pipelines・google-github-actions/auth の README・GitHub Docs「OpenID Connect reference」(いずれも 2026-11-11 に見た)。
auth の README は、サービスアカウントの JSON の鍵を長く生きる資格情報としてパスワードのように扱えと書き、WIF を鍵より勧めています。また service_account を省くと直の形になり、そのとき得るトークンの寿命は最大 10 分です(google-github-actions/auth の README・2026-11-11 に見た)。
当社の記録: 固定の鍵を、対照を取りながら撤去した順番
CI は、サービスアカウントの JSON の鍵を GitHub の secret に置いて Google Cloud へ入っていました。これを WIF に替え、鍵を消すまでを次の順で進めました。各段で「前は駄目・後は通る」か「前は通る・後は駄目」の対照を取っています(出典: 社の実測 2026-10-18)。
| 順 | やった事 | 確かめた対照 |
|---|---|---|
1 | OIDC の provider を作る | — |
2 | WIF で認証して読む run を撃つ | 認証の前は読めない・WIF で認証した後は読める |
3 | 旧い鍵を無効にする | 無効にする前は旧い鍵で読める・無効にした後は Invalid JWT で落ちる |
4 | 鍵を消し、GitHub の secret を消す | 残りは鍵 0・secret 0 |
出典: 社の実測 2026-10-18。
先に鍵を「無効」にして Invalid JWT を見てから「消す」順にしたのは、無効は戻せるからです。旧い鍵にまだ頼る所が残っていれば、無効にした時点で落ちて分かります(出典: 社の実測 2026-10-18)。
当社の記録: 初めてのタグの deploy が、属性の条件で止まった
本番の初めてのタグの deploy が、WIF の認証の段で次の文で止まりました(出典: 社の実測 2026-09-20)。
unauthorized_client: rejected by the attribute condition
provider の属性の条件は「リポが一致 かつ ref が refs/heads/main」だけでした。タグで走る run の ref は refs/tags/v… なので、条件が偽になって拒まれていました。直しは、同じリポのタグの ref だけを足し、他のリポは通さないままにする事です。直した後は provider を読み直して、条件が反映された事を確かめました(出典: 社の実測 2026-09-20)。形を example の値で写すと次のとおりです。
| 見る所 | 前 | 後 |
|---|---|---|
属性の条件 | assertion.repository=='example-org/example-repo' && assertion.ref=='refs/heads/main' | assertion.repository=='example-org/example-repo' && (assertion.ref=='refs/heads/main' || assertion.ref.startsWith('refs/tags/v')) |
main の push の run | 通る | 通る |
同じリポの v タグの run | unauthorized_client で拒まれる | 通る |
他のリポ | 拒まれる | 拒まれる(変えていない) |
出典: 社の実測 2026-09-20。sub と ref の形は GitHub Docs「OpenID Connect reference」(2026-11-11 に見た)。
属性の条件は、main の push だけで試すと通ってしまい、タグの run が来て初めて落ちます。条件を書いたら、実際に走らせる ref(枝・タグ・pull request)ごとに通るか拒まれるかを並べておくと、初めての本番の deploy で止まりません。
当社の記録: タグを通したら、門が嘘をつく穴が開いた
上の直しの後で、逆の向きの穴に気づきました。条件はタグの名前が v で始まるかしか見ていません。main に無い commit に v で始まるタグを打てば、WIF を通って本番の deploy に届きます。条件は「main の物だけが本番に行く」と言っているように見えて、実はそうなっていない=門が嘘をつく状態です(出典: 社の実測 2026-10-10)。
属性の条件が見られるのは OIDC のトークンの中身だけで、その commit が main の祖先かどうかは分かりません。そこで、タグを main の祖先にだけ打てるようにする直しを起票しました(出典: 社の実測 2026-10-10)。WIF の条件は「どの身元を入れるか」の門で、「何を本番に出すか」は別の門で守る、というのが当社の今の分け方です。
当社の記録: 外のサービスの札も GitHub の secret から消した
鍵を消した後も、GitHub の secret には外のサービスの札(Vercel と Cloudflare の API の札)の写しが残っていました。同じ札が Google Cloud の Secret Manager にもあり、写しが 2 か所にある状態です。CI の写しを消し、CI は WIF で Google Cloud に入った後に Secret Manager から読む共通の段にしました。替えたのは 4 か所+1 か所です(出典: 社の実測 2026-10-18)。
| 見る所 | 前 | 後 |
|---|---|---|
Google Cloud へ入る物 | サービスアカウントの JSON の鍵(GitHub の secret) | WIF(鍵 0・secret 0) |
外のサービスの札 | GitHub の secret に写しを持つ | WIF で入った後に Secret Manager から読む |
札を替えるとき | 写しの在る所を全部直す | Secret Manager の 1 か所を直す |
読む段 | workflow ごとにばらばら | 共通の段(4 か所+1 か所を寄せた) |
出典: 社の実測 2026-10-18。
Secret Manager の置き方と読み方は Secret Manager の頁、同時に替えた Vercel の deploy の段は Vercel デプロイの頁 にあります。
当社の記録: main で動くかは、CI の車線に載るまで測れない
main の workflow を WIF に替えた PR は、必須のチェックが走らず、取り込み待ちのまま止まりました(出典: 社の実測 2026-10-18)。WIF の段が main で本当に動くかは、その workflow が CI の車線に載って走るまで測れません。手元や別の枝で通っても、main の門の中で通った事にはなりません。
ここから当社は、WIF の切り替えを「PR を出したら終わり」にせず、main で最初の run が通るのを見るまでを 1 つの作業にしています(出典: 社の実測 2026-10-18)。
よくある質問
Workload Identity Federation を使うと、サービスアカウントの鍵は要らなくなりますか?
GitHub Actions から入る所では要りません。job が GitHub の OIDC のトークンを求め、WIF がそれを Google Cloud の短い寿命の資格情報に引き換えます(Configure Workload Identity Federation with deployment pipelines・2026-11-11 に見た)。当社は切り替えの後、鍵 0・GitHub の secret 0 にしました(社の実測 2026-10-18)。
「unauthorized_client: rejected by the attribute condition」と出ます
provider の属性の条件が偽になり、トークンが拒まれた文です。当社では条件が refs/heads/main だけを通していて、タグの run(refs/tags/v…)が拒まれました(社の実測 2026-09-20)。走らせる ref を条件が通すかを確かめ、要る ref だけを足します。
属性の条件は書かなくても動きますか?
Google Cloud の文書は、GitHub の場合は組織が発行したトークンに絞る属性の条件を必ず使うよう書いています(Configure Workload Identity Federation with deployment pipelines・2026-11-11 に見た)。条件の無い provider は、他人のリポの workflow のトークンも受け入れうるからです。
workflow に何を書けばよいですか?
job に permissions: id-token: write を付け、google-github-actions/auth に provider の完全な道(projects/番号/locations/global/workloadIdentityPools/…/providers/…)を渡します。サービスアカウントを挟むなら service_account も渡します(google-github-actions/auth の README・2026-11-11 に見た)。
タグで deploy するときに気をつける事はありますか?
属性の条件はトークンの中身しか見ないので、タグの名前で通すと、main に無い commit に打ったタグも通ります。当社はこの穴に気づき、タグを main の祖先にだけ打てるようにする直しを起票しました(社の実測 2026-10-10)。
出典
- Google Cloud「Workload Identity Federation」 https://docs.cloud.google.com/iam/docs/workload-identity-federation(2026-11-11 に見た・pool と provider・属性の対応(
google.subjectは必須で 127 文字以内・attribute.NAMEは 50 個まで)・属性の条件が偽なら拒む事・principal の書き方とプロジェクト番号) - Google Cloud「Configure Workload Identity Federation with deployment pipelines」 https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines(2026-11-11 に見た・GitHub Actions の手順・発行者の URL・組織で絞る条件が必須・
roles/iam.workloadIdentityUser・直の権限の勧め・workflow の permissions) - google-github-actions/auth の README https://github.com/google-github-actions/auth(2026-11-11 に見た・
id-token: write・workload_identity_providerとservice_account・直の形のトークンは最大 10 分・JSON の鍵より WIF を勧める事・auth@v3の例) - GitHub Docs「OpenID Connect reference」 https://docs.github.com/en/actions/reference/security/oidc(2026-11-11 に見た・
id-token: writeが要る事・発行者・枝とタグのsubの形・repository・refの claim) - 社の実測 2026-09-20(初めてのタグの deploy が
unauthorized_client: rejected by the attribute conditionで止まった・同じリポのタグの ref だけを足し、読み直して反映を確かめた) - 社の実測 2026-10-10(main に無い commit への v タグが本番の deploy に届く穴・main の祖先にだけ打てる直しを起票)
- 社の実測 2026-10-18(固定の鍵を対照つきで撤去・
Invalid JWT・鍵 0・secret 0/外のサービスの札の写しを消し Secret Manager から読む共通の段に(4 か所+1 か所)/main の workflow を替えた PR で必須のチェックが走らなかった)