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

外部 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 認証情報と交換できます。

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

  1. Azure AD アプリケーションとサービス プリンシパルを作成します

  2. アプリケーションにアプリケーション ID URI を設定します。デフォルトのアプリケーション ID URI(api://APPID)を使用することも、カスタム URI を指定することもできます。

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

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

  1. マネージド ID を作成します。マネージド ID のオブジェクト ID をメモします。これは、後で権限借用を構成するときに必要になります。

  2. アプリケーションを実行する仮想マシンまたは別のリソースにマネージド ID を割り当てます。

Workload Identity 連携を構成する

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

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

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

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

  2. Workload Identity プールとプロバイダの管理に専用のプロジェクトを使用することをおすすめします。
  3. Google Cloud プロジェクトで課金が有効になっていることを確認します

  4. 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 が含まれます。別のクレームを使用する場合は、そのクレームが一意であり、再割り当てできないことを確認してください。

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

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

  2. 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 に置き換えます。

  3. ウェブブラウザで https://jwt.ms/ に移動し、アクセス トークンをテキスト ボックスに貼り付けます。

  4. アクセス トークンに埋め込まれたクレームのリストを表示するには、[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 ロールを付与するよう管理者に依頼してください。

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

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

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

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

コンソール

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

    [新しいワークロード プロバイダとプール] に移動

  2. [ID プールを作成する] セクションで、次のように入力します。

    • 名前: プールの名前。この名前はプール ID としても使用されます。プール ID を後で変更することはできません。
    • 説明: プールの目的を説明するテキスト。
  3. [続行] をクリックします。

  4. プロバイダを構成します。

    AWS

    次のプロバイダを構成します。

    • プロバイダを選択: AWS
    • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。

    Azure

    次のプロバイダを構成します。

    • プロバイダを選択: OpenID Connect(OIDC)
    • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
    • 発行元 URL: https://sts.windows.net/TENANT_IDTENANT_ID は、Azure AD テナントのテナント ID(GUID)に置き換えます。
    • 許可された対象: Azure AD でアプリケーションを登録したときに使用したアプリケーション ID URI
  5. [続行] をクリックします。

  6. [プロバイダの属性を構成する] セクションで、前に確認した属性マッピングを追加します。

  7. [属性条件] セクションで、前に確認した属性条件を入力します。属性条件がない場合は、空白のままにします。

  8. [保存] をクリックして、Workload Identity のプールとプロバイダを作成します。

gcloud

  1. 新しい 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 へのアクセス権を付与するときに表示されます。
  2. 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"
    

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

    例:

    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="https://sts.windows.net/TENANT_ID" \
        --allowed-audiences="APPLICATION_ID_URI" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

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

    • PROVIDER_ID: プロバイダの一意の ID。
    • POOL_ID: プールの ID。
    • TENANT_ID: Azure AD テナントのテナント ID(GUID)。
    • 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 回行う必要があります。

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

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

    API を有効にする

  2. ワークロードを表すサービス アカウントを作成します。ワークロードごとに専用のサービス アカウントを使用することをおすすめします。

    サービス アカウントは、Workload Identity プールと同じプロジェクトにある必要はありません。

  3. 外部 ID にアクセスを許可するリソースに対するアクセス権をサービス アカウントに付与します。

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

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

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

コンソール

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

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

    [Workload Identity プール] に移動

  2. 更新する Workload Identity プールを見つけて選択します。

  3. 選択した Workload Identity プールへのアクセス権を付与するには、[ アクセスを許可] をクリックします。

  4. [サービス アカウント] リストで、権限を借用する外部 ID のサービス アカウントを選択します。

  5. サービス アカウントの権限を借用するプール内の ID を選択するには、次のいずれかを行います。

    • Workload Identity プールの特定の ID のみにサービス アカウントの権限借用を許可するには、[フィルタに一致する ID のみ] を選択します。

      [属性名] リストで、フィルタする属性を選択します。

      [属性値] フィールドに、属性の想定値を入力します。たとえば、属性マッピング google.subject=assertion.sub を使用する場合は、属性名を subject に設定します。属性値には、外部 ID プロバイダによって発行されたトークンの sub クレームの値を設定します。

  6. 構成を保存するには、[保存]、[閉じる] の順にクリックします。

gcloud

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

  1. 現在のプロジェクトのプロジェクト番号を取得するには、次のコマンドを実行します。

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. 特定の条件を満たす外部 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 コンソールで、認証情報の構成ファイルをダウンロードします。

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

    [Workload Identity プール] に移動

  2. 使用する IdP を含む Workload Identity プールを見つけてクリックします。

  3. [接続済みサービス アカウント] を選択します。

  4. 使用するサービス アカウントを見つけて、[ダウンロード] をクリックします。

  5. [アプリケーションの構成] ダイアログで、サービス アカウントの権限を借用する外部 ID を含むプロバイダを選択します。

  6. 次の追加設定を行います。

    AWS

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

    Azure

    リソースパス: Azure アプリケーションのアプリケーション ID URI

  7. [構成をダウンロード] を選択して認証情報の構成ファイルをダウンロードしてから、[閉じる] をクリックします。

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 環境で次の操作を行います。

  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 クライアント ライブラリのほとんどは、grpc::GoogleDefaultCredentials() を呼び出して作成される ChannelCredentials オブジェクトを使用して ID 連携をサポートしています。この認証情報を初期化するには、バージョン 1.36.0 以降の gRPC でクライアント ライブラリを構築する必要があります。

    C++ 用の Cloud Storage クライアント ライブラリでは、gRPC ではなく REST API が使用されるため、ID 連携はサポートされません。

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

  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リージョン エンドポイントもサポートされます。
    • 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 APIgenerateAccessToken メソッドを呼び出し、アクセス トークンを取得します。

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 は、サービス アカウントのメールアドレスに置き換えます。

次のステップ