OIDC ID プロバイダからリソースにアクセスする

このドキュメントでは、ID 連携を使用して OpenID Connect（OIDC）をサポートする ID プロバイダから Google Cloud リソースにアクセスする方法について説明します。

従来、Google Cloud の外部で実行されているアプリケーションは、サービスアカウントキーを使用して Google Cloud リソースにアクセスしていました。ID 連携を使用すると、外部 ID でサービスアカウントになり代わることができます。これにより、ワークロードは短期間だけ有効なアクセストークンを使用して Google Cloud リソースに直接アクセスでき、サービスアカウントキーに関連するメンテナンスとセキュリティの負担が軽減されます。

始める前に

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 連携を構成する権限も含まれています。本番環境で基本ロールを付与することはできませんが、開発環境またはテスト環境ではこれらのロールを付与できます。
組織が ID プロバイダからの連携を許可するには、組織ポリシーを更新します。
Google Cloud サービスアカウントを作成します。
サービスアカウントにアクセス権を付与して、ワークロードに必要な Google Cloud APIs を呼び出します。

OIDC の ID プロバイダ設定

OIDC ID プロバイダを Workload Identity プールに追加するときは、次の情報を指定する必要があります。

プロバイダの ID。
プロバイダの発行者 URI。通常は、https://example.com の形式を使用します。URI の確認については、OIDC 統合に関するプロバイダのドキュメントをご覧ください。
外部トークンのクレームを Google トークンの属性にマッピングする属性マッピングのリスト。assertion を使用して外部認証情報を参照します。Google 属性の場合は google、カスタム属性の場合は attribute を使用します。

Google 属性には google.subject と google.groups の 2 つがあります。これらの属性は IAM ロールバインディングで参照できます。google.subject も Cloud Logging のログエントリに表示されます。

google.subject のマッピングを指定する必要があります。通常は、assertion.sub にマッピングすることをおすすめします。これにより、IAM ロールバインディングで使用する固定 ID が提供されます。マッピングは次のようになります。
```
google.subject=assertion.sub
```
より複雑なアサーションの場合は、Common Expression Language を使用できます。たとえば、Workload Identity プールに複数の ID プロバイダが含まれている場合は、それらの ID を明確化するために接頭辞を追加できます。
```
google.subject="provider-a::" + assertion.sub
```
google.subject フィールドは 127 文字以下で指定してください。

カスタム属性を指定することもできます。たとえば、以下では assertion.foo を attribute.bar にマッピングします。
```
attribute.bar=assertion.foo
```
参照できるクレームの完全なリストについては、アクセストークンに関するプロバイダのドキュメントをご覧ください。

式で使用されているクレームの特定の部分を参照するには、CEL の extract() 関数を使用します。この関数は、指定したテンプレートに基づいてクレームから値を抽出します。extract() の詳細については、リソース名からの値の抽出をご覧ください。

認証情報にクレームが含まれているかどうかを確認するには、has() 関数を使用します。
外部認証情報の aud フィールドに設定できる値を指定する許可されたオーディエンスのリスト。最大 10 個のオーディエンス（それぞれ最大 256 文字）を構成できます。aud のデフォルト値については、プロバイダのドキュメントをご覧ください。

