AWS または Azure との Workload Identity 連携を構成する

このガイドでは、Workload Identity 連携を使用して、Google Cloud で AWS または Azure のワークロードの認証をサービスアカウントキーなしで実行できるようにする方法を説明します。

Workload Identity 連携を使用することで、AWS EC2 と Azure で実行されるワークロードは、環境固有の認証情報を有効期間の短い Google Cloud Security Token Service トークンと交換できます。

環境固有の認証情報は次のとおりです。

AWS EC2 インスタンスは、インスタンスプロファイルを使用して一時的な認証情報をリクエストできます。
Azure VM は、マネージド ID を使用して Azure アクセストークンを取得できます。

Workload Identity 連携を設定すると、これらのワークロードで有効期間の短い Google Cloud 認証情報と環境固有の認証情報を交換できるようになります。ワークロードは、これらの有効期間が短い認証情報を使用して Google Cloud APIs にアクセスできます。

始める前に

認証を設定します。

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

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

このページの gcloud CLI のサンプルは、次のいずれかの開発環境から使用できます。
- Cloud Shell: gcloud CLI がすでに設定されているオンラインターミナルを使用するには、Cloud Shell をアクティブにします。
  
  このページの下部で Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。セッションが初期化されるまで数秒かかることがあります。
- ローカルシェル: ローカル開発環境で gcloud CLI を使用するには、gcloud CLI をインストールして初期化してください。
Python

このページの Python サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。
1. Google Cloud CLI をインストールします。
2. gcloud CLI を初期化するには:
```
gcloud init
```
3. Google アカウントのローカル認証情報を作成します。
```
gcloud auth application-default login
```
詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

外部 ID プロバイダを準備する

この手順は、Azure AD テナントまたは AWS アカウントごとに 1 回だけ行います。

AWS

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

AWS アカウントを信頼するように Workload Identity プールを構成すると、AWS ユーザーと AWS ロールは、永続または一時的な AWS セキュリティ認証情報を使用して、有効期間の短い Google Cloud 認証情報を取得できます。

Azure

Azure AD テナントで新しい Azure AD アプリケーションを作成し、Workload Identity 連携で使用できるように構成する必要があります。

アプリケーションを信頼するように Workload Identity プールを構成すると、Azure ユーザーとサービスプリンシパルは、このアプリケーションのアクセストークンをリクエストし、それらのアクセストークンを有効期間の短い Google Cloud 認証情報と交換できます。

アプリケーションを作成するには、次のようにします。

Azure AD アプリケーションとサービスプリンシパルを作成します。
アプリケーションにアプリケーション ID URI を設定します。デフォルトのアプリケーション ID URI（api://APPID）を使用することも、カスタム URI を指定することもできます。

後で Workload Identity プールプロバイダを構成するときに、アプリケーション ID URI が必要になります。

アプリケーションが Azure AD アプリケーションのアクセストークンを取得できるようにするには、マネージド ID を使用します。

マネージド ID を作成します。マネージド ID のオブジェクト ID をメモします。これは、後で権限借用を構成するときに必要になります。
アプリケーションを実行する仮想マシンまたは別のリソースにマネージド ID を割り当てます。

Workload Identity 連携を構成する

この手順は、AWS アカウントまたは Azure AD テナントごとに 1 回だけ行います。これにより、複数のワークロードや複数の Google Cloud プロジェクトで同じ Workload Identity プールとプロバイダを使用できます。

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

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

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

Google Cloud プロジェクトで課金が有効になっていることを確認します。

IAM, Resource Manager, Service Account Credentials, and Security Token Service API を有効にします。

API を有効にする

属性のマッピングと条件を定義する

AWS または Azure ワークロードの環境固有の認証情報には複数の属性が含まれているため、Google Cloud でサブジェクト識別子（google.subject）として使用する属性を決定する必要があります。

Google Cloud は、Cloud Audit Logs とプリンシパル ID でサブジェクト ID を使用して、AWS または Azure のユーザーまたはロールを一意に識別します。

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

AWS

属性マッピングでは、ソース属性として GetCallerIdentity のレスポンスフィールドを使用できます。次のようなフィールドがあります。

account: AWS アカウント番号。
arn: 外部エンティティの AWS ARN。
userid: 呼び出し元エンティティの一意の識別子。

