デプロイメントパイプラインとの Workload Identity 連携を構成する

このガイドでは、Workload Identity 連携を使用して、デプロイパイプラインで Google Cloud に対する認証を行えるようにする方法について説明します。

使用している CI / CD システムによっては、デプロイパイプラインからアンビエントな環境固有の認証情報にアクセスできる場合があります。例:

Azure DevOps パイプラインは、Microsoft Entra Workload Identity 連携サービス接続を使用して、Azure DevOps プロジェクトを一意に識別する ID トークンを取得できます。
GitHub Actions ワークフローでは、GitHub OIDC トークンを取得して、ワークフローとそのリポジトリを一意に識別できます。
GitLab SaaS を使用すると、CI / CD ジョブは、ジョブとそのプロジェクト、環境、リポジトリを一意に識別する ID トークンにアクセスできます。
Terraform Cloud では、ワークスペースと環境を一意に識別する OIDC トークンを Terraform 構成に指定できます。

Workload Identity 連携を使用すると、これらの認証情報を使用して Google Cloud に対する認証を行うようにデプロイパイプラインを構成できます。これにより、サービスアカウントキーに関連するメンテナンスとセキュリティの負担がなくなります。

始める前に

認証を設定する

このページのサンプルをどのように使うかに応じて、タブを選択してください。

コンソール

Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

gcloud

このページの gcloud CLI のサンプルは、次のいずれかの開発環境から使用できます。

Cloud Shell: gcloud CLI がすでに設定されているオンラインターミナルを使用するには、Cloud Shell をアクティブにします。

このページの下部で Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。セッションが初期化されるまで数秒かかることがあります。
ローカルシェル: ローカル開発環境で gcloud CLI を使用するには、gcloud CLI をインストールして初期化してください。

Python

このページの Python サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。

Install the Google Cloud CLI.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

必要なロール

Workload Identity 連携の構成に必要な権限を取得するには、プロジェクトに対する Workload Identity プール管理者（roles/iam.workloadIdentityPoolAdmin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセスの管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

また、IAM オーナー（roles/owner）の基本ロールには ID 連携を構成する権限も含まれています。本番環境では基本ロールを付与すべきではありません。基本ロールは、開発環境またはテスト環境で付与してください。

外部 IdP を準備する

Azure DevOps

Azure DevOps パイプラインで Google Cloud に対する認証を行うには、まず Azure Resource Manager にサービス接続を構成します。この接続により、パイプラインで ID トークンを取得し、Google Cloud の認証情報と交換できるようになります。

Azure Resource Manager にサービス接続を作成するには、次の操作を行います。

Azure DevOps でプロジェクトを開き、[Project Settings] に移動します。
[Pipelines] > [Service connections] に移動します。
[Create service connection] をクリックします。
[Azure Resource Manager] を選択します。
[Next] をクリックします。
[Workload Identity federation (automatic)] を選択します。
[Next] をクリックします。
以下の設定を構成します。
- Scope level: サブスクリプションを選択します。
  
  サービス接続を使用して Azure リソースにアクセスする予定がない場合でも、サブスクリプションを選択する必要があります。
- Service connection name: google-cloud などの名前を入力します。
[Save] をクリックします。

後のステップでは、サービス接続の発行者とサブジェクトの識別子が必要になります。これらの情報を確認するには、次の操作を行います。

作成したサービス接続をクリックします。
[Manage Service Principal] をクリックします。
[Certificate & secrets] > [Federated credentials] に移動します。
フェデレーション資格情報をクリックします。
[Edit a credential] ページで、次の識別子を見つけます。
- Issuer: Azure DevOps 組織を一意に識別する ID
- Subject identifier: サービス接続を一意に識別する ID

Azure DevOps は、新しいサービス接続に関連付けられたサービスプリンシパルに、スコープとして選択したサブスクリプションへのアクセス権を自動的に付与します。サービス接続を使用して Azure リソースにアクセスする予定がないため、このアクセス権は次のステップで取り消すことができます。

