他の ID プロバイダとの Workload Identity 連携を構成する

このガイドでは、他の ID プロバイダ（IdP）との Workload Identity 連携を使用する方法について説明します。

Google Cloud の外部で実行されるワークロードは、既存の環境固有の認証情報にアクセスできる場合があります。次に例を示します。

ワークロードは、同じ環境で実行されている ID プロバイダ（IdP）から SAML アサーションまたは OpenID Connect（OIDC）トークンを取得できます。

Google Cloud で認証を行うには、Workload Identity 連携を使用して、ワークロードが環境固有の認証情報を有効期間の短い Google Cloud 認証情報に交換できるようにします。
ワークロードには、mTLS クライアント証明書など、他の種類の認証情報がある場合があります。

Workload Identity 連携とカスタムトークンブローカーを組み合わせることで、ワークロードで他のタイプの認証情報を使用して有効期間の短い Google Cloud 認証情報を取得できます。

Workload Identity 連携を使用すると、ローテーションが必要な認証情報の数を減らすことができます。

以降のセクションでは、OpenID Connect（OIDC）または SAML 認証プロトコルをサポートする IdP と Workload Identity 連携を使用する方法について説明します。

外部 IdP を準備する

この手順は、IdP ごとに 1 回だけ行います。

始める前に、外部 IdP が次の要件を満たしていることを確認します。

OIDC

IdP は OpenID Connect 1.0 をサポートしています。
IdP の OIDC メタデータと JWKS エンドポイントは SSL と TLS で保護されています。エンドポイント URL は https:// で始まり、インターネット経由で一般公開されています。

Google Cloud はこれらのエンドポイントを使用して IdP の鍵セットをダウンロードし、この鍵セットを使用してトークンを検証します。

自己署名証明書で保護されているエンドポイントは、Google Cloud ではサポートされていません。

SAML

IdP は SAML 2.0 をサポートしています。
IdP には、SAML サービスプロバイダの構成と IdP の署名証明書を含む SAML SP メタデータドキュメントが用意されています。

Google Cloud は、この証明書を使用して SAML アサーションとレスポンスを検証します。

IdP がこれらの条件を満たしている場合は、次の操作を行います。

OIDC

ワークロードが次の条件を満たす ID トークンを取得できるように IdP を構成します。

トークンは RS256 または ES256 アルゴリズムを使用して署名されます。
トークンには、次の値を持つ aud クレームが含まれています。
```
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 を使用する必要があります。
また、カスタムオーディエンスを想定するように Workload Identity プールのプロバイダを構成することもできます。
トークンには、将来の exp クレームと過去の iat クレームが含まれています。

exp の値は、iat の値よりも最大で 24 時間大きくする必要があります。

ID トークンはユーザーの ID を反映しているため、トークンの交換時に ID トークンを使用することをおすすめします。アクセストークンを使用する場合は、アクセストークンが次の要件を満たしていることを確認してください。

アクセストークンは JSON Web Token 形式です。
アクセストークンには ISSUER クレームが含まれているため、URL ISSUER/.well-known/openid-configuration は IdP の OIDC メタデータエンドポイントを指しています。
ローカル JWK 鍵をアップロードするには、OIDC JWK を管理するをご覧ください。

SAML

SAML アサーションが次のものを含むように IdP を構成します。

Workload Identity プールプロバイダで構成されたエンティティ ID に設定された Issuer 要素。発行者の形式は省略するか、urn:oasis:names:tc:SAML:2.0:nameid-format:entity に設定する必要があります。
Subject 要素:
- NameID 要素。
- Method が urn:oasis:names:tc:SAML:2.0:cm:bearer に設定された SubjectConfirmation 要素を 1 つだけ使用します。
- NotOnOrAfter に将来のタイムスタンプが設定され、NotBefore 値が設定されていない SubjectConfirmationData 要素。
Conditions 要素:
- NotBefore は省略されているか、過去の日付です。
- NotOnOrAfter は省略されているか、将来の日付です。
- 次の形式の Audience。
```
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 を使用する必要があります。
少なくとも 1 つの AuthnStatement 要素。
将来のタイムスタンプを含む SessionNotOnOrAfter 要素。この要素は省略することもできます。

