X.509 証明書を使用して Workload Identity 連携を構成する

このガイドでは、認証局（CA）によって発行された X.509 証明書を使用して Workload Identity 連携を実行し、Google Cloud で認証を行い Google Cloud リソースにアクセスする方法について説明します。

ワークロードが mTLS クライアント証明書を所有している場合は、1 つ以上の CA を Workload Identity 連携にトラストアンカーとして登録することで、Google Cloud に対して認証できます。中間 CA を登録することもできます。

Workload Identity 連携を使用すると、これらのワークロードは相互 TLS（mTLS）接続を介して有効期間の短い Google Cloud 認証情報を取得できます。ワークロードは、これらの有効期間が短い認証情報を使用して Google Cloud APIs にアクセスできます。

コンセプト

X.509 証明書ベースの連携のコンセプトには、次のようなものが含まれています。

トラストアンカーは、信頼のルートとして見なされる CA 証明書です。クライアント証明書チェーンは、いずれかのトラストアンカーにチェーンする必要があります。
中間 CA は、クライアント証明書チェーンの構築に役立つオプションの認証局証明書です。
トラストストアには、クライアント証明書チェーンの検証に使用されるトラストアンカー証明書と中間 CA 証明書が含まれています。CA は、クライアントに信頼できる証明書を発行します。

トラストストアには、次の種類のクライアント証明書をアップロードできます。
- 任意の第三者の CA が発行した証明書
- プライベート CA によって発行された証明書
- 署名付き証明書（自己署名証明書を作成するを参照）。

始める前に

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

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

Go to project selector

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

Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

必要なロール

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

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

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

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

Workload Identity 連携を構成する

このセクションでは、Workload Identity 連携とトラストストアを構成する方法について説明します。この手順は、トラストストアごとに 1 回だけ行います。これにより、複数のワークロードと複数の Google Cloud プロジェクトで同じ Workload Identity のプールとプロバイダを使用できます。

トラストストアを作成して構成する

このセクションでは、トラストストアの YAML 構成ファイルと自己署名 CA 証明書を作成する方法について説明します。

鍵と署名済み証明書を生成する

このセクションでは、openssl コマンドを使用してルート証明書と中間証明書を作成します。

証明書がすでにある場合は、この手順をスキップして、証明書をフォーマットするに進みます。

ルート証明書と、有効な keyUsage および extendedKeyUsage フィールドを含む署名付き中間証明書を生成するには、次の操作を行います。

有効な署名証明書を作成するために必要な最小限の構成を含むサンプルの example.cnf ファイルを作成します。このファイルを編集して、これらの証明書に追加のフィールドを設定できます。

cat > example.cnf << EOF
[req]
distinguished_name = empty_distinguished_name
[empty_distinguished_name]
# Kept empty to allow setting via -subj command line arg.
[ca_exts]
basicConstraints=critical,CA:TRUE
keyUsage=keyCertSign
extendedKeyUsage=clientAuth
EOF

ルート証明書を作成します。

openssl req -x509 \
    -new -sha256 -newkey rsa:2048 -nodes \
    -days 3650 -subj '/CN=root' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout root.key -out root.cert

中間証明書の署名リクエストを作成します。

openssl req \
    -new -sha256 -newkey rsa:2048 -nodes \
    -subj '/CN=int' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout int.key -out int.req

中間証明書を作成します。

openssl x509 -req \
    -CAkey root.key -CA root.cert \
    -set_serial 1 \
    -days 3650 \
    -extfile example.cnf \
    -extensions ca_exts \
    -in int.req -out int.cert

証明書をフォーマットする

新規または既存の証明書をトラストストアに含めるには、YAML ファイルに読み込めるように、証明書を 1 行にまとめて環境変数に格納します。証明書は PEM 形式にする必要があります。証明書をフォーマットして環境変数に格納する手順は次のとおりです。

ルート証明書を 1 行の文字列として保存します。

export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

中間証明書を 1 行の文字列として保存します。

export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

トラストストアの YAML ファイルを作成する

このセクションでは、トラストアンカーと中間 CA を含むトラストストアの YAML ファイルを作成します。

トラストストアの YAML ファイルを作成するには、次のコマンドを実行します。このファイルには、証明書をフォーマットするで作成した環境変数からの証明書の内容が含まれています。トラストアンカーを追加するには、trustStore の下に trustAnchors エントリを追加します。中間 CA 証明書を追加するには、trustStore の下に intermediateCas エントリを追加します。

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

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