Azure Portal で、スコープとして選択したサブスクリプションを開きます。
[Access control (IAM)] > [Role assignments] に移動します。
サービス接続のロール割り当てを見つけて削除します。

GitHub Actions

GitHub アカウントで構成を変更する必要はありません。

GitHub リポジトリを信頼するように Workload Identity プールを構成すると、そのリポジトリのワークフローで GitHub OIDC トークンを使用して、有効期間の短い Google Cloud 認証情報を取得できます。

GitLab SaaS

GitLab アカウントで構成を変更する必要はありません。

GitLab グループを信頼するように Workload Identity プールを構成すると、個々の CI / CD ジョブで Workload Identity 連携を有効にできます。

Terraform Cloud

Terraform Cloud アカウントで構成を変更する必要はありません。

Terraform Cloud を信頼するように Workload Identity プールを構成すると、個々のワークスペースで Workload Identity 連携を有効にできます。

Workload Identity 連携を構成する

この手順は、GitHub 組織、GitLab グループ、Terraform Cloud 組織ごとに行う必要があります。

Workload Identity 連携の構成を開始するには、次の操作を行います。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Workload Identity プールとプロバイダの管理に専用のプロジェクトを使用する

Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

属性マッピングを定義する

デプロイパイプラインの環境固有の認証情報には複数の属性を含めることができます。このため、Google Cloud でサブジェクト識別子（google.subject）として使用する属性を決定する必要があります。

必要に応じて、追加の属性をマッピングできます。これにより、リソースへのアクセス権を付与する際にこれらの追加属性を参照できます。

Azure DevOps

Azure DevOps ID トークンには、サービス接続のサブジェクト識別子を含む sub クレームが含まれています。サブジェクト識別子の形式は次のとおりです。

sc://ORGANIZATION/PROJECT/CONNECTION

この識別子を google.subject にマッピングするには、次の属性マッピングを使用します。

google.subject=assertion.sub

GitHub Actions

属性マッピングでは、GitHub Actions OIDC トークン内のすべてのクレームを使用できます。これらのトークンクレームキーとその値は GitHub によって制御されます。少なくとも、GitHub Actions OIDC トークンのサブジェクトに対応する google.subject を assertion.sub にマッピングする必要があります。

google.subject=assertion.sub

GitHub Actions の OIDC トークンのサブジェクトの値は、ソースイベントによって異なる場合があります。その他のクレーム属性には次のようなものがあります。

repository: オーナーとリポジトリ名が含まれます（例: "google/guava"）。
repository_id: 一意のリポジトリ ID が含まれています（例: "20300177"）。
repository_owner: オーナー（ユーザー名または GitHub 組織の名前）が含まれています（例: "google"）。
repository_owner_id: 一意のオーナー ID が含まれています（例: "1342004"）。

このリストは、可能性のあるクレームの一部です。完全なリストについては、クレームの例に関する GitHub ドキュメントをご覧ください。属性条件として使用するクレーム、または今後 principalSet 条件の一部として使用する予定のクレームを必ずマッピングします。

GitLab SaaS

属性マッピングでは、次のような GitLab ID トークンに埋め込まれたクレームをソース属性として使用できます。

sub: プロジェクト名と Git リファレンス（例: project_path:groupname/projectname:ref_type:branch:ref:main）。
namespace_id: 一意のグループ ID。
project_id: 一意のプロジェクト ID。
user_id: 一意のユーザー ID。
environment: ジョブが適用される環境。
ref_path: Git リファレンス（例: refs/heads/main）。

次の属性マッピングでは、google.subject を GitLab ID トークンの sub クレームに設定します。sub クレームにはリポジトリ名と Git リファレンスの両方が含まれるため、このマッピングによりプロジェクトとブランチによるアクセスを制御できます。

google.subject=assertion.sub

リポジトリとブランチによるアクセスの制御は、特定のブランチ（main など）が他のブランチ（機能ブランチなど）以外のリソースに対する異なるアクセスが必要な場合に役立ちます。

場合によっては、プロジェクトまたはグループでアクセスを区別するだけで十分です。次のマッピングには、GitLab の project_id と namespace_id を含む 2 つの追加属性が含まれています。