ロールが関連付けられた Amazon Elastic Compute Cloud（EC2）インスタンスでアプリケーションが実行されている場合は、次の属性マッピングを使用できます。

google.subject=assertion.arn
attribute.account=assertion.account
attribute.aws_role=assertion.arn.extract('assumed-role/{role}/')
attribute.aws_ec2_instance=assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')

マッピングでは次のことを行います。

ARN をサブジェクト識別子として使用する（例: "arn:aws:sts::000000000000:assumed-role/ec2-my-role/i-00000000000000000）
カスタム属性 account を使用して AWS アカウント ID を割り当てる
カスタム属性 aws_role を使用して AWS ロール名を割り当てる（例: ec2-my-role）
カスタム属性 aws_ec2_instance を使用して EC2 インスタンス ID を割り当てる（例: i-00000000000000000）

このマッピングを使用すると、次へのアクセスを許可できます。

特定の EC2 インスタンス:

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_ec2_instance/EC2_INSTANCE_ID

ロールのすべてのユーザーとインスタンス:

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_NAME

Azure

属性マッピングでは、ソース属性として Azure アクセストークンに埋め込まれたクレーム（カスタムクレームを含む）を使用できます。ほとんどの場合、sub クレームをサブジェクト識別子として使用することをおすすめします。

google.subject=assertion.sub

マネージド ID に発行されたアクセストークンの場合、sub クレームにマネージド ID のオブジェクト ID が含まれます。別のクレームを使用する場合は、そのクレームが一意であり、再割り当てできないことを確認してください。

参照可能なクレームのリストが確かでない場合は、次の操作を行います。

マネージド ID が割り当てられている Azure VM に接続します。

Azure Instance Metadata Service（IMDS）からアクセストークンを取得します。

Bash

curl \
  "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
  -H "Metadata: true" | jq -r .access_token

このコマンドは jq ツールを使用します。Cloud Shell では jq がデフォルトで使用されます。

PowerShell

$SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
$SubjectToken = (Invoke-RestMethod `
  -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
  -Headers @{Metadata="true"}).access_token
Write-Host $SubjectToken

APP_ID_URI は、Workload Identity 連携用に構成したアプリケーションのアプリケーション ID URI に置き換えます。

ウェブブラウザで https://jwt.ms/ に移動し、アクセストークンをテキストボックスに貼り付けます。
アクセストークンに埋め込まれたクレームのリストを表示するには、[Claims] をクリックします。

サービス ID の場合は通常、google.groups やカスタム属性のマッピングを作成する必要はありません。

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

AWS

属性条件を使用して、有効期間の短い Google Cloud トークンを取得するために Workload Identity 連携を使用できる IAM ユーザーとロールを制限できます。

たとえば、次の条件では、AWS ロールへのアクセスが制限され、他の IAM 識別子は拒否されます。

assertion.arn.startsWith('arn:aws:sts::AWS_ACCOUNT_ID:assumed-role/')

Azure

属性条件を使用して、有効期間の短い Google Cloud トークンを取得するために Workload Identity 連携を使用できるユーザーとサービスプリンシパルを制限できます。代わりに、アプリロールの割り当てを使用するように Azure AD アプリケーションを構成します。

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

必要なロール

Workload Identity 連携の構成に必要な権限を取得するには、プロジェクトに対して次の IAM ロールを付与するよう管理者に依頼してください。

Workload Identity プール管理者（roles/iam.workloadIdentityPoolAdmin）
サービスアカウント管理者（roles/iam.serviceAccountAdmin）

ロールの付与の詳細については、アクセスの管理をご覧ください。

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

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

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

コンソール

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

[新しいワークロードプロバイダとプール] に移動
[ID プールを作成する] セクションで、次のように入力します。
- 名前: プールの名前。この名前はプール ID としても使用されます。プール ID を後で変更することはできません。
- 説明: プールの目的を説明するテキスト。
[続行] をクリックします。
プロバイダを構成します。
AWS
次のプロバイダを構成します。
- プロバイダを選択: AWS。
- プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
Azure
次のプロバイダを構成します。
- プロバイダを選択: OpenID Connect（OIDC）。
- プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
- 発行元 URL: https://sts.windows.net/TENANT_ID。TENANT_ID は、Azure AD テナントのテナント ID（GUID）に置き換えます。
- 許可された対象: Azure AD でアプリケーションを登録したときに使用したアプリケーション ID URI。
[続行] をクリックします。
[プロバイダの属性を構成する] セクションで、前に確認した属性マッピングを追加します。
[属性条件] セクションで、前に確認した属性条件を入力します。属性条件がない場合は、空白のままにします。
[保存] をクリックして、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 プールのプロバイダを追加します。
AWS
AWS の Workload Identity プールプロバイダを作成するには、次のコマンドを実行します。
```
gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
  --location="global"  \
  --workload-identity-pool="POOL_ID" \
  --account-id="ACCOUNT_ID" \
  --attribute-mapping="MAPPINGS" \
  --attribute-condition="CONDITIONS"
```
次のように置き換えます。
- PROVIDER_ID: プロバイダの一意の ID。
- POOL_ID: プールの ID。
- ACCOUNT_ID: AWS アカウントを識別する 12 桁の番号。
- MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
- CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。
例:
```
gcloud iam workload-identity-pools providers create-aws example-provider \
  --location="global"  \
  --workload-identity-pool="pool-1" \
  --account-id="123456789000" \
  --attribute-mapping="google.subject=assertion.arn"
```
Azure
Azure 用の Workload Identity プールプロバイダを作成するには、次のコマンドを実行します。
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER_URI" \
    --allowed-audiences="APPLICATION_ID_URI" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
次のように置き換えます。
- PROVIDER_ID: プロバイダの一意の ID。
- POOL_ID: プールの ID。
- ISSUER_URI: Azure AD テナントのテナント ID（GUID）。https://sts.windows.net/TENANT_ID の形式になることがあります。発行者 URI はさまざまであり、JWT.io を使用して JWT をデバッグできます。
- APPLICATION_ID_URI: Azure AD でアプリケーションを登録したときに使用したアプリケーション ID URI。
- MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
- CONDITIONS: （省略可）前に確認した属性条件。
例:
```
gcloud iam workload-identity-pools providers create-oidc example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --issuer-uri="https://sts.windows.net/00000000-1111-2222-3333-444444444444" \
    --allowed-audiences="api://my-app" \
    --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups"
```

ワークロードの認証

この手順は、ワークロードごとに 1 回行う必要があります。

外部ワークロードのサービスアカウントを作成する

IAM, Security Token Service, and Service Account Credentials API を有効にします。
API を有効にする
ワークロードを表すサービスアカウントを作成します。ワークロードごとに専用のサービスアカウントを使用することをおすすめします。

サービスアカウントは、Workload Identity プールと同じプロジェクトにある必要はありません。
外部 ID にアクセスを許可するリソースに対するアクセス権をサービスアカウントに付与します。

外部ワークロードにサービスアカウントの権限借用を許可する

外部 ID にサービスアカウントの権限借用を許可するには、サービスアカウントに Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を付与します。このロールは、特定の外部 ID または複数の外部 ID に付与できます。

特定の外部 ID の場合は、google.subject 属性をチェックする属性条件を記述します。
外部 ID のグループの場合は、google.groups 属性またはカスタム属性 attribute.NAME をチェックする属性条件を記述します。

コンソール

Google Cloud コンソールを使用して外部 ID にサービスアカウントの権限借用を許可するには、次の操作を行います。

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

[Workload Identity プール] に移動
更新する Workload Identity プールを見つけて選択します。
選択した Workload Identity プールへのアクセス権を付与するには、[ アクセスを許可] をクリックします。
[サービスアカウント] リストで、権限を借用する外部 ID のサービスアカウントを選択します。
プール内のどの ID がサービスアカウントの権限を借用できるかを選択するには、次のいずれかを行います。
- Workload Identity プールの特定の ID のみにサービスアカウントの権限借用を許可するには、[フィルタに一致する ID のみ] を選択します。
  
  [属性名] リストで、フィルタリングする属性を選択します。
  
  [属性値] フィールドに、属性の想定値を入力します。たとえば、属性マッピング google.subject=assertion.sub を使用する場合は、属性名を subject に設定します。属性値には、外部 ID プロバイダによって発行されたトークンの sub クレームの値を設定します。
構成を保存するには、[保存]、[閉じる] の順にクリックします。

gcloud

gcloud CLI を使用して、外部 ID にサービスアカウントの権限借用を許可するには、次の操作を行います。

現在のプロジェクトのプロジェクト番号を取得するには、次のコマンドを実行します。
```
gcloud projects describe $(gcloud config get-value core/project) --format=value$projectNumber$
```

特定の条件を満たす外部 ID に Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を付与するには:

サブジェクト

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

グループ

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

属性

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --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: 属性マッピングのカスタム属性の名前

認証情報構成を作成する

Cloud クライアントライブラリ、gcloud CLI、Terraform は、外部認証情報を自動的に取得し、これらの認証情報を使用してサービスアカウントの権限を借用できます。ライブラリとツールでこのプロセスを完了するには、認証情報の構成ファイルを指定する必要があります。このファイルに次の項目を定義します。

外部認証情報の取得元
使用する Workload Identity プールとプロバイダ
権限を借用するサービスアカウント

認証情報構成ファイルを作成するには、次のようにします。

コンソール

Google Cloud コンソールで、認証情報の構成ファイルをダウンロードします。

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

[Workload Identity プール] に移動
使用する IdP を含む Workload Identity プールを見つけてクリックします。
[接続済みサービスアカウント] を選択します。
使用するサービスアカウントを見つけて、[ダウンロード] をクリックします。
[アプリケーションの構成] ダイアログで、サービスアカウントの権限を借用する外部 ID を含むプロバイダを選択します。
次の追加設定を行います。

AWS
追加の設定は必要ありません。

Azure
Application ID URL: Azure アプリケーションのアプリケーション ID URI
[構成をダウンロード] を選択して認証情報の構成ファイルをダウンロードしてから、[閉じる] をクリックします。

gcloud

gcloud iam workload-identity-pools create-cred-config を使用して認証情報の構成ファイルを作成するには、次の操作を行います。

AWS

ライブラリが EC2 インスタンスメタデータからアクセストークンを取得できるように認証情報の構成ファイルを作成するには、次の操作を行います。

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --aws \
    --output-file=FILEPATH.json

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

PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
POOL_ID: Workload Identity プールの ID
PROVIDER_ID: Workload Identity プールプロバイダの ID
SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス
SERVICE_ACCOUNT_TOKEN_LIFETIME: サービスアカウントのアクセストークンの存続期間（秒単位）。指定しない場合のデフォルトは 1 時間です。1 時間を超える有効期間を指定するには、constraints/iam.allowServiceAccountCredentialLifetimeExtension 組織ポリシー制約を構成する必要があります。
FILEPATH: 構成を保存するファイル

AWS IMDSv2 を使用する場合は、--enable-imdsv2 フラグを gcloud iam workload-identity-pools create-cred-config コマンドに追加する必要があります。

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --aws \
    --enable-imdsv2 \
    --output-file=FILEPATH.json

AWS メタデータサーバーを使用しない場合は、次の AWS 環境変数を使用して AWS セキュリティ認証情報を指定できます。

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION または AWS_DEFAULT_REGION のいずれか
省略可: AWS_SESSION_TOKEN

AWS メタデータサーバーが使用できない場合、gcloud CLI とライブラリはこれらの AWS 環境変数を使用します。

Azure

ライブラリが Azure Instance Metadata Service（IMDS）からアクセストークンを取得できるように認証情報の構成ファイルを作成します。

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --azure \
    --app-id-uri APPLICATION_ID_URI \
    --output-file=FILEPATH.json

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

PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
POOL_ID: Workload Identity プールの ID
PROVIDER_ID: Workload Identity プールプロバイダの ID
SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス
APPLICATION_ID_URI: Azure アプリケーションのアプリケーション ID URI
SERVICE_ACCOUNT_TOKEN_LIFETIME: サービスアカウントのアクセストークンの存続期間（秒単位）。指定しない場合のデフォルトは 1 時間です。1 時間を超える有効期間を指定するには、constraints/iam.allowServiceAccountCredentialLifetimeExtension 組織ポリシー制約を構成する必要があります。
FILEPATH: 構成を保存するファイル

認証情報の構成を使用して Google Cloud にアクセスする

ツールとクライアントライブラリが認証情報の構成を使用できるようにするには、AWS または Azure 環境で次の操作を行います。

環境変数 GOOGLE_APPLICATION_CREDENTIALS を初期化し、認証情報の構成ファイルを指すように設定します。
Bash
```
  export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
  
```
FILEPATH は、認証情報の構成ファイルの相対パスです。
PowerShell
```
  $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
  
```
FILEPATH は、認証情報の構成ファイルの相対パスです。
Workload Identity 連携をサポートし、認証情報を自動的に検索できるクライアントライブラリまたはツールを使用します。
C++
C++ 用 Google Cloud クライアントライブラリは、バージョン v2.6.0 から Workload Identity 連携をサポートしています。Workload Identity 連携を使用するには、バージョン 1.36.0 以降の gRPC でクライアントライブラリをビルドする必要があります。
Go
Go 用クライアントライブラリは、golang.org/x/oauth2 モジュールのバージョン v0.0.0-20210218202405-ba52d332ba99 以降を使用している場合、ID 連携をサポートします。

クライアントライブラリが使用しているこのモジュールのバージョンを確認するには、次のコマンドを実行します。
```
cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2
```
Java
Java 用クライアントライブラリは、com.google.auth:google-auth-library-oauth2-http アーティファクトのバージョン 0.24.0 以降を使用している場合、ID 連携をサポートします。

クライアントライブラリで使用しているこのアーティファクトのバージョンを確認するには、アプリケーションディレクトリで次の Maven コマンドを実行します。
```
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
```
Node.js
Node.js 用クライアントライブラリは、google-auth-library パッケージのバージョン 7.0.2 以降を使用している場合、Workload Identity 連携をサポートします。

クライアントライブラリで使用されているこのパッケージのバージョンを確認するには、アプリケーションディレクトリで次のコマンドを実行します。
```
npm list google-auth-library
```
GoogleAuth オブジェクトを作成するときに、プロジェクト ID を指定できます。また、GoogleAuth で自動的にプロジェクト ID を検出することもできます。プロジェクト ID を自動的に検出するには、構成ファイルのサービスアカウントに、プロジェクト上でブラウザのロール（roles/browser）または同等の権限を持つロールが付与されている必要があります。詳細については、google-auth-library パッケージの README をご覧ください。
Python
Python 用クライアントライブラリは、google-auth パッケージのバージョン 1.27.0 以降を使用している場合、ID 連携をサポートします。

クライアントライブラリで使用されているこのパッケージのバージョンを確認するには、パッケージがインストールされている環境で次のコマンドを実行します。
```
pip show google-auth
```
認証クライアントのプロジェクト ID を指定するには、GOOGLE_CLOUD_PROJECT 環境変数を設定するか、クライアントがプロジェクト ID を自動的に検出するようにします。プロジェクト ID を自動的に検出するには、構成ファイルのサービスアカウントに、プロジェクト上でブラウザのロール（roles/browser）または同等の権限を持つロールが付与されている必要があります。詳細については、google-auth パッケージのユーザーガイドをご覧ください。
gcloud
Workload Identity 連携を使用して認証するには、gcloud auth login コマンドを使用します。
```
gcloud auth login --cred-file=FILEPATH.json
```
FILEPATH は、認証情報の構成ファイルのパスに置き換えます。

gcloud CLI での Workload Identity 連携は、gcloud CLI のバージョン 363.0.0 以降でサポートされています。
Terraform
バージョン 3.61.0 以降を使用している場合、Google Cloud プロバイダは Workload Identity 連携をサポートしています。
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 3.61.0"
    }
  }
}
```
gsutil
Workload Identity 連携を使用して認証を行うには、次のいずれかの方法を使用します。

gsutil と gcloud を併用する場合は、通常どおりログインします。
```
gcloud auth login --cred-file=FILEPATH.json
```
gsutil をスタンドアロンコマンドラインアプリケーションとして使用する場合は、.boto ファイルを編集して次のセクションを含めます。
```
[Credentials]
gs_external_account_file = FILEPATH
```
いずれの場合も、FILEPATH を認証情報の構成ファイルのパスに置き換えます。

gsutil での Workload Identity 連携は、gcloud CLI のバージョン 379.0.0 以降でサポートされています。
bq
Workload Identity 連携を使用して認証するには、次のように gcloud auth login コマンドを使用します。
```
gcloud auth login --cred-file=FILEPATH.json
```
FILEPATH は、認証情報の構成ファイルのパスに置き換えます。

bq での Workload Identity 連携は、gcloud CLI のバージョン 390.0.0 以降でサポートされています。
Workload Identity 連携をサポートするクライアントライブラリを使用できない場合は、REST API を使用してプログラムで認証できます。

高度なシナリオ

REST API を使用してワークロードを認証する

クライアントライブラリを使用できない場合は、REST API を使用して外部ワークロードで有効期間の短いアクセストークンを取得できるように、次の手順を行います。

外部 IdP から認証情報を取得します。

AWS

有効なリクエスト署名など、AWS GetCallerIdentity() エンドポイントへのリクエストに通常含まれる情報を含む JSON ドキュメントを作成します。

Workload Identity 連携では、この JSON ドキュメントを GetCallerIdentity トークンと呼びます。このトークンを使用すると、Workload Identity 連携で AWS シークレットアクセスキーを公開せずに ID を確認できます。

GetCallerIdentity トークンは次のような形式になります。

{
  "url": "https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
  "method": "POST",
  "headers": [
    {
      "key": "Authorization",
      "value" : "AWS4-HMAC-SHA256 Credential=AKIASOZTBDV4D7ABCDEDF/20200228/us-east-1/sts/aws4_request, SignedHeaders=host;x-amz-date,Signature=abcedefdfedfd"
    },
    {
      "key": "host",
      "value": "sts.amazonaws.com"
    },
    {
      "key": "x-amz-date",
      "value": "20200228T225005Z"
    },
    {
      "key": "x-goog-cloud-target-resource",
      "value": "//iam.googleapis.com/projects/12345678/locations/global/workloadIdentityPools/my-pool/providers/my-aws-provider"
    },
    {
      "key": "x-amz-security-token",
      "value": "GizFWJTqYX...xJ55YoJ8E9HNU="
    }
  ]
}

このトークンには次のフィールドがあります。

url: GetCallerIdentity() の AWS STS エンドポイントの URL。標準の GetCallerIdentity() リクエストの本文がクエリパラメータとして追加されます。例: https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15。リージョン STS エンドポイントを使用して、ワークロードに適した信頼性の高いインフラストラクチャを設計することをおすすめします。詳細については、リージョン AWS STS エンドポイントをご覧ください。
method: HTTP リクエストメソッド: POST。
headers: HTTP リクエストヘッダー。次の情報を含める必要があります。
- Authorization: リクエストの署名。
- host: url フィールドのホスト名。たとえば、sts.amazonaws.com。
- x-amz-date: リクエストを送信する時刻。ISO 8601 の基本文字列の形式になります。通常、この値は現在の時刻に設定され、リプレイ攻撃の防止に使用されます。
- x-goog-cloud-target-resource: https: 接頭辞のない ID プロバイダの完全なリソース名。次に例を示します。
```
//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
- x-amz-security-token: セッションのトークン。一時的なセキュリティ認証情報を使用する場合にのみ必要です。

次の例では、URL エンコードされた GetCallerIdentity トークンを作成します。後で使用するために、URL エンコードされたトークンを抽出します。また、参照用に人間が読める形式のトークンも作成します。

import json
import urllib

import boto3
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest

def create_token_aws(project_number: str, pool_id: str, provider_id: str) -> None:
    # Prepare a GetCallerIdentity request.
    request = AWSRequest(
        method="POST",
        url="https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15",
        headers={
            "Host": "sts.amazonaws.com",
            "x-goog-cloud-target-resource": f"//iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/providers/{provider_id}",
        },
    )

    # Set the session credentials and Sign the request.
    # get_credentials loads the required credentials as environment variables.
    # Refer:
    # https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
    SigV4Auth(boto3.Session().get_credentials(), "sts", "us-east-1").add_auth(request)

    # Create token from signed request.
    token = {"url": request.url, "method": request.method, "headers": []}
    for key, value in request.headers.items():
        token["headers"].append({"key": key, "value": value})

    # The token lets workload identity federation verify the identity without revealing the AWS secret access key.
    print("Token:\n%s" % json.dumps(token, indent=2, sort_keys=True))
    print("URL encoded token:\n%s" % urllib.parse.quote(json.dumps(token)))

def main() -> None:
    # TODO(Developer): Replace the below credentials.
    # project_number: Google Project number (not the project id)
    project_number = "my-project-number"
    pool_id = "my-pool-id"
    provider_id = "my-provider-id"

    create_token_aws(project_number, pool_id, provider_id)

if __name__ == "__main__":
    main()

次の変数を初期化します。

Bash

SUBJECT_TOKEN_TYPE="urn:ietf:params:aws:token-type:aws4_request"
SUBJECT_TOKEN=TOKEN

PowerShell

$SubjectTokenType = "urn:ietf:params:aws:token-type:aws4_request"
$SubjectToken = "TOKEN"

TOKEN は、上記のスクリプトによって生成された、URL エンコードされた GetCallerIdentity トークンです。

Azure

マネージド ID が割り当てられている Azure VM に接続し、Azure Instance Metadata Service（IMDS）からアクセストークンを取得します。

Bash

SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
SUBJECT_TOKEN=$(curl \
  "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
  -H "Metadata: true" | jq -r .access_token)
echo $SUBJECT_TOKEN

このコマンドは jq ツールを使用します。Cloud Shell では jq がデフォルトで使用されます。

PowerShell

$SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
$SubjectToken = (Invoke-RestMethod `
  -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
  -Headers @{Metadata="true"}).access_token
