Workload Identity 連携の構成

このガイドでは、外部 ID プロバイダによって発行された認証情報を使用して、サービス アカウントの権限を借用し、Google Cloud のリソースにアクセスする方法について説明します。このプロセスは Workload Identity 連携と呼ばれます。

Workload Identity 連携の一般的なユースケースは次のとおりです。

  • Google Cloud の外部で実行されるバックグラウンド アプリケーションまたは継続的インテグレーション / 継続的デリバリー(CI / CD)パイプラインを有効にして、Google Cloud のリソースと API にアクセスできるようにする。
  • Google Cloud の外部で実行されるウェブ アプリケーションのユーザーが、Cloud Storage や BigQuery などの Google Cloud サービスに保存されているデータにアクセスできるようにする。

Workload Identity 連携を使用するには、Amazon Web Services(AWS)、Azure Active Directory(AD)、OIDC 互換 ID プロバイダ、または SAML 2.0 対応 ID プロバイダ(プレビュー)などの外部 ID プロバイダを信頼するように Google Cloud を構成します。これにより、外部 ID プロバイダから発行された認証情報をアプリケーションで使用し、次のようにサービス アカウントの権限を借用できるようになります。

  1. 信頼できる ID プロバイダから認証情報を取得します。
  2. Security Token Service から取得したトークンと認証情報を交換します。
  3. Security Token Service のトークンを使用してサービス アカウントの権限を借用し、有効期間の短い Google アクセス トークンを取得します

Workload Identity 連携を使用することで、サービス アカウント キーを保存して管理する必要がなくなります。

始める前に

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

    API を有効にする

  • プロジェクトに Workload Identity プール管理者(roles/iam.workloadIdentityPoolAdmin)とサービス アカウント管理者(roles/iam.serviceAccountAdmin)のロールがあることを確認します。

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

  • 追加のプロバイダ別手順

    SAML

    SAML 2.0 対応 ID プロバイダを使用して連携を構成する場合は、次の手順も完了する必要があります。

    • Workload Identity 連携の構成時に使用するプロジェクトを特定する。

    • Google Cloud アカウント チームに、プロジェクトの SAML 2.0 プレビューへのアクセスをリクエストするよう依頼してください。プレビューへのアクセスが許可されると、Google Cloud アカウント チームから通知が送信されます。

    • SAML 2.0 ID プロバイダから Workload Identity 連携を構成するには、gcloud ツールを使用する必要があります。SAML プレビューへのアクセスが許可されているプロジェクトに billing/quota_project を構成します。

外部 ID プロバイダの準備

Workload Identity 連携を使用するには、プロジェクトで Workload Identity プールWorkload Identity プール プロバイダを構成する必要があります。

AWS

AWS ユーザーAWS ロールは、永続的または一時的な AWS セキュリティ認証情報を使用して、Google Cloud のサービス アカウントの権限を借用できます。

AWS セキュリティ認証情報を使用できるようにするには、AWS アカウントを信頼するように Workload Identity プールを構成する必要があります。これにより、この AWS アカウントに発行されたセキュリティ認証情報トークンが Workload Identity 連携で認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

Azure

Azure ユーザーとサービス プリンシパルは、Azure AD アクセス トークンを使用して Google Cloud のサービス アカウントの権限を借用できます。

Azure AD アクセス トークンの使用を許可するには、Azure AD アプリケーションを信頼するように Workload Identity プールを構成する必要があります。これにより、このアプリケーションに発行されたアクセス トークンが Workload Identity 連携で認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

Azure AD で新しいアプリケーションを作成し、そのアプリケーションを Google Cloud の認証情報の取得のみに使用することをおすすめします。

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

  2. アプリケーションにアプリケーション ID URI を設定します。

    カスタム アプリケーション ID URI を定義する代わりに、次の URI を使用できます。

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

    次の値を置き換えます。

    • PROJECT_NUMBER: Workload Identity プールの作成に使用する Google Cloud プロジェクトのプロジェクト番号
    • POOL_ID: Workload Identity プールを識別する任意の ID。後で Workload Identity プールを作成するときに、この ID を使用する必要があります。
    • PROVIDER_ID: Workload Identity プールのプロバイダを識別する任意の ID。後で Workload Identity プールのプロバイダを作成するときに、この ID を使用する必要があります。

    この形式を使用することで、アプリケーション ID URI によって Workload Identity プールのプロバイダが一意に識別されます。

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

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

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

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