google.subject=assertion.sub
attribute.project_id=assertion.project_id
attribute.namespace_id=assertion.namespace_id

Terraform Cloud

属性マッピングでは、次のような Terraform Cloud OIDC トークンに埋め込まれたクレームを使用できます。

terraform_organization_id: 組織の一意の ID が含まれます（例: org-xxxxxxxxxxxxxxxx）。
terraform_workspace_id: ワークスペースの一意の ID が含まれます（例: ws-xxxxxxxxxxxxxxxx）。
terraform_workspace_name: ワークスペースの表示名が含まれます。
sub: 組織、ワークスペース、フェーズの表示名が含まれます（例: organization:example-org:workspace:example-workspace:run_phase:apply）。

次の属性マッピングは、google.subject を Terraform Cloud OIDC トークンの terraform_workspace_id クレームに設定します。

google.subject=assertion.terraform_workspace_id

このマッピングにより、ワークスペースごとに Google Cloud リソースへのアクセスを制御できます。

属性条件を定義する

属性条件は、アサーション属性とターゲット属性をチェックする CEL 式です。特定の認証情報の属性条件が true と評価されると、認証情報が受け入れられます。それ以外の場合、認証情報は拒否されます。すべての属性条件フィールドに属性マッピングが必要です。

Azure DevOps

必要に応じて、属性条件を使用して、特定のサービス接続へのアクセスを制限します。たとえば、次の条件は、特定の Azure DevOps プロジェクトの接続へのアクセスを制限しています。

assertion.sub.startsWith('sc://ORGANIZATION/PROJECT/')

次のように置き換えます。

ORGANIZATION: Azure DevOps 組織の名前。
PROJECT: Azure DevOps プロジェクトの名前。

GitHub Actions

GitHub 組織によって発行されたトークンへのアクセスを制限するには、次の属性条件を使用します。

assertion.repository_owner=='ORGANIZATION'

ORGANIZATION は、GitHub 組織の名前に置き換えます。

必要に応じて属性条件を拡張して、ワークフローまたはブランチのサブセットへのアクセスを制限します。たとえば、次の条件は、Git ブランチ main を使用するワークフローへのアクセスを制限します。

assertion.repository_owner=='ORGANIZATION' && assertion.ref=='refs/heads/main'

GitLab SaaS

次の属性条件を使用して、GitLab グループによって発行されるトークンへのアクセスを制限します。

assertion.namespace_id=='GROUP_ID'

GROUP_ID は、GitLab グループのホームページに表示されるグループ ID に置き換えます。

必要に応じて、属性条件を拡張して、プロジェクト、ブランチ、環境のサブセットへのアクセスを制限します。たとえば、次の条件は、環境 production を使用するジョブへのアクセスを制限します。

assertion.namespace_id=='GROUP_ID' && assertion.environment=='production'

Terraform Cloud

Terraform Cloud 組織によって発行されたトークンへのアクセスを制限するには、次の属性条件を使用します。

assertion.terraform_organization_id=='ORGANIZATION_ID'

ORGANIZATION_ID は、組織の一意の ID に置き換えます（例: org-xxxxxxxxxxxxxxxx）。必要に応じて属性条件を拡張して、ワークフローまたはブランチのサブセットへのアクセスを制限します。たとえば、次の属性条件により、特定のワークスペースへのアクセスが制限されます。

assertion.terraform_organization_id=='ORGANIZATION_ID' && terraform_workspace_id=='WORKSPACE_ID'

Workload Identity のプールとプロバイダを作成する

これで、Workload Identity プールとプロバイダの作成に必要な情報がすべて収集されました。

コンソール

Google Cloud コンソールで、[新しいワークロードプロバイダとプール] ページに移動します。