SAML レスポンスに含まれる SAML アサーションの場合、SAML レスポンスには次のものを含める必要があります。

上記の条件を満たす 1 つのアサーション。
1 時間以上前の値を持つ IssueInstant 属性。
StatusCode urn:oasis:names:tc:SAML:2.0:status:Success。

SAML アサーション、レスポンス、またはその両方に署名する必要があります。

Workload Identity 連携を構成する

この手順は、IdP ごとに 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 を有効にする

OIDC JWK を管理する（省略可）

このセクションでは、Workload Identity プールの oidc プロバイダでセルフアップロードされた OIDC JWK の管理方法について説明します。

プロバイダを作成して OIDC JWK をアップロードする

OIDC JWK を作成するには、JWT、JWS、JWE、JWK、JWA の実装をご覧ください。

Workload Identity プールプロバイダを作成するときに、OIDC JWK ファイルをアップロードするには、--jwk-json-path="JWK_JSON_PATH" を指定して、gcloud iam workload-identity-pools providers create-oidc コマンドを実行します。JWK_JSON_PATH は、JWK JSON ファイルのパスに置き換えます。

これにより、ファイル内の鍵でアップロードされた鍵が作成されます。

OIDC JWK を更新する

OIDC JWK を更新するには、--jwk-json-path="JWK_JSON_PATH" を指定して gcloud iam container-identity-pools providers update-oidc コマンドを実行します。JWK_JSON_PATH は、JWK JSON ファイルのパスに置き換えます。

これにより、既存のアップロード鍵がファイル内の鍵に置き換えられます。置換された鍵は復元できません。

アップロードされたすべての OIDC JWK を削除する

アップロードした OIDC JWK をすべて削除し、発行者 URI を使用して鍵を取得する場合は、--jwk-json-path="JWK_JSON_PATH" を指定して、gcloud iam workload-identity-pools providers update-oidc コマンドを実行します。JWK_JSON_PATH は空のファイルへのパスに置き換えます。--issuer-uri フラグを使用して発行者 URI を設定します。

これにより、既存のアップロード鍵（ファイル内の鍵を含む）がすべて削除されます。削除した鍵は復元できません。

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

IdP が発行する OIDC トークンまたは SAML アサーションに複数の属性が含まれている可能性があるため、Google Cloud でサブジェクト識別子（google.subject）として使用する属性を決める必要があります。

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

OIDC

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

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

多くの IdP は、変更できない一意 ID を sub クレームに設定します。これらの IdP では、sub クレームを google.subject にマッピングすることを検討してください。

google.subject=assertion.sub

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

SAML

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

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

多くの IdP では、変更できない一意 ID が NameId に設定されます。これらの IdP では、NameId 属性を google.subject にマッピングすることを検討してください。

google.subject=assertion.subject

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

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

OIDC

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

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

assertion.service_account==true

SAML

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

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

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

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

必要なロール

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

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

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

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

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

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

コンソール

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