Write-Host $SubjectToken

APP_ID_URI は、Workload Identity 連携用に構成したアプリケーションのアプリケーション ID URI です。

Security Token Service API を使用して、有効期間の短いアクセストークンと認証情報を交換します。

Bash

STS_TOKEN=$(curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=$SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=$SUBJECT_TOKEN" | jq -r .access_token)
echo $STS_TOKEN

PowerShell

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
$StsToken = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://sts.googleapis.com/v1/token" `
    -ContentType "application/json" `
    -Body (@{
        "audience"           = "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID"
        "grantType"          = "urn:ietf:params:oauth:grant-type:token-exchange"
        "requestedTokenType" = "urn:ietf:params:oauth:token-type:access_token"
        "scope"              = "https://www.googleapis.com/auth/cloud-platform"
        "subjectTokenType"   = $SubjectTokenType
        "subjectToken"       = $SubjectToken
    } | ConvertTo-Json)).access_token
Write-Host $StsToken

次の値を置き換えます。

PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
POOL_ID: Workload Identity プールの ID
PROVIDER_ID: Workload Identity プールプロバイダの ID

セキュリティトークンサービスから取得したトークンを使用して、IAM Service Account Credentials API の generateAccessToken メソッドを呼び出し、アクセストークンを取得します。

Bash

ACCESS_TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken \
    -H "Content-Type: text/json; charset=utf-8" \
    -H "Authorization: Bearer $STS_TOKEN" \
    -d @- <<EOF | jq -r .accessToken
    {
        "scope": [ "https://www.googleapis.com/auth/cloud-platform" ]
    }
EOF
)
echo $ACCESS_TOKEN

PowerShell

$AccessToken = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" `
    -Headers @{ "Authorization" = "Bearer $StsToken" } `
    -ContentType "application/json" `
    -Body (@{
        "scope" = , "https://www.googleapis.com/auth/cloud-platform"
    } | ConvertTo-Json)).accessToken