[新しいワークロードプロバイダとプール] に移動
[ID プールを作成] に、次のように入力します。
- 名前: プールの名前。この名前はプール ID としても使用されます。プール ID を後で変更することはできません。
- 説明: プールの目的を説明するテキスト。
[続行] をクリックします。
プロバイダを構成します。
Azure DevOps
- Select a provider: OpenID Connect（OIDC）。
- Provider name: Azure DevOps プロジェクトの名前またはカスタム名。
- Provider ID: Azure DevOps プロジェクトの名前またはカスタム ID。プロバイダ ID は後から変更できません。
- Issuer URL: 以前に検索したサービス接続の発行元。
- Audiences: [Allowed audiences] を選択して、次の値を貼り付けます。
```
api://AzureADTokenExchange
```
GitHub Actions
- Select a provider: OpenID Connect（OIDC）。
- Provider name: プロバイダの名前。
- Provider ID: プロバイダの ID。プロバイダ ID は後から変更できません。
- 発行元 URL: https://token.actions.githubusercontent.com/
- オーディエンス: デフォルトのオーディエンス
GitLab SaaS
- Select a provider: OpenID Connect（OIDC）。
- Provider name: プロバイダの名前。
- Provider ID: プロバイダの ID。プロバイダ ID は後から変更できません。
- 発行元 URL: https://gitlab.com
- オーディエンス: デフォルトのオーディエンス
Terraform Cloud
- Select a provider: OpenID Connect（OIDC）。
- Provider name: プロバイダの名前。
- Provider ID: プロバイダの ID。プロバイダ ID は後から変更できません。
- 発行元 URL: https://app.terraform.io
- オーディエンス: デフォルトのオーディエンス
[続行] をクリックします。
[プロバイダの属性を構成する] で、前に確認した属性マッピングを追加します。
[属性条件] で、前に確認した属性条件を入力します。
[保存] をクリックして、Workload Identity のプールとプロバイダを作成します。

gcloud

新しい Workload Identity プールを作成します。
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
次の値を置き換えます。
- POOL_ID: プールの一意の ID
- DISPLAY_NAME: プールの名前
- DESCRIPTION: プールの説明。この説明は、プール ID へのアクセス権を付与するときに表示されます。
Workload Identity プールのプロバイダを追加します。
Azure DevOps
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
次の値を置き換えます。
- PROVIDER_ID: Azure DevOps プロジェクトの名前、またはプロバイダのカスタム ID。
- POOL_ID: プールの ID
- ISSUER: 以前に検索したサービス接続の発行者。
- MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト
- CONDITIONS: 前に確認した属性条件
GitHub Actions
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://token.actions.githubusercontent.com/" \
    --allowed-audiences="api://AzureADTokenExchange" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
次の値を置き換えます。
- PROVIDER_ID: プロバイダの一意の ID
- POOL_ID: プールの ID
- MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト
- CONDITIONS: 前に確認した属性条件
GitLab SaaS
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://gitlab.com" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
次の値を置き換えます。
- PROVIDER_ID: プロバイダの一意の ID
- POOL_ID: プールの ID
- MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト
- CONDITIONS: 前に確認した属性条件
Terraform Cloud
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://app.terraform.io" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
次の値を置き換えます。
- PROVIDER_ID: プロバイダの一意の ID。
- POOL_ID: プールの ID。
- MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
- CONDITIONS: 前に確認した属性条件。

Workload Identity プロバイダの属性条件を更新する

このセクションでは、既存の Workload Identity プールプロバイダの属性条件を更新して、GitHub 組織、GitLab グループ、Terraform Cloud 組織によって発行されたトークンへのアクセスを制限する方法について説明します。

パイプラインに推奨される属性条件を確認するには、属性条件を定義するをご覧ください。

コンソール

Google Cloud コンソールで、[Workload Identity プール] ページに移動します。

[Workload Identity プール] に移動
プロバイダを含む Workload Identity プールを見つけて、そのプールの「ノードを開く」アイコン（）をクリックします。
編集する Workload Identity プールプロバイダを見つけて、[編集] をクリックします。
[属性条件] で、前に確認した属性条件を入力します。
Workload Identity のプールとプロバイダを更新するには、[保存] をクリックします。

gcloud

Workload Identity プールのプロバイダを更新するには、次のコマンドを実行します。

