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 にアクセスできます。

始める前に

• 認証を設定します。

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  Python

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

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. 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 の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

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

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

Workload Identity 連携を構成する

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

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

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

   Go to project selector

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

2. 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

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

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

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

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

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}')

google.subject=assertion.sub

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

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

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

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

ワークロードの認証

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

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

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

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"

認証情報の構成をダウンロードまたは作成する

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

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

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

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

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

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

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

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

1. 環境変数 GOOGLE_APPLICATION_CREDENTIALS を初期化し、認証情報の構成ファイルを指すように設定します。

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   FILEPATH は、認証情報の構成ファイルの相対パスです。

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   FILEPATH は、認証情報の構成ファイルの相対パスです。

2. 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 以降を使用している場合、Workload Identity 連携をサポートします。

   クライアント ライブラリが使用しているこのモジュールのバージョンを確認するには、次のコマンドを実行します。

   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 以降を使用している場合、Workload Identity 連携をサポートします。

   クライアント ライブラリで使用しているこのアーティファクトのバージョンを確認するには、アプリケーション ディレクトリで次の 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 以降を使用している場合、Workload Identity 連携をサポートします。

   クライアント ライブラリで使用されているこのパッケージのバージョンを確認するには、パッケージがインストールされている環境で次のコマンドを実行します。

   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"
       }
     }
   }
   

   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 を使用して外部ワークロードで有効期間の短いアクセス トークンを取得できるように、次の手順を行います。

1. 外部 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 です。

2. 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

3. サービス アカウントの権限借用を使用する場合は、セキュリティ トークン サービスから取得したトークンを使用して、IAM Service Account Credentials API の generateAccessToken メソッドを呼び出し、アクセス トークンを取得します。

Cloud Run サービスのトークン

Cloud Run サービスにアクセスする場合は、ID トークンを使用する必要があります。

TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken \
    -H "Content-Type: text/json; charset=utf-8" \
    -H "Authorization: Bearer $STS_TOKEN" \
    -d @- <<EOF | jq -r .token
    {
        "audience": "SERVICE_URL"
    }
EOF
)
echo $TOKEN

$Token = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken" `
    -Headers @{ "Authorization" = "Bearer $StsToken" } `
    -ContentType "application/json" `
    -Body (@{
        "audience" = "SERVICE_URL"
    } | ConvertTo-Json)).token
Write-Host $Token

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

• SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス。
• SERVICE_URL: サービスの URL（例: https://my-service-12345-us-central1.run.app）。カスタム サービス エンドポイントに設定することもできます。詳細については、カスタム オーディエンスについてをご覧ください。

他のプラットフォーム用のトークン

別のサービスにアクセスする場合は、アクセス トークンを使用する必要があります。

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 $TOKEN

$Token = (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 $Token

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

• SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス。

次のステップ

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