[新しいワークロードプロバイダとプール] に移動
[ID プールを作成] に、次のように入力します。
- 名前: プールの名前。この名前はプール ID としても使用されます。プール ID を後で変更することはできません。
- 説明: プールの目的を説明するテキスト。
[続行] をクリックします。
プロバイダの設定を次のように構成します。
OIDC
- [プロバイダの選択] で、[OpenID Connect（OIDC）] を選択します。
- [プロバイダ名] にプロバイダの名前を入力します。この名前はプロバイダ ID としても使用されます。プロバイダの作成後にプロバイダ ID を変更することはできません。
- [発行元 URL] に、IdP の発行元の URL を入力します。URL の先頭は https:// にする必要があります。
- 省略可: [JWK ファイル（JSON）] で、アップロードする JWK ファイルを選択します。このフィールドが指定されていない場合、Google Cloud は発行者から JWK を取得しようとします。
- 許可するオーディエンス: ID トークンの想定されるオーディエンス。
SAML
- [プロバイダを選択] で、[SAML] を選択します。
- [プロバイダ名] にプロバイダの名前を入力します。この名前はプロバイダ ID としても使用されます。プロバイダの作成後にプロバイダ ID を変更することはできません。
- [IDP メタデータファイル（XML）] で、ID プロバイダから提供された SAML メタデータ XML ドキュメントをアップロードします。
[続行] をクリックします。
[プロバイダの属性を構成する] で、このガイドの前半で確認した属性マッピングを追加します。
[属性条件] で、このガイドの前半で確認した属性条件を入力します。属性条件がない場合は、空白のままにします。
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 プールのプロバイダを追加するには、次のようにします。
OIDC
OIDC Workload Identity プールのプロバイダを追加するには、次のコマンドを実行します。
```
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"
    --jwk-json-path="JWK_JSON_PATH"
```
次のように置き換えます。
- PROVIDER_ID: 一意の Workload Identity プールプロバイダ ID。
- POOL_ID: 前に作成した Workload Identity プール ID。
- ISSUER: OIDC メタデータで定義されている発行者 URI。
- AUDIENCE: ID トークンに想定されるオーディエンス。多くのプロバイダでは、クライアント ID と一致します。
- MAPPINGS: このガイドの前半で作成した属性マッピングのカンマ区切りリスト。
- CONDITIONS: このガイドの前半で作成した属性条件。属性条件がない場合は、パラメータを削除します。
- JWK_JSON_PATH: ローカルにアップロードされた OIDC JWK へのパス（省略可）。このパラメータを指定しない場合、代わりに Google Cloud は IdP の /.well-known/openid-configuration パスを使用して公開鍵を含む JWK を取得します。
SAML
SAML Workload Identity プールのプロバイダを追加するには、次のコマンドを実行します。
```
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 IdP のメタデータドキュメントのローカルファイルパス
- MAPPINGS: このガイドの前半で作成した属性マッピングのカンマ区切りリスト
- CONDITIONS: 省略可。このガイドの前半で作成した属性条件
接頭辞 gcp- は予約されているため、プールやプロバイダ ID では使用できません。

省略可: IdP から暗号化された SAML アサーションを受け入れる

SAML 2.0 IdP が Workload Identity 連携で受け入れられる暗号化された SAML アサーションを生成できるようにするには、次の操作を行います。
- Workload Identity 連携で次の操作を行います。
- IdP で次の操作を行います。
SAML 暗号化プロバイダの鍵が構成されている場合でも、Workload Identity 連携は平文のアサーションを処理できます。

Workload Identity 連携 SAML アサーション暗号鍵を作成する

このセクションでは、Workload Identity 連携で暗号化された SAML アサーションを受け入れる非対称鍵ペアの作成について説明します。

Google Cloud は秘密鍵を使用して、IdP が発行する SAML アサーションを復号します。SAML 暗号化で使用する非対称鍵ペアを作成するには、次のコマンドを実行します。詳細については、サポートされている SAML 暗号化アルゴリズムをご覧ください。
```
gcloud iam workload-identity-pools providers keys create KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION
```
次のように置き換えます。
- KEY_ID: 任意の鍵名
- WORKLOAD_POOL_ID: プール ID
- PROVIDER_ID: プロバイダ ID
- KEY_SPECIFICATION: 鍵仕様（rsa-2048、rsa-3072、rsa-4096 のいずれか）。
鍵ペアを作成したら、次のコマンドを実行して、公開鍵を証明書ファイルにダウンロードします。秘密鍵にアクセスできるのは Workload Identity 連携だけです。
```
gcloud iam workload-identity-pools providers keys describe KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH
```
次のように置き換えます。
- KEY_ID: 鍵名
- WORKLOAD_POOL_ID: プール ID
- PROVIDER_ID: プロバイダ ID
- CERTIFICATE_PATH: 証明書を書き込むパス（例: saml-certificate.cer や saml-certificate.pem）
暗号化された SAML アサーションを発行するように SAML 2.0 準拠の IdP を構成する

前の手順でダウンロードした公開証明書を使用して、発行する SAML アサーションを暗号化するように SAML IdP を構成します。具体的な手順については、IdP チームにお問い合わせください。

SAML アサーションを暗号化するように IdP を構成したら、IdP によって生成されるアサーションが実際に暗号化されていることを確認することをおすすめします。SAML アサーションの暗号化が構成されている場合でも、Workload Identity 連携は平文のアサーションを処理できます。

Workload Identity 連携暗号鍵を削除する
SAML 暗号鍵を削除するには、次のコマンドを実行します。
```
  gcloud iam workload-identity-pools providers keys delete KEY_ID \
      --workload-identity-pool WORKLOAD_POOL_ID \
      --provider PROVIDER_ID \
      --location global