gcloud iam workload-identity-pools providers update-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --attribute-condition="CONDITIONS"

次の値を置き換えます。

PROVIDER_ID: プロバイダの一意の ID
POOL_ID: プールの ID
CONDITIONS: 前に確認した属性条件

デプロイパイプラインを認証する

この手順は、GitHub Actions ワークフローまたは Terraform Cloud ワークスペースごとに行う必要があります。

外部ワークロードが Google Cloud リソースにアクセスできるようにする

このガイドの後半の手順を完了するには、このセクションの説明に沿ってサービスアカウントの権限借用を構成する必要があります。

ワークロードに Google Cloud リソースへのアクセス権を付与するには、プリンシパルに直接リソースへのアクセス権を付与することをおすすめします。この場合、プリンシパルは連携ユーザーです。一部の Google Cloud プロダクトには、Google Cloud API の制限事項があります。ワークロードが制限付きの API エンドポイントを呼び出す場合は、サービスアカウントの権限借用を使用できます。この場合、プリンシパルは Google Cloud サービスアカウントであり、ID として機能します。リソースのサービスアカウントにアクセス権を付与します。

リソースへの直接アクセス

Google Cloud コンソールまたは gcloud CLI を使用して、リソースへの直接アクセス権を連携 ID に付与できます。

コンソール

Google Cloud コンソールでリソースに IAM ロールを直接付与するには、リソースのページに移動してロールを付与する必要があります。次の例は、Cloud Storage ページに移動し、Cloud Storage バケットでフェデレーション ID にストレージオブジェクト閲覧者（roles/storage.objectViewer）ロールを直接付与する方法を示しています。

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、ロールを付与するバケットの名前をクリックします。
ページ上部にある [権限] タブを選択します。
[ アクセス権を付与] ボタンをクリックします。

[プリンシパルの追加] ダイアログが表示されます。
[新しいプリンシパル] フィールドに、バケットへのアクセスが必要な ID を 1 つ以上入力します。
サブジェクト
```
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
```
次のように置き換えます。
- PROJECT_NUMBER: プロジェクト番号
- POOL_ID: ワークロードプールの ID
- SUBJECT: IdP からマッピングされた個々のサブジェクト（例: administrator@example.com）
グループ
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
```
次のように置き換えます。
- PROJECT_NUMBER: プロジェクト番号
- WORKLOAD_POOL_ID: ワークロードプールの ID
- GROUP: IdP からマッピングされたグループ（例: administrator-group@example.com）。
属性
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
```
次のように置き換えます。
- PROJECT_NUMBER: プロジェクト番号
- WORKLOAD_POOL_ID: ワークロードプールの ID
- ATTRIBUTE_NAME: IdP からマッピングされた属性のいずれか
- ATTRIBUTE_VALUE: 属性の値
[ロールを選択] プルダウンメニューからロールを選択します。選択したロールと付与する権限の簡単な説明がパネルに表示されます。
[保存] をクリックします。

gcloud

gcloud CLI を使用してプロジェクトのリソースに IAM ロールを付与するには、次の操作を行います。

リソースが定義されているプロジェクトのプロジェクト番号を取得します。
```
gcloud projects describe $(gcloud config get-value core/project) --format=value$projectNumber$
```
リソースへのアクセス権を付与します。