クライアント X.509 証明書には複数の属性を含めることができます。Google Cloud の google.subject を証明書の属性にマッピングして、サブジェクト識別子として使用する属性を選択する必要があります。たとえば、証明書内の属性がサブジェクトの共通名である場合、マッピングは次のようになります。 google.subject=assertion.subject.dn.cn

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

属性マッピングでは、次のようなクライアント証明書内の属性を使用できます。

serialNumberHex: シリアル番号
subject.dn.cn: サブジェクトの共通名
subject.dn.o: サブジェクトの組織名
subject.dn.ou: サブジェクトの組織部門
issuer.dn.cn: 発行者のコモンネーム
issuer.dn.o: 発行元の組織名
issuer.dn.ou: 発行元の組織部門
san.dns: サブジェクト代替名の最初の DNS 名
san.uri: サブジェクト代替名の最初の URI

サブジェクトを一意に識別するには、これらの属性のいずれかを google.subject にマッピングする必要があります。なりすましの脅威から保護するため、変更できない一意の値を持つ属性を選択します。デフォルトでは、google.subject ID はクライアント証明書のサブジェクトの共通名（assertion.subject.dn.cn）に設定されます。

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

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

たとえば、次の条件は、SPIFFE ID spiffe://example/path を含むクライアント証明書へのアクセスを制限します。

assertion.san.uri=="spiffe://example/path"

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

新しい 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 へのアクセス権を付与するときに表示されます。
X.509 Workload Identity プールプロバイダを追加するには、次のコマンドを実行します。
```
gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
    --location=global \
    --workload-identity-pool="POOL_ID" \
    --trust-store-config-path="TRUST_STORE_CONFIG" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS" \
    --billing-project="ALLOWLISTED_PROJECT"
```
次のように置き換えます。
- PROVIDER_ID: 一意の Workload Identity プールプロバイダ ID。
- POOL_ID: 前に作成した Workload Identity プール ID。
- TRUST_STORE_CONFIG: トラストストアの YAML ファイル。
- MAPPINGS: このガイドの前半で作成した属性マッピングのカンマ区切りリスト。google.subject を指定しない場合、デフォルトのマッピングは google.subject=assertion.subject.dn.cn になります。
- CONDITIONS: このガイドの前半で作成した属性条件。属性条件がない場合は、パラメータを削除します。
- ALLOWLISTED_PROJECT: プロジェクト ID。

ワークロードの認証

この手順は、ワークロードごとに 1 回だけ行います。

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

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

リソースへの直接アクセス

Google Cloud コンソールまたは gcloud CLI を使用して、リソースへの直接アクセス権を連携 ID に付与できます。

コンソール

Google Cloud コンソールでリソースに IAM ロールを直接付与するには、リソースのページに移動してロールを付与する必要があります。次の例は、Cloud Storage ページに移動し、Cloud Storage バケットでフェデレーション ID にストレージオブジェクト閲覧者（roles/storage.objectViewer）ロールを直接付与する方法を示しています。

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、ロールを付与するバケットの名前をクリックします。
ページ上部にある [権限] タブを選択します。
[ アクセス権を付与] ボタンをクリックします。

[プリンシパルの追加] ダイアログが表示されます。
[新しいプリンシパル] フィールドに、バケットへのアクセスが必要な ID を 1 つ以上入力します。
サブジェクト
```
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
```
次のように置き換えます。
- PROJECT_NUMBER: プロジェクト番号
- POOL_ID: ワークロードプールの ID
- SUBJECT: IdP からマッピングされた個々のサブジェクト（例: administrator@example.com）
グループ
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
```
次のように置き換えます。
- PROJECT_NUMBER: プロジェクト番号
- WORKLOAD_POOL_ID: ワークロードプールの ID
- GROUP: IdP からマッピングされたグループ（例: administrator-group@example.com）
属性
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
```
次のように置き換えます。
- PROJECT_NUMBER: プロジェクト番号
- WORKLOAD_POOL_ID: ワークロードプールの ID
- ATTRIBUTE_NAME: IdP からマッピングされた属性のいずれか
- ATTRIBUTE_VALUE: 属性の値
[ロールを選択] プルダウンメニューからロールを選択します。選択したロールと付与する権限の簡単な説明がパネルに表示されます。
[保存] をクリックします。