```
次のように置き換えます。
- KEY_ID: 鍵名
- WORKLOAD_POOL_ID: プール ID
- PROVIDER_ID: プロバイダ ID
サポートされている SAML 暗号化アルゴリズム

Workload Identity 連携は、次の主要なトランスポートアルゴリズムをサポートしています。
Workload Identity 連携は、次のブロック暗号化アルゴリズムをサポートしています。

ワークロードの認証を行う

この手順は、ワークロードごとに 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 プールとプロバイダ
権限を借用するサービスアカウント

Cloud クライアントライブラリは、ローカルの実行可能ファイルを実行して、ローカルファイルから外部認証情報（HTTP URL）を取得します。

実行可能ファイル提供の認証情報: ライブラリは、新しい認証情報が必要になるたびに実行可能ファイルを起動します。実行可能ファイルは、新しい外部認証情報の取得に成功した場合、次のような JSON ドキュメントを STDOUT に書き込みます。
OIDC
```
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}
```
実行可能ファイルは、新しい認証情報の取得に失敗した場合は、次のような JSON ドキュメントを STDOUT に書き込みます。
```
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}
```
JSON ドキュメントは次のフィールドを使用します。
- version: JSON 出力のバージョン。現在、バージョン 1 のみがサポートされています。
- success: レスポンスのステータス。
  
  true の場合、レスポンスに id_token フィールドと token_type フィールドが含まれます。実行可能ファイルは終了コード 0 で終了します。
  
  false の場合、レスポンスに code フィールドと message フィールドが含まれ、ゼロ以外の値で終了します。
- token_type: 外部認証情報のトークンの種類。サポートされている値は次の通りです。
  - urn:ietf:params:oauth:token-type:id_token
  - urn:ietf:params:oauth:token-type:jwt
- id_token: 外部認証情報。
- expiration_time: OIDC トークンの有効期限（秒単位）（エポック時間）。このフィールドは、認証情報の構成で出力ファイルが指定されている場合にのみ必要です。
- code: エラーコードの文字列。
- message: エラーメッセージ。
SAML
```
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}
```
実行可能ファイルは、新しい認証情報の取得に失敗した場合は、次のような JSON ドキュメントを STDOUT に書き込みます。
```
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}
```
JSON ドキュメントは次のフィールドを使用します。
- version: JSON 出力のバージョン。現在、バージョン 1 のみがサポートされています。
- success: レスポンスのステータス。
  
  true の場合、レスポンスに id_token フィールドと token_type フィールドが含まれます。実行可能ファイルは終了コード 0 で終了します。
  
  false の場合、レスポンスに code フィールドと message フィールドが含まれ、ゼロ以外の値で終了します。
- token_type: 外部認証情報のトークンの種類。必ず urn:ietf:params:oauth:token-type:saml2 を指定します。
- saml_response: SAML レスポンスまたは Base64 でエンコードされた SAML アサーション。
- expiration_time: アサーションの有効期限（秒単位）（エポック時間）。このフィールドは、認証情報の構成で出力ファイルが指定されている場合にのみ必要です。
- code: エラーコードの文字列。
- message: エラーメッセージ。
実行可能ファイルの起動時に、クライアントライブラリは次の環境変数を設定します。
- GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 認証情報構成のオーディエンス。常に存在します。
- GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 想定されるサブジェクトトークンタイプ。常に存在します。
- GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: サービスアカウントのメールサービスアカウントの権限借用が使用されている場合にのみ存在します。
- GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 認証情報構成の出力ファイルの場所。認証情報の構成で指定されている場合にのみ存在します。
実行可能ファイル提供の認証情報を使用するには、環境変数 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES を 1 に設定する必要があります。
ファイル提供の認証情報: ライブラリは、ローカルの書式なしテキストまたは JSON ファイルから外部認証情報を読み取ります。次に例を示します。
JSON
```
{
  "mytoken": "ey...
}
```
テキスト
```
ey...
```
外部認証情報の例:
- OIDC トークン
- SAML レスポンス
- Base64 でエンコードされた SAML アサーション
常に有効な認証情報が含まれるように、ファイルを定期的に更新する必要があります。たとえば、OIDC トークンまたは SAML アサーションが 1 時間有効な場合、少なくとも 1 時間に 1 回ファイルを更新する必要があります。
URL 提供の認証情報: ライブラリは、新しい認証情報が必要になるたびに HTTP エンドポイントに GET リクエストを実行します。エンドポイントは、ファイル提供の認証情報で使用される形式と同等の書式なしテキストまたは 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 \
    --output-file=FILEPATH.json \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE

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

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: 構成を保存するファイル
EXECUTABLE_COMMAND: OIDC ID トークンを取得するために実行される完全なコマンド（引数を含む）（例: --executable-command="/path/to/command --foo=bar"）
EXECUTABLE_TIMEOUT: 実行可能ファイルの実行を待つオプションの時間（ミリ秒単位）（デフォルトは 30 秒）。
EXECUTABLE_OUTPUT_FILE: このファイルのパスは、実行可能ファイルによって生成された 3PI 認証情報を参照します。これは、認証情報をキャッシュに保存する場合に便利です。このパスを指定すると、Auth ライブラリは実行可能ファイルを実行する前に、まずその存在を確認します。

ファイル提供の認証情報

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 \
    --output-file=FILEPATH.json \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

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

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: 構成を保存するファイル
TOKEN_FILEPATH: OIDC ID トークンが保存されているパス
SOURCE_TYPE: OIDC ID トークンファイルの形式。text（デフォルト）または json に設定します。
FIELD_NAME: トークンを含むテキストファイルのフィールド（SOURCE_TYPE が json の場合）

URL 提供の認証情報

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 \
    --output-file=FILEPATH.json \
    --credential-source-url="TOKEN_URL" \
    --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

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

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: 構成を保存するファイル
TOKEN_URL: OIDC ID トークンを取得する URL
KEY_n、VALUE_n: TOKEN_URL への HTTP リクエストに含めるカスタムヘッダー
SOURCE_TYPE: OIDC ID トークンファイルの形式。text（デフォルト）または json に設定します。
FIELD_NAME: トークンを含むテキストファイルのフィールド（SOURCE_TYPE が json の場合）

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

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

環境変数 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 連携について確認する。
Workload Identity 連携の使用に関するベストプラクティスを確認する。
Workload Identity プールとプロバイダの管理方法を学習する。

他の ID プロバイダとの Workload Identity 連携を構成する

外部 IdP を準備する

OIDC

SAML

OIDC

SAML

Workload Identity 連携を構成する

OIDC JWK を管理する（省略可）

プロバイダを作成して OIDC JWK をアップロードする

OIDC JWK を更新する

アップロードされたすべての OIDC JWK を削除する

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

OIDC

SAML

OIDC

SAML

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

必要なロール

コンソール

OIDC

SAML

gcloud

OIDC

SAML

省略可: IdP から暗号化された SAML アサーションを受け入れる

Workload Identity 連携 SAML アサーション暗号鍵を作成する

暗号化された SAML アサーションを発行するように SAML 2.0 準拠の IdP を構成する

Workload Identity 連携暗号鍵を削除する

サポートされている SAML 暗号化アルゴリズム

ワークロードの認証を行う

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

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

コンソール

gcloud

サブジェクト

グループ

属性

認証情報構成を作成する

OIDC

SAML

JSON

テキスト

実行可能ファイル提供の認証情報

ファイル提供の認証情報

URL 提供の認証情報

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

Bash

PowerShell

C++

Go

Java

Node.js

Python

gcloud

Terraform

gsutil

bq

次のステップ

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

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