OIDC

ID トークンを使用するか、OIDC 準拠の ID プロバイダから発行される JSON ウェブトークン形式のアクセス トークンを使用して、ユーザーとアプリケーションが Google Cloud でサービス アカウントの権限を借用できるようにします。

これらのトークンの使用を許可するには、外部 ID プロバイダを信頼するように Workload Identity プールを構成する必要があります。これにより、外部 ID プロバイダによって発行されたトークンが Workload Identity 連携によって認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

Workload Identity 連携を使用するには、ID プロバイダの OIDC メタデータ URI がインターネットからアクセス可能で、エンドポイント ISSUER/.well-known/openid-configuration を使用する必要があります。ここで ISSUER は、プロバイダを一意に識別する発行者 URL です。Google からメタデータ エンドポイントにクエリを実行して、プロバイダの JSON ウェブ キー セット(JWKS)を取得し、このキーセットを使用してトークンを検証します。

ID トークンはユーザーの ID を反映しているため、トークンの交換時に ID トークンを使用することをおすすめします。アクセス トークンを使用する場合は、Google Cloud の認証情報の取得のみを行う専用のアプリケーションまたはリソースを ID プロバイダに構成します。

SAML

SAML 2.0 対応 ID プロバイダによって発行されたアサーションを使用して、ユーザーとアプリケーションが Google Cloud でサービス アカウントの権限を借用できるようにします。暗号化されたアサーションを使用した連携はサポートされません。

ご利用の SAML ID プロバイダを構成し、Workload Identity プール プロバイダを含むアサーションを、オーディエンスとして https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID 形式で発行します。

このようなアサーションの使用を許可するには、SAML ID プロバイダのメタデータ ドキュメントを提供して、外部 ID プロバイダを信頼するように Workload Identity プールを構成する必要があります。

次に、Workload Identity 連携は、外部 ID プロバイダによって発行されたアサーションを認識します。トークンを使用して有効期間が短いサービス アカウント認証情報を取得できます。

連携の構成

外部 ID プロバイダと連携するには、次のことを行う必要があります。

  1. Workload Identity プールとプロバイダを含む Google Cloud プロジェクトを準備します。
  2. ID プロバイダの認証情報を外部 ID にマッピングする属性マッピングを定義します。また、必要に応じて属性条件も定義します。
  3. Workload Identity のプールとプロバイダを作成します。

以降のセクションでは、この手順について詳しく説明します。

プロジェクトを準備する

Workload Identity プールとプロバイダを含むプロジェクトを選択して準備します。

  1. プロジェクトに Workload Identity プール管理者(roles/iam.workloadIdentityPoolAdmin)とサービス アカウント管理者(roles/iam.serviceAccountAdmin)のロールがあることを確認します。

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

  2. 連携を許可するように組織のポリシーを更新します。

  3. IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) API を有効にします。

    API を有効にする

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

ID プロバイダの認証情報を外部 ID にマッピングする属性マッピングを定義します。また、必要に応じて属性条件も定義します。

外部 ID プロバイダから発行された認証情報には、1 つ以上の属性(クレーム)が含まれます。Workload Identity 連携では、これらの属性をアサーション属性として参照し、先頭に assertion. を付けます。

属性マッピングを使用すると、Workload Identity 連携で認識される事前定義済みのターゲット属性にアサーション属性をマッピングできます。これらの定義済みのターゲット属性は次のとおりです。

属性 説明
google.subject 必須。ユーザーの一意の識別子。この属性は、IAM principal:// ロール バインディングで使用され、Cloud Logging のログに表示されます。127 文字以内の一意の値にする必要があります。
google.groups 省略可。ID が属するグループのセット。この属性は、IAM の principalSet:// ロール バインディングでグループのすべてのメンバーにアクセス権を付与する場合に使用されます。
attribute.NAME 省略可。最大で 50 個までのカスタム属性を定義できます。これらの属性を IAM principalSet:// ロール バインディングで使用して、特定の属性を持つすべての ID にアクセス権を付与できます。