gcloud CLI を使用して、特定の条件を満たす外部 ID に Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を付与するには、次のコマンドを実行します。
サブジェクト
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
```
グループ
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
```
属性
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
```
次のように置き換えます。
- BUCKET_ID: アクセス権を付与するバケット
- PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
- POOL_ID: Workload Identity プールのプール ID
- SUBJECT: google.subject にマッピングされている属性の想定値
- GROUP: google.groups にマッピングされている属性の想定値
- ATTRIBUTE_NAME: 属性マッピングのカスタム属性の名前
- ATTRIBUTE_VALUE: 属性マッピングのカスタム属性の値
IAM 許可ポリシーをサポートする任意の Google Cloud リソースにロールを付与できます。

注: メンバー ID には、プロジェクト ID ではなくプロジェクト番号を使用する必要があります。

サービスアカウントの権限借用

外部ワークロードのサービスアカウントを作成するには、次の操作を行います。
1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
  Enable the APIs
2. ワークロードを表すサービスアカウントを作成します。ワークロードごとに専用のサービスアカウントを使用することをおすすめします。
  
  サービスアカウントは、Workload Identity プールと同じプロジェクトにある必要はありません。
3. 外部 ID にアクセスを許可するリソースに対するアクセス権をサービスアカウントに付与します。
4. サービスアカウントに Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を付与します。
5. ワークロードを表すサービスアカウントを作成します。ワークロードごとに専用のサービスアカウントを使用することをおすすめします。
  
  サービスアカウントは、Workload Identity プールと同じプロジェクトにある必要はありませんが、サービスアカウントを含むプロジェクトを参照する必要があります。
Google Cloud コンソールまたは gcloud CLI を使用してサービスアカウントの権限借用でフェデレーション ID へのアクセス権を付与するには、次の操作を行います。
コンソール
Google Cloud コンソールで、サービスアカウントを使用してフェデレーション ID に IAM ロールを付与する手順は次のとおりです。
1. 次の手順で、権限借用の ID として機能するサービスアカウントを作成します。
  1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
    Enable the APIs
  2. ワークロードの ID を表すサービスアカウントを作成します。ワークロードごとに専用のサービスアカウントを使用することをおすすめします。
    
    サービスアカウントは、Workload Identity プールと同じプロジェクトにある必要はありませんが、IAM アクセス権を付与する場合は、サービスアカウントを含むプロジェクトを参照する必要があります。
  3. 外部 ID にアクセスを許可するリソースに対するアクセス権をサービスアカウントに付与します。
2. サービスアカウントの権限借用を使用してアクセス権を付与する手順は次のとおりです。
  1. [Workload Identity プール] ページに移動します。
    
    [Workload Identity プール] に移動
  2. [アクセス権を付与] を選択します。
  3. [サービスアカウントにアクセス権を付与する] ダイアログで、[Grant access using Service Account impersonation] を選択します。
  4. [サービスアカウント] リストで、権限を借用する外部 ID のサービスアカウントを選択して、次の操作を行います。
  5. プール内のどの ID がサービスアカウントの権限を借用できるかを選択するには、次のいずれかを行います。
    
    Workload Identity プールの特定の ID のみにサービスアカウントの権限借用を許可するには、[フィルタに一致する ID のみ] を選択します。
    
    [属性名] リストで、フィルタリングする属性を選択します。
    
    [属性値] フィールドに、属性の想定値を入力します。たとえば、属性マッピング google.subject=assertion.sub を使用する場合は、属性名を subject に設定します。属性値には、外部 ID プロバイダによって発行されたトークンの sub クレームの値を設定します。
  6. 構成を保存するには、[保存]、[閉じる] の順にクリックします。
gcloud

gcloud CLI を使用して、特定の条件を満たす外部 ID に Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を付与するには、次のコマンドを実行します。
サブジェクト

gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
グループ

gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
属性

gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
次のように置き換えます。
- SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス
- PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
- POOL_ID: Workload Identity プールのプール ID
- SUBJECT: google.subject にマッピングされている属性の想定値
- GROUP: google.groups にマッピングされている属性の想定値
- ATTRIBUTE_NAME: 属性マッピングのカスタム属性の名前
- ATTRIBUTE_VALUE: 属性マッピングのカスタム属性の値
注: メンバー ID には、プロジェクト ID ではなくプロジェクト番号を使用する必要があります。

デプロイパイプラインを構成する

このセクションでは、デプロイパイプラインで Workload Identity 連携を使用する方法について説明します。このセクションの手順では、ワークロードがサービスアカウントの権限借用を使用して Google Cloud リソースにアクセスすることを前提としています。

Azure DevOps

azure-pipelines.yml ファイルを編集して、ジョブ構成に以下を追加します。

variables:
- name: Azure.WorkloadIdentity.Connection
  value: CONNECTION
- name: GoogleCloud.WorkloadIdentity.ProjectNumber
  value: PROJECT_NUMBER
- name: GoogleCloud.WorkloadIdentity.Pool
  value: POOL_ID
- name: GoogleCloud.WorkloadIdentity.Provider
  value: PROVIDER_ID
- name: GoogleCloud.WorkloadIdentity.ServiceAccount
  value: SERVICE_ACCOUNT_EMAIL
- name: GOOGLE_APPLICATION_CREDENTIALS
  value: $(Pipeline.Workspace)/.workload_identity.wlconfig

steps:
  - task: AzureCLI@2
    inputs:
      connectedServiceNameARM: $(Azure.WorkloadIdentity.Connection)
      addSpnToEnvironment: true
      scriptType: 'bash'
      scriptLocation: 'inlineScript'
      inlineScript: |
        echo $idToken > $(Pipeline.Workspace)/.workload_identity.jwt
        cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
        {
          "type": "external_account",
          "audience": "//iam.googleapis.com/projects/$(GoogleCloud.WorkloadIdentity.ProjectNumber)/locations/global/workloadIdentityPools/$(GoogleCloud.WorkloadIdentity.Pool)/providers/$(GoogleCloud.WorkloadIdentity.Provider)",
          "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
          "token_url": "https://sts.googleapis.com/v1/token",
          "credential_source": {
            "file": "$(Pipeline.Workspace)/.workload_identity.jwt"
          },
          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$(GoogleCloud.WorkloadIdentity.ServiceAccount):generateAccessToken"
        }
        EOF

次の値を置き換えます。

CONNECTION: サービス接続の名前
PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
POOL_ID: Workload Identity プールの ID
PROVIDER_ID: Workload Identity プールプロバイダの ID
SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス

この構成では、次の処理が行われます。

AzureCLI タスクを使用して、サービス接続の ID トークンを取得し、idToken 変数で使用できるようにします。
ID トークンを .workload_identity.jwt という一時ファイルに保存します。
.workload_identity.jwt から ID トークンを読み取り、それを使用してサービスアカウントの権限を借用するようにクライアントライブラリに指示する認証情報構成ファイルを作成します。
認証情報構成ファイルを参照するように環境変数 GOOGLE_APPLICATION_CREDENTIALS を設定します。

GitHub Actions

google-github-actions/auth アクションを使用すると、ワークフローの実行中に認証情報構成ファイルを自動的に生成できます。terraform などのクライアントライブラリとツールでは、この認証情報構成ファイルを使用して Google 認証情報を自動的に取得できます。

GitHub Actions YAML ファイルを編集して、次の内容を追加します。

ジョブが GitHub ID トークンを取得できるようにするには、次の構成を追加します。
```
permissions:
  id-token: write
  contents: read