または、ID プロバイダで aud のカスタム値を構成できる場合は、許可オーディエンスパラメータを空白のままにし、aud の値を Workload Identity プロバイダの完全なリソース名に設定できます。HTTP 接頭辞は省略可能です。例:
```
//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
どちらの場合も、許可された値を含まないトークン交換リクエストは拒否されます。

次の複数のオプションパラメータを指定することもできます。

表示名と説明。
プリンシパルが提示する必要がある属性を指定する属性条件。この条件は、外部認証情報に対するクレーム、または Google 認証情報の属性に適用できます。条件を満たしていないリクエストは拒否されます。

属性条件は、ブール値を返す CEL 式の形式になります。たとえば以下では、特定のグループのメンバーではない ID からのリクエストは拒否されます。
```
GROUP in assertion.groups
```
ID プロバイダが一般に公開されている場合は、属性条件を使用することを強くおすすめします。一般的なユースケースの詳細については、属性条件をご覧ください。

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

外部 ID を編成して管理するには、Workload Identity プールを使用します。Workload Identity プールは相互に分離されていますが、1 つのプールは任意の数のサービスアカウントになり代わることができます。一般に、開発、ステージング、本番環境など、環境ごとに新しいプールを作成することをおすすめします。

新しい Workload Identity プールを作成するには、ID を指定する必要があります。オプションの説明と表示名を指定することもできます。ID の先頭に gcp- は使用できません。この接頭辞は Google で使用するために予約されています。

Workload Identity プールを作成したら、Workload Identity プールプロバイダを追加できます。各 Workload Identity プールプロバイダは、特定の ID プロバイダを表します。1 つのプールには複数のプロバイダを含めることができます。プロバイダを作成するには、OIDC の ID プロバイダ設定のページに記載されている情報が必要です。

Console

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

[新しいワークロードプロバイダとプール] に移動
Workload Identity プールの名前を入力します。

この名前は、プール ID の作成に使用されます。プール ID を変更するには、[編集] をクリックします。後からプール ID を変更することはできません。
（省略可）Workload Identity プールの説明を入力します。
[続行] をクリックします。
[プロバイダの選択] プルダウンリストで [OpenID Connect（OIDC）] を選択し、[続行] をクリックします。
プロバイダ名を入力します。

この名前は、プロバイダ ID の作成に使用されます。プロバイダ ID を変更するには、[編集] をクリックします。後からプロバイダ ID を変更することはできません。
プロバイダの [発行元（URL）] を入力し、[続行] をクリックします。
属性のマッピングを構成するには、[マッピングを編集] をクリックします。

属性のマッピングでは、外部 ID に関する情報を使用して、それらの ID のサブセットへのアクセス権を付与できます。OIDC ID プロバイダの場合は、google.subject を assertion.sub にマッピングすることをおすすめします。その他のマッピングは省略可能です。

詳細については、このページの OIDC の ID プロバイダ設定をご覧ください。
（省略可）認証できる ID を指定する属性条件を指定するには、[条件を追加] をクリックし、有効な CEL（Common Expression Language）を入力します。詳細については、属性の条件をご覧ください。
[保存] をクリックして、Workload Identity のプールとプロバイダを作成します。

gcloud

Workload Identity プールを作成するには、gcloud iam workload-identity-pools create コマンドを使用します。

gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"

レスポンスは次のようになります。

Created workload identity pool [POOL_ID].

Workload Identity プールプロバイダを追加するには、gcloud iam workload-identity-pools providers create-oidc コマンドを使用します。

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER_URI" \
    --location="global" \
    --attribute-mapping="google.subject=assertion.sub"

レスポンスは次のようになります。

Created workload identity pool provider [PROVIDER_ID].

REST

Workload Identity プールを作成するには、次の操作を行います。

projects.locations.workloadIdentityPools.create メソッドにより、Workload Identity プールが作成されます。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

JSON 本文のリクエスト:

{
  "description": "description",
  "display-name": "display-name"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id" | Select-Object -Expand Content

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

このメソッドは、次のような長時間実行 Operation を返します。

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/operations/operation-id"
}

Workload Identity プールのプロバイダを追加するには、次のようにします。

projects.locations.workloadIdentityPools.providers.create メソッドにより、OIDC ID プロバイダが追加されます。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

JSON 本文のリクエスト:

{
  "issuerUrl": "issuer-uri"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id" | Select-Object -Expand Content

API Explorer（ブラウザ）

このメソッドは、次のような長時間実行 Operation を返します。

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id/operations/operation-id"
}

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

外部 ID は、ほとんどの Google Cloud リソースに直接アクセスできません。代わりに、サービスアカウントの Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を外部 ID に付与することで、サービスアカウントの権限を借用できます。外部 ID がサービスアカウントの権限を借用すると、サービスアカウントと同じロールと権限を持ちます。

Workload Identity ユーザーロールを外部 ID に付与するには、次のようにします。

Console

Workload Identity ユーザーロールを付与する前に、サービスアカウントの権限借用を許可する ID を決定します。ロールは、Workload Identity プール内のすべての ID に付与するか、属性のマッピングに基づいてこれらの ID のサブセットに付与できます。

ID	属性名	属性の値
単一の ID	`subject`	`SUBJECT_NAME`
特定の属性値を持つすべての ID	`ATTRIBUTE_NAME`	`ATTRIBUTE_VALUE`

次に、サービスアカウントへのアクセスを許可します。必要に応じて、認証情報を自動的に生成するための構成ファイルをダウンロードします。

Cloud Console で、[Workload Identity プール] ページに移動します。

[Workload Identity プール] に移動
外部 ID を含む Workload Identity プールを見つけて、その [ 編集] アイコンをクリックします。Cloud Console に Workload Identity プールの詳細が表示されます。
[ アクセスを許可] をクリックします。
[サービスアカウント] プルダウンリストで、外部 ID が権限借用するサービスアカウントを選択します。
プール内でサービスアカウントの権限を借用する ID を選択します。

すべての ID にサービスアカウントの権限借用を許可するには、[プール内のすべての ID] を選択します。

一部の ID にサービスアカウントの権限借用を許可するには、[フィルタに一致する ID のみ] を選択して、次のようにします。
1. [Attribute name] プルダウンリストで、評価する属性を選択します。
  
  マッピングされた属性のみがリストに表示されます。google. と attribute. の接頭辞は表示されません。
2. [属性値] フィールドに、属性の想定値を入力します。
[保存] をクリックします。

ID がすでにサービスアカウントへのアクセス権を持っている場合は、Cloud Console に Workload Identity プールの詳細が表示されます。その場合、残りの手順はスキップしてください。

ID がサービスアカウントにアクセスできるようになると、Cloud Console に [アプリケーションの構成] ダイアログが表示されます。
（省略可）認証情報を自動的に生成するための構成ファイルをダウンロードするには、次のようにします。
1. [プロバイダ] プルダウンリストで、サービスアカウントの権限を借用する外部 ID を含むプロバイダを選択します。
2. [ 構成をダウンロード] をクリックして JSON 構成ファイルをダウンロードします。
[閉じる] をクリックします。

gcloud

ID	メンバー形式
単一の ID	`principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_NAME`
特定の属性値を持つすべての ID	`principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE`
プール内のすべての ID	`principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*`

次に、gcloud iam service-accounts add-iam-policy-binding コマンドを実行します。

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="MEMBER"

次の値を置き換えます。

SERVICE_ACCOUNT_EMAIL: サービスアカウントのメールアドレス。
MEMBER: サービスアカウントの権限を借用する外部 ID。

REST

ID	メンバー形式
単一の ID	`principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_NAME`
特定の属性値を持つすべての ID	`principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE`
プール内のすべての ID	`principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*`

次に、読み取り / 変更 / 書き込みのパターンでポリシーを更新します。

サービスアカウントの現在の IAM ポリシーを読み取ります。
ポリシーを変更してロールを付与します。
更新したポリシーを書き込みます。

サービスアカウントの IAM ポリシーを読み取ります。

serviceAccounts.getIamPolicy メソッドで、サービスアカウントの IAM ポリシーを取得します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクト IDプロジェクト ID は英数字からなる文字列です（例: my-project）。
SA_ID: サービスアカウントの ID。これは、サービスアカウントのメールアドレス（SA_NAME@PROJECT_ID.iam.gserviceaccount.com の形式）、またはサービスアカウントの一意の数値 ID のいずれかです。
注: サービスアカウントの作成後にサービスを識別するには、メールアドレスではなく数値 ID を使用します。
POLICY_VERSION: 返されるポリシーバージョン。リクエストでは、最新のポリシーバージョン（ポリシーバージョン 3）を指定する必要があります。詳細については、ポリシーの取得時にポリシーバージョンを指定するをご覧ください。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy

JSON 本文のリクエスト:

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy" | Select-Object -Expand Content

API Explorer（ブラウザ）

次のような JSON レスポンスが返されます。

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

既存のポリシーがない場合、レスポンスにはデフォルトの etag のみが含まれます。このレスポンスが返された場合は、version フィールドを追加して 3 に設定し、bindings フィールドを空の配列に設定します。

適切なロールがメンバーに付与されるようにポリシーを変更します。

ロールを付与するには、レスポンス本文の bindings 配列を変更します。

ロールのバインディングが存在しない場合は、付与するロールとメンバーを定義する bindings 配列に新しいオブジェクトを追加します。
ロールのバインディングがすでに存在する場合は、既存のメンバーのリストに新しいメンバーを追加します。

例:

Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）をプール内のすべての ID に付与するには、前の手順で示した例を次のように変更します。

{
  "version": 1,
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.workloadIdentityUser",
      "members": [
        "principalSet://iam.googleapis.com/projects/1234567890123/locations/global/workloadIdentityPools/my-pool/*"
      ]
    },
    {
      "role": "roles/iam.serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

更新したポリシーを書き込みます。

serviceAccounts.setIamPolicy メソッドによって、サービスアカウントの更新済み IAM ポリシーが設定されます。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクト IDプロジェクト ID は英数字からなる文字列です（例: my-project）。
SA_ID: サービスアカウントの ID。これは、サービスアカウントのメールアドレス（SA_NAME@PROJECT_ID.iam.gserviceaccount.com の形式）、またはサービスアカウントの一意の数値 ID のいずれかです。
注: サービスアカウントの作成後にサービスを識別するには、メールアドレスではなく数値 ID を使用します。

POLICY: 設定するポリシーの JSON 表現。ポリシーの形式については、ポリシーリファレンスをご覧ください。

たとえば、前の手順で示したポリシーを設定するには、policy を次のコードに置き換えます。

{
  "version": 1,
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.workloadIdentityUser",
      "members": [
        "principalSet://iam.googleapis.com/projects/1234567890123/locations/global/workloadIdentityPools/my-pool/*"
      ]
    },
    {
      "role": "roles/iam.serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy

JSON 本文のリクエスト:

{
  "policy": POLICY
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy" | Select-Object -Expand Content

API Explorer（ブラウザ）

レスポンスには、更新されたポリシーが含まれます。

Google 認証情報を生成する

サポートされているクライアントライブラリを使用する場合は、Google 認証情報が自動的に生成されるようにクライアントライブラリを構成できます。または、OIDC ID トークンを手動で生成し、Google 認証情報と交換することもできます。

可能であれば、トークン交換プロセスを自身で実装しなくても済むように、認証情報を自動的に生成することをおすすめします。

認証情報を自動生成する

次のいずれかの言語のクライアントライブラリを使用して Google Cloud にアクセスする場合は、ID 連携を使用して認証情報を自動的に生成するようにクライアントライブラリを構成できます。

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

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

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 パッケージのユーザーガイドをご覧ください。

クライアントライブラリが自動的に認証情報を生成するように構成するには、JSON 構成ファイルを作成します。このファイルは、Cloud Console または gcloud ツールで作成できます。

この構成ファイルでは、クライアントライブラリで ID プロバイダからトークンを取得する方法を指定します。クライアントライブラリでトークンを取得する方法は複数あります。

ファイルソースの認証情報: トークンはファイルから読み込まれます。古いトークンが期限切れになる前に、別のプロセスでこのファイルを新しい OIDC トークンで更新する必要があります。たとえば、トークンの有効期間が 1 時間の場合、1 時間経過する前にファイルを更新する必要があります。
URL 提供の認証情報: トークンは、HTTP GET リクエストに応答するエンドポイントを持つローカルサーバーから読み込まれます。レスポンスは、書式なしテキストまたは JSON 形式の OIDC ID トークンでなければなりません。

Console

まず、このページの手順に沿って、外部 ID にサービスアカウントの権限借用を許可します。次に、外部 ID が権限を借用するサービスアカウントに対する JSON 構成ファイルを作成します。

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

Cloud Console で、[Workload Identity プール] ページに移動します。

[Workload Identity プール] に移動
使用する ID プロバイダを含む Workload Identity プールを見つけて、[ 編集] アイコンをクリックします。Cloud Console に Workload Identity プールの詳細が表示されます。
[接続済みサービスアカウント] をクリックします。
使用するサービスアカウントを見つけて、[ ダウンロード] をクリックします。
[プロバイダ] プルダウンリストで、サービスアカウントの権限を借用する OIDC ID を含むプロバイダを選択します。
[OIDC ID トークンのパス] ボックスに、次のいずれかを入力します。
- ファイルソースの認証情報: OIDC ID トークンが保存されるファイルパス。
- URL ソースの認証情報: HTTP GET リクエストに対する OIDC ID トークンを提供する URL。
[Format type] プルダウンリストで、テキスト形式の場合は [txt]、JSON 形式の場合は [json] を選択します。

[json] を選択した場合は、[サブジェクトトークンのフィールド名] ボックスの値がトークンを含む JSON フィールド名と一致していることを確認します。必要に応じて値を更新します。
[ 構成をダウンロード] をクリックして JSON 構成ファイルをダウンロードし、[完了] をクリックします。

URL ソースの認証情報を使用していて、リクエストに特定の HTTP ヘッダーを含める場合は、これらのヘッダーを構成ファイルに追加できます。

テキストエディタで構成ファイルを開き、headers フィールドを探します。次のようになります。
```
"headers": {},
```
Key-Value ペアとして HTTP ヘッダーを headers オブジェクトに追加します。各キーと値は二重引用符で囲む必要があります。

たとえば、値が test の X-Example-One ヘッダー、値が example の X-Example-Two ヘッダーを送信するには、次のように追加します。
```
"headers": {
  "X-Example-One": "test",
  "X-Example-Two": "example"
},
```
変更を構成ファイルに保存します。

gcloud

ファイルソースの認証情報を使用するには、gcloud iam workload-identity-pools create-cred-config コマンドを実行して構成ファイルを生成します。--credential-source-type フラグは省略可能です。--credential-source-type が json でない限り、--credential-source-field-name フラグは省略可能です。

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --output-file=CONFIGURATION_FILEPATH \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

次の値を置き換えます。

PROJECT_NUMBER: プロジェクトの数値 ID。
POOL ID: Workload Identity プールの ID。
PROVIDER_ID: Workload Identity プールプロバイダの ID。
SERVICE_ACCOUNT_EMAIL: なり代わるサービスアカウントのメールアドレス。
CONFIGURATION_FILEPATH: 構成ファイルのファイルパス。
TOKEN_FILEPATH: OIDC ID トークンが保存されるファイルパス。
SOURCE_TYPE: OIDC ID トークンファイルの形式。text または json に設定します。デフォルトは text です。
FIELD_NAME: JSON トークンファイルの場合、トークンを含む JSON フィールド名。--credential-source-type が json の場合は必須です。

URL ソースの認証情報を使用するには、gcloud iam workload-identity-pools create-cred-config コマンドを実行して構成ファイルを生成します。--credential-source-headers フラグと --credential-source-type フラグは省略可能です。--credential-source-type が json でない限り、--credential-source-field-name フラグは省略可能です。

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --output-file=CONFIGURATION_FILEPATH \
    --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: プロジェクトの数値 ID。
POOL_ID: Workload Identity プールの ID。
PROVIDER_ID: Workload Identity プールプロバイダの ID。
SERVICE_ACCOUNT_EMAIL: なり代わるサービスアカウントのメールアドレス。
CONFIGURATION_FILEPATH: 構成ファイルのファイルパス。
TOKEN_URL: HTTP GET リクエストに対する OIDC ID トークンを提供する URL。
KEY_1、KEY_2: リクエストに含める HTTP ヘッダーの名前。
VALUE_1、VALUE_2: リクエストに含める HTTP ヘッダーの値。
SOURCE_TYPE: OIDC トークンファイルの形式。text または json に設定します。デフォルトは text です。
FIELD_NAME: JSON トークンファイルの場合、トークンを含むフィールド名。--credential-source-type が json の場合は必須です。

構成ファイルを生成したら、環境変数 GOOGLE_APPLICATION_CREDENTIALS を構成ファイルのファイルパスに設定します。この環境変数は、クライアントライブラリに対し、アプリケーションのデフォルト認証情報を使用して認証するように指示します。詳細については、認証情報の自動検出をご覧ください。

認証情報を手動で交換する

外部 ID が、サービスアカウントに成り代わることができると、認証情報を Google 認証情報と手動で交換できます。

認証情報を交換するには:

ID プロバイダから OIDC ID トークンを取得します（詳しい手順については、ID プロバイダのドキュメントをご覧ください）。
OIDC ID トークンをセキュリティトークンサービスの token() メソッドに渡して、連携アクセストークンを取得します。
REST

token メソッドにより、サードパーティトークンが Google トークンに交換されます。

リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_NUMBER: Google Cloud プロジェクト番号。
- POOL_ID: 作成した Workload Identity プールの ID。
- PROVIDER_ID: 構成した ID プロバイダの ID。
- ACCESS_TOKEN: ID プロバイダから取得したトークン。
HTTP メソッドと URL:
```
POST https://sts.googleapis.com/v1/token
```
JSON 本文のリクエスト:
```
{
  "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": "urn:ietf:params:oauth:token-type:jwt",
  "subjectToken": "ACCESS_TOKEN"
}
```
リクエストを送信するには、次のいずれかのオプションを展開します。
curl（Linux、macOS、または Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sts.googleapis.com/v1/token"
PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
$headers = @{ }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://sts.googleapis.com/v1/token" | Select-Object -Expand Content
API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。
このメソッドは連携トークンを返します。
generateAccessToken() を呼び出して、サービスアカウントのアクセストークンと連携トークンを交換します。連携トークンは一部の Google Cloud APIs でサポートされています。すべての Google Cloud APIs はサービスアカウントのアクセストークンをサポートしています。
REST

Service Account Credentials API の serviceAccounts.generateAccessToken メソッドによって、サービスアカウントの OAuth 2.0 アクセストークンが生成されます。

リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: Google Cloud プロジェクト IDプロジェクト ID は英数字からなる文字列です（例: my-project）。
- SA_ID: サービスアカウントの ID。これは、サービスアカウントのメールアドレス（SA_NAME@PROJECT_ID.iam.gserviceaccount.com の形式）、またはサービスアカウントの一意の数値 ID のいずれかです。
- token: 連携アクセストークン。
HTTP メソッドと URL:
```
POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken
```
JSON 本文のリクエスト:
```
{
  "scope": [
    "https://www.googleapis.com/auth/cloud-platform"
  ]
}
```
リクエストを送信するには、次のいずれかのオプションを展開します。
curl（Linux、macOS、または Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
curl -X POST \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken"
PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
$headers = @{ "Authorization" = "Bearer token" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken" | Select-Object -Expand Content
API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

generateAccessToken リクエストが成功した場合、レスポンスの本文には OAuth 2.0 アクセストークンと有効期限が含まれます。expireTime に達するまで、サービスアカウントの代わりに accessToken をリクエストの認証に使用できます。
```
{
  "accessToken": "eyJ0eXAi...NiJ9",
  "expireTime": "2020-04-07T15:01:23.045123456Z"
}
```

サービスアカウントのアクセストークンを取得したら、リクエストの Authorization ヘッダーにトークンを含めることで、Google Cloud APIs の呼び出しに使用できます。

Authorization: Bearer SERVICE_ACCOUNT_ACCESS_TOKEN

リクエストはサービスアカウントとして承認されます。

次のステップ

ID 連携を使用して AWS からリソースにアクセスするか、Microsoft Azure からリソースにアクセスする。
既存の Workload Identity プールとプロバイダを管理する方法を確認する。
Workload Identity 連携について学習する。

OIDC ID プロバイダからリソースにアクセスする

始める前に

OIDC の ID プロバイダ設定

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

Console

gcloud

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

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

Console

gcloud

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

Google 認証情報を生成する

認証情報を自動生成する

C++

Go

Java

Node.js

Python

Console

gcloud

認証情報を手動で交換する

REST

curl（Linux、macOS、または Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

REST

curl（Linux、macOS、または Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

次のステップ

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