属性マッピングの形式は TARGET_ATTRIBUTE=SOURCE_EXPRESSION です。次の例をご覧ください。

  • このマッピングでは、アサーション属性 subgoogle.subject に割り当てられます。

    google.subject=assertion.sub
    
  • このマッピングでは、Common Expression Language(CEL)式を使用して、複数のアサーション属性を連結します。

    google.subject="myprovider::" + assertion.aud + "::" + assertion.sub
    
  • このマッピングでは、別の CEL 式を使用して GUID 値のアサーション属性 workload_id を名前にマッピングし、結果を attribute.my_display_name という名前のカスタム属性に割り当てます。

    attribute.my_display_name={
      "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1",
      "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2"
    }[assertion.workload_id]
    
  • このマッピングでは、CEL の論理演算子と関数を使用して、ID の Amazon リソース名(ARN)に応じて、attribute.environment という名前のカスタム属性を prod または test に設定します。

    attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"
    
  • このマッピングでは、extract 関数を使用して、想定されたロールの名前カスタム属性 aws_role に設定します。想定されたロールがない場合は、ID の ARN が設定されます。

    attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn
    

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

ユースケースに適した属性マッピングと条件を選択するため、サービス ID とユーザー ID のどちらをマッピングするかを決める必要があります。

  • サービス ID をマッピングすると、Google Cloud の外部で実行されるバックグラウンド アプリケーションまたは CI / CD パイプラインを有効にして、有効期間の短い Google Cloud の認証情報を取得できます。アプリケーションは、ユーザーの操作なしで、これらの認証情報を取得できます。
  • ユーザー ID をマッピングすると、Google Cloud の外部で実行されているアプリケーションのユーザーが有効期間の短い Google Cloud の認証情報を取得できます。アプリケーションは、ユーザーに代わってこの認証情報を取得します。

サービス ID のマッピング

AWS

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

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

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

google.subject=assertion.arn
attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

このマッピングにより、特定の EC2 インスタンスにサービス アカウントの借用権限を付与できます。また、ロールごと付与することもできます。

AWS アカウントに多くのユーザーとロールが含まれている場合がありますが、Google Cloud リソースへのアクセスが必要になるのはごく一部です。Workload Identity 連携を使用できるユーザーとロールのセットを制限するには、属性条件を使用します。たとえば、次の条件を使用すると、Google Cloud リソースへのアクセスを特定のアカウントに限定できます。

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

Azure

属性マッピングでは、ソース属性として Azure アクセス トークンに埋め込まれたクレーム(カスタム クレームを含む)を使用できます。

参照可能なクレームの完全なリストを取得するには、マネージド ID が割り当てられている Azure VM に接続し、次の操作を行います。

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

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

  3. アクセス トークンに埋め込まれたクレームのリストを表示するには、[Claims] をクリックします。

サービス プリンシパルで認証するには、次の属性マッピングを使用します。

google.subject=assertion.sub

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

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

有効期間の短い Google Cloud の認証情報を取得できる ID を制限する場合は、属性条件を定義しないでください。代わりに、アプリロールの割り当てを使用するように Azure AD アプリケーションを構成します。

OIDC

属性マッピングでは、外部 ID プロバイダから発行された ID トークンまたはアクセス トークンに埋め込まれたクレームを使用できます。

ユーザーを一意に識別するため、これらのクレームのいずれかを google.subject にマッピングする必要があります。なりすましの脅威から保護するため、変更できない一意の値を持つクレームを選択します。

多くの ID プロバイダは、変更できない一意 ID を sub クレームに設定します。こうした ID プロバイダの場合は、sub クレームを google.subject にマッピングすることを検討してください。

google.subject=assertion.sub

email のようなクレームをこの目的で使用しないでください。通常、メールアドレスは再割り当てまたは変更が可能なため、ユーザーを一意に識別することはできません。

ID プロバイダに多くのユーザーが含まれている場合がありますが、Google Cloud リソースへのアクセスが必要になるのはごく一部です。Workload Identity 連携を使用できるユーザーと認証情報のセットを制限するために、属性条件を使用することもできます。