```

認証情報構成ファイルを作成するステップを追加します。

- id: 'auth'
  name: 'Authenticate to Google Cloud'
  uses: 'google-github-actions/auth@v1'
  with:
    create_credentials_file: true
    workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
    service_account: 'SERVICE_ACCOUNT_EMAIL'

次の値を置き換えます。

PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号。
POOL_ID: Workload Identity プールの ID。
PROVIDER_ID: Workload Identity プールプロバイダの ID。
SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレスに置き換えます。

次の例は、GitHub Action を構成するものです。

jobs:
  build:
    # Allow the job to fetch a GitHub ID token
    permissions:
      id-token: write
      contents: read

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v1'
        with:
          create_credentials_file: true
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'

google-github-actions/auth アクションの使用方法については、Workload Identity 連携の設定をご覧ください。

GitLab SaaS

.gitlab-ci.yml ファイルを編集して、ジョブ構成に以下を追加します。

job:
  variables:
    WORKLOAD_IDENTITY_PROJECT_NUMBER: PROJECT_NUMBER
    WORKLOAD_IDENTITY_POOL: POOL_ID
    WORKLOAD_IDENTITY_PROVIDER: PROVIDER_ID
    SERVICE_ACCOUNT: SERVICE_ACCOUNT_EMAIL
    GOOGLE_APPLICATION_CREDENTIALS: $CI_BUILDS_DIR/.workload_identity.wlconfig

  id_tokens:
    WORKLOAD_IDENTITY_TOKEN:
      aud: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

  script:
    - |-
      echo $WORKLOAD_IDENTITY_TOKEN > $CI_BUILDS_DIR/.workload_identity.jwt
      cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/projects/$WORKLOAD_IDENTITY_PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_IDENTITY_POOL/providers/$WORKLOAD_IDENTITY_PROVIDER",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "$CI_BUILDS_DIR/.workload_identity.jwt"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SERVICE_ACCOUNT:generateAccessToken"
      }
      EOF

次の値を置き換えます。

PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
POOL_ID: ワークロード ID プールの ID
PROVIDER_ID: Workload Identity プールプロバイダの ID
SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス

この構成では、次の処理が行われます。

ID トークンを発行し、WORKLOAD_IDENTITY_TOKEN という名前の環境変数で使用できるように GitLab に指示します。ID トークンは、Workload Identity プールのプロバイダをオーディエンスとして使用します。
ID トークンを .workload_identity.jwt という一時ファイルに保存します。
.workload_identity.jwt から ID トークンを読み取り、それを使用してサービスアカウントの権限を借用するようにクライアントライブラリに指示する認証情報構成ファイルを作成します。
認証情報構成ファイルを参照するように環境変数 GOOGLE_APPLICATION_CREDENTIALS を設定します。

Terraform Cloud

Workload Identity 連携を使用してサービスアカウントの権限借用で Google Cloud の認証を行えるように、Terraform Cloud ワークスペースを構成します。

Terraform Cloud でワークスペースを開き、[Variables] に移動します。

次の変数を追加します。

変数のカテゴリ	キー	値
環境変数	`TFC_GCP_PROVIDER_AUTH`	`true`
環境変数	`TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL`	サービスアカウントのメールアドレス（例: `terraform@my-project-123.iam.gserviceaccount.com`）
環境変数	`TFC_GCP_PROJECT_NUMBER`	Workload Identity プールを含むプロジェクトのプロジェクト番号
環境変数	`TFC_GCP_WORKLOAD_POOL_ID`	Workload Identity プールの ID
環境変数	`TFC_GCP_WORKLOAD_PROVIDER_ID`	Workload Identity プールプロバイダの ID

必要に応じて環境変数を追加し、Terrform Cloud で plan フェーズと apply フェーズに異なるサービスアカウントを使用できるようにします。詳細については、オプションの環境変数をご覧ください。

変数のリストで、前の手順で追加した 5 つの変数のカテゴリが env に設定されていることを確認します。
Terraform 構成で、バージョン 4.48.0 以降の Google Cloud プロバイダが使用されていることを確認し、必要に応じて次のように更新します。
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.48.0"
    }
  }
}
```
ソースコードリポジトリに変更を送信します。

次のステップ

Workload Identity 連携について確認する。
デプロイパイプラインでの Workload Identity 連携の使用に関するベストプラクティスを確認する。
Workload Identity プールとプロバイダの管理方法を学習する。

デプロイメント パイプラインとの Workload Identity 連携を構成する

始める前に

認証を設定する

コンソール

gcloud

Python

必要なロール

外部 IdP を準備する

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

Workload Identity 連携を構成する

属性マッピングを定義する

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

属性条件を定義する

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

Workload Identity のプールとプロバイダを作成する

コンソール

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

gcloud

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

Workload Identity プロバイダの属性条件を更新する

コンソール

gcloud

デプロイ パイプラインを認証する

外部ワークロードが Google Cloud リソースにアクセスできるようにする

リソースへの直接アクセス

コンソール

サブジェクト

グループ

属性

gcloud

サブジェクト

グループ

属性

サービス アカウントの権限借用

コンソール

gcloud

サブジェクト

グループ

属性

デプロイ パイプラインを構成する

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

次のステップ

デプロイメントパイプラインとの Workload Identity 連携を構成する

デプロイパイプラインを認証する

サービスアカウントの権限借用

デプロイパイプラインを構成する