Write-Host $AccessToken

SERVICE_ACCOUNT_EMAIL は、サービスアカウントのメールアドレスに置き換えます。

次のステップ

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

AWS または Azure との Workload Identity 連携を構成する

始める前に

コンソール

gcloud

Python

外部 ID プロバイダを準備する

AWS

Azure

Workload Identity 連携を構成する

属性のマッピングと条件を定義する

AWS

Azure

Bash

PowerShell

AWS

Azure

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

必要なロール

コンソール

AWS

Azure

gcloud

AWS

Azure

ワークロードの認証

外部ワークロードのサービス アカウントを作成する

外部ワークロードにサービス アカウントの権限借用を許可する

コンソール

gcloud

サブジェクト

グループ

属性

認証情報構成を作成する

コンソール

AWS

Azure

gcloud

AWS

Azure

認証情報の構成を使用して Google Cloud にアクセスする

Bash

PowerShell

C++

Go

Java

Node.js

Python

gcloud

Terraform

gsutil

bq

高度なシナリオ

REST API を使用してワークロードを認証する

AWS

Bash

PowerShell

Azure

Bash

PowerShell

Bash

PowerShell

Bash

PowerShell

次のステップ

外部ワークロードのサービスアカウントを作成する

外部ワークロードにサービスアカウントの権限借用を許可する