たとえば、次の条件では、値が true のカスタム service_account クレームを含むトークンにのみアクセスを許可します。

assertion.service_account==true

SAML

属性マッピングでは、外部 ID プロバイダによって発行されたアサーションに埋め込まれた 要素と 要素を使用できます。SAML 属性は、次のキーワードを使用して参照できます。

  • assertion.subject には、<Subject> 要素にある認証済みユーザーの NameID が含まれます。
  • assertion.attributes['ATTRIBUTE_NAME'] には、同じ名前の <Attribute> の値のリストが格納されています。

ユーザーを一意に識別するため、これらのクレームのいずれかを google.subject にマッピングする必要があります。なりすましの脅威から保護するため、変更できない一意の値を持つクレームを選択します。

多くの ID プロバイダは、変更できない一意 ID を NameId に設定します。こうした ID プロバイダの場合は、NameId 属性を google.subject にマッピングすることを検討してください。

google.subject=assertion.subject

この目的で http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress のような属性を使用しないでください。通常、メールアドレスは再割り当てまたは変更が可能なため、ユーザーを一意かつ永続的に識別することはできません。

ID プロバイダに多くのユーザーが含まれている場合がありますが、Google Cloud リソースへのアクセスが必要になるのはごく一部です。Workload Identity 連携を使用できるユーザーと認証情報のセットを制限するために、属性条件を使用することもできます。

たとえば、次の条件は、値が true のカスタム https://example.com/SAML/Attributes/AllowGcpFederation 属性を含むアサーションへのアクセスを制限します。

assertion.attributes['https://idp.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

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

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

Console

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

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

  2. [ID プールを作成] に、次のように入力します。

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

  4. [プロバイダの選択] プルダウン リストでプロバイダを選択します。

    • AWS: AWS と連携している場合。
    • OpenID Connect(OIDC): Microsoft Azure などの OIDC 互換プロバイダと連携する場合。
    • Cloud Console を使用して SAML 2.0 ID プロバイダから Workload Identity 連携を構成することはできません。SAML 2.0 ID プロバイダから Workload Identity 連携を構成するには、gcloud ツールを使用する必要があります。
  5. [プロバイダの詳細] に次のように入力します。

    • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
    • AWS アカウント ID(AWS のみ): AWS アカウント ID
    • 発行元 URL(OIDC のみ): 発行元の URI。このページの発行元 URI の確認手順をご覧ください。
  6. [続行] をクリックします。

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

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

  9. [保存] をクリックして、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

    gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
      --location="global"  \
      --workload-identity-pool="POOL_ID" \
      --account-id="AWS_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

    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。このパラメータは、カスタム アプリケーション 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"
    

    OIDC

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --allowed-audiences="AUDIENCE" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    次の値を置き換えます。

    • POOL_ID: プールの ID。
    • ISSUER: OIDC メタデータで定義されている発行元 URI。
    • AUDIENCE: ID トークンに想定されるオーディエンス。多くのプロバイダでは、オーディエンスがクライアント ID と一致しています。
    • MAPPINGS: 前に確認した属性マッピングのカンマ区切りのリスト。
    • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

    SAML

    gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --idp-metadata-path="IDP_METADATA_PATH" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    次の値を置き換えます。

    • POOL_ID: プールの ID。
    • IDP_METADATA_PATH: SAML ID プロバイダの IdP メタデータ ドキュメントを取得するためのローカル ファイルパス。
    • MAPPINGS: 前に確認した属性マッピングのカンマ区切りのリスト。
    • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

    例:

    gcloud iam workload-identity-pools providers create-saml example-provider \
        --location="global" \
        --workload-identity-pool="pool-1" \
        --idp-metadata-path="/path/to/idp_metadata.xml" \
        --attribute-mapping="google.subject=assertion.subject,google.groups=assertion.attributes.groups"
    

    次のエラーが表示された場合:

    INVALID_ARGUMENT: Invalid WorkloadIdentityPoolProvider IDP configuration: PROVIDERCONFIG_NOT_SET.
    

    SAML プレビュー アクセス リクエスト ページで説明されている手順を完了していることを確認します。

次のステップ