gcloud

gcloud CLI を使用してプロジェクトのリソースに IAM ロールを付与するには、次の操作を行います。

リソースが定義されているプロジェクトのプロジェクト番号を取得します。
```
gcloud projects describe $(gcloud config get-value core/project) --format=value$projectNumber$
```
リソースへのアクセス権を付与します。

gcloud CLI を使用して、特定の条件を満たす外部 ID に Storage オブジェクト閲覧者ロール（roles/storage.objectViewer）を付与するには、次のコマンドを実行します。
サブジェクト
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
```
グループ
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
```
属性
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
```
次のように置き換えます。
- BUCKET_ID: アクセス権を付与するバケット
- PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
- POOL_ID: Workload Identity プールのプール ID
- SUBJECT: google.subject にマッピングされている属性の想定値
- GROUP: google.groups にマッピングされている属性の想定値
- ATTRIBUTE_NAME: 属性マッピングのカスタム属性の名前
- ATTRIBUTE_VALUE: 属性マッピングのカスタム属性の値
IAM 許可ポリシーをサポートする任意の Google Cloud リソースにロールを付与できます。

注: メンバー ID には、プロジェクト ID ではなくプロジェクト番号を使用する必要があります。

サービスアカウントの権限借用

外部ワークロードのサービスアカウントを作成するには、次の操作を行います。
1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
  Enable the APIs
2. ワークロードを表すサービスアカウントを作成します。ワークロードごとに専用のサービスアカウントを使用することをおすすめします。サービスアカウントは、Workload Identity プールと同じプロジェクトにある必要はありませんが、サービスアカウントを含むプロジェクトを参照する必要があります。
3. 外部 ID にアクセスを許可するリソースに対するアクセス権をサービスアカウントに付与します。
4. サービスアカウントに Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）を付与します。
Google Cloud コンソールまたは gcloud CLI を使用してサービスアカウントの権限借用でフェデレーション ID へのアクセス権を付与するには、次の操作を行います。

コンソール

Google Cloud コンソールで、サービスアカウントを使用してフェデレーション ID に IAM ロールを付与する手順は次のとおりです。

同じプロジェクトのサービスアカウント

同じプロジェクトのサービスアカウントに対してサービスアカウントの権限借用を使用してアクセス権を付与する手順は次のとおりです。
1. [Workload Identity プール] ページに移動します。
  
  [Workload Identity プール] に移動
2. [アクセス権を付与] を選択します。
3. [サービスアカウントにアクセス権を付与する] ダイアログで、[Grant access using Service Account impersonation] を選択します。
4. [サービスアカウント] リストで、権限を借用する外部 ID のサービスアカウントを選択して、次の操作を行います。
5. プール内のどの ID がサービスアカウントの権限を借用できるかを選択するには、次のいずれかを行います。
  - Workload Identity プールの特定の ID のみにサービスアカウントの権限借用を許可するには、[フィルタに一致する ID のみ] を選択します。
  - [属性名] リストで、フィルタリングする属性を選択します。
  - [属性値] フィールドに、属性の想定値を入力します。たとえば、属性マッピング google.subject=assertion.sub を使用する場合は、属性名を subject に設定します。属性値には、外部 ID プロバイダによって発行されたトークンの sub クレームの値を設定します。
6. 構成を保存するには、[保存]、[閉じる] の順にクリックします。

別のプロジェクトのサービスアカウント

別のプロジェクトのサービスアカウントに対してサービスアカウントの権限借用を使用してアクセス権を付与する手順は次のとおりです。
1. [サービスアカウント] ページに移動します。
  
  [サービスアカウント] に移動
2. 権限を借用するサービスアカウントを選択します。
3. [アクセスを管理] をクリックします。
4. [プリンシパルを追加] をクリックします。
5. [新しいプリンシパル] フィールドに、プール内でサービスアカウントの権限を借用する ID の次のプリンシパル ID のいずれかを入力します。
  サブジェクト
  principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
  次のように置き換えます。
  - PROJECT_NUMBER: プロジェクト番号
  - POOL_ID: ワークロードプールの ID
  - SUBJECT: IdP からマッピングされた個々のサブジェクト（例: administrator@example.com）
  グループ
  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
  次のように置き換えます。
  - PROJECT_NUMBER: プロジェクト番号
  - WORKLOAD_POOL_ID: ワークロードプールの ID
  - GROUP: IdP からマッピングされたグループ（例: administrator-group@example.com）
  属性
  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
  次のように置き換えます。
  - PROJECT_NUMBER: プロジェクト番号
  - WORKLOAD_POOL_ID: ワークロードプールの ID
  - ATTRIBUTE_NAME: IdP からマッピングされた属性のいずれか
  - ATTRIBUTE_VALUE: 属性の値
  プール別
  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
  次のように置き換えます。
  - PROJECT_NUMBER: プロジェクト番号
  - WORKLOAD_POOL_ID: ワークロードプールの ID
6. [ロールを選択] で、Workload Identity ユーザーのロール（roles/iam.workloadIdentityUser）を指定します。
7. 構成を保存するには、[保存] をクリックします。

gcloud

gcloud CLI を使用して、特定の条件を満たす外部 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: 属性マッピングのカスタム属性の名前
ATTRIBUTE_VALUE: 属性マッピングのカスタム属性の値

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

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

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

また、X.509 証明書の連携には、証明書の構成ファイルが必要です。このファイルには、X.509 クライアント証明書と秘密鍵ファイルへのパスが含まれています。

認証情報と証明書の構成ファイルを作成する手順は次のとおりです。

リソースへの直接アクセス

gcloud iam workload-identity-pools create-cred-config を使用してリソースへの直接アクセス用の認証情報と証明書の構成ファイルを作成するには、次の操作を行います。

X.509 証明書を使用してアクセストークンを取得できるように、認証情報と証明書の構成ファイルを作成します。

gcloud iam workload-identity-pools create-cred-config
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

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

PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号。
POOL_ID: Workload Identity プールの ID。
PROVIDER_ID: Workload Identity プールプロバイダの ID。
CLIENT_CERT_PATH: クライアント証明書ファイルのパス。
CLIENT_KEY_PATH: クライアント証明書の秘密鍵ファイルのパス。
FILEPATH: 構成を保存するファイル。

このコマンドを実行すると、証明書構成ファイルも作成され、デフォルトの Google Cloud CLI の場所に保存されます。

Linux / macOS: ~/.config/gcloud/certificate_config.json
Windows: %APPDATA%\gcloud\certificate_config.json

サービスアカウントの権限借用

gcloud iam workload-identity-pools create-cred-config を使用してサービスアカウントの権限借用で認証情報と証明書の構成ファイルを作成するには、次の操作を行います。

X.509 証明書を使用してアクセストークンを取得できるように、認証情報と証明書の構成ファイルを作成します。

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 \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --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 組織ポリシー制約を構成する必要があります。
CLIENT_CERT_PATH: クライアント証明書ファイルのパス。
CLIENT_KEY_PATH: クライアント証明書の秘密鍵ファイルのパス。
FILEPATH: 構成を保存するファイル。

このコマンドを実行すると、証明書構成ファイルも作成され、デフォルトの Google Cloud CLI の場所に保存されます。

Linux / macOS: ~/.config/gcloud/certificate_config.json
Windows: %APPDATA%\gcloud\certificate_config.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 は、認証情報の構成ファイルの相対パスです。
クライアントライブラリが証明書構成ファイルを検出できるようにします。証明書構成ファイルは、デフォルトの Google Cloud CLI の場所に保存されています。
- Linux / macOS: ~/.config/gcloud/certificate_config.json
- Windows: %APPDATA%\gcloud\certificate_config.json
あるいは、GOOGLE_API_CERTIFICATE_CONFIG 環境変数によって指定されます。
Workload Identity 連携をサポートし、認証情報を自動的に検索できるクライアントライブラリまたはツールを使用します。

Go

Go 用クライアントライブラリは、cloud.google.com/go/auth モジュールのバージョン 0.8.0 以降と google.golang.org/api モジュールのバージョン 0.189.0 を使用している場合に X.509 Workload Identity 連携をサポートします。

クライアントライブラリで使用されているこれらのモジュールのバージョンを確認するには、モジュールの go.mod ファイルを含むディレクトリで次のコマンドを実行します。

  go list -m cloud.google.com/go/auth
  go list -m cloud.google.com/api

Python

Python 用クライアントライブラリは、google-auth パッケージのバージョン 2.32.0 以降を使用している場合に X.509 Workload Identity 連携をサポートします。

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

  pip show google-auth

認証クライアントのプロジェクト ID を指定するには、GOOGLE_CLOUD_PROJECT 環境変数を設定するか、クライアントがプロジェクト ID を自動的に検出するようにします。プロジェクト ID を自動的に検出するには、構成ファイルのサービスアカウントに、プロジェクト上でブラウザのロール（roles/browser）または同等の権限を持つロールが付与されている必要があります。詳細については、google-auth パッケージのユーザーガイドをご覧ください。

gcloud

X.509 Workload Identity 連携を使用して認証するには、gcloud auth login コマンドを使用します。

  gcloud auth login --cred-file=FILEPATH.json

FILEPATH は、認証情報の構成ファイルのパスに置き換えます。

gcloud CLI での X.509 Workload Identity 連携は、gcloud CLI のバージョン 488.0.0 以降でサポートされています。

Google Cloud にアクセスするためのプレーンリクエストを使用してアクセストークンを取得する

アクセストークンを取得する手順は次のとおりです。

curl を使用して、mTLS とクライアント証明書でトークン交換を行います。

curl --key CLIENT_CERT_KEY \
--cert CLIENT_CERT \
--request POST 'https://sts.mtls.googleapis.com/v1/token' \
--header "Content-Type: application/json" \
--data-raw '{
    "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "audience": "WORKLOAD_IDENTITY_POOL_URI",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "https://www.googleapis.com/auth/cloud-platform",
}'

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

CLIENT_CERT_KEY: クライアント証明書の秘密鍵
CLIENT_CERT: クライアント証明書
WORKLOAD_IDENTITY_POOL_URI: Workload Identity プールプロバイダの URL（次の形式）:

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

前の手順で生成した Bearer アクセストークンを使用して、Google Cloud リソースにアクセスします。
```
curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
```

割り当てと上限

次の表に、割り当てと上限を示します。

項目	割り当てと上限	注
トラストアンカーの数	上限: 3	各証明書は 32 KB を超えてはなりません。
中間証明書の数	上限: 10	各証明書は 32 KB を超えてはなりません。
ルート証明書と中間証明書の検証中に許可される名前の制約の数	上限: 10
サブジェクトとサブジェクトの公開鍵情報を共有する中間証明書	上限: 5	この上限はトラストストアごとに適用されます。
証明書チェーンの深さ	上限: 5	ルート証明書とクライアント証明書を含む証明書チェーンの最大深度。
信頼チェーンを構築する際に中間証明書を評価できる回数	上限: 100
クライアントからアップロードされ、渡される証明書の鍵	上限: RSA 鍵の長さは 2,048～4,096 ビットにできます。 ECDSA 証明書には、P-256 または P-384 の楕円曲線暗号を使用する必要があります。	通常のユースケースには RSA-2048 と P-256 をおすすめします。セキュリティのベストプラクティスを実践する場合は他のアルゴリズムを使用します。

次のステップ

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

X.509 証明書を使用して Workload Identity 連携を構成する

コンセプト

始める前に

必要なロール

Workload Identity 連携を構成する

トラストストアを作成して構成する

鍵と署名済み証明書を生成する

証明書をフォーマットする

トラストストアの YAML ファイルを作成する

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

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

ワークロードの認証

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

リソースへの直接アクセス

コンソール

サブジェクト

グループ

属性

gcloud

サブジェクト

グループ

属性

サービス アカウントの権限借用

コンソール

同じプロジェクトのサービス アカウント

別のプロジェクトのサービス アカウント

サブジェクト

グループ

属性

プール別

gcloud

サブジェクト

グループ

属性

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

リソースへの直接アクセス

サービス アカウントの権限借用

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

Bash

PowerShell

Go

Python

gcloud

Google Cloud にアクセスするためのプレーン リクエストを使用してアクセス トークンを取得する

割り当てと上限

次のステップ

サービスアカウントの権限借用

同じプロジェクトのサービスアカウント

別のプロジェクトのサービスアカウント

サービスアカウントの権限借用

Google Cloud にアクセスするためのプレーンリクエストを使用してアクセストークンを取得する