Workforce Identity 連携の有効期間が短いトークンを取得する

このガイドでは、Workforce Identity プールと Workforce Identity プールプロバイダを使用して、セキュリティトークンサービスから有効期間が短いトークンを取得する方法について説明します。トークンを使用して、Workforce Identity 連携をサポートし、アクセス権が付与されている Google Cloud リソースにアクセスできます。

有効期間の短いトークンを取得する手順は次のとおりです。

信頼できる ID プロバイダから認証情報を取得します。
Security Token Service から取得したトークンと認証情報を交換します。

始める前に

Workforce Identity 連携を構成する。IdP 固有の手順については、次のガイドをご覧ください。
- Microsoft Entra ID ベースの Workforce Identity 連携を構成する
- Okta ベースの Workforce Identity 連携を構成する
Workforce プール ID またはプロバイダ ID を把握している必要があります。
Identity and Access Management（IAM）権限 serviceusage.services.use があることを確認します。この権限を含む最小権限のロールは Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）です。
Enable the IAM and Security Token Service APIs.
Enable the APIs
Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

Google Cloud アクセストークンの外部認証情報を交換する

このセクションでは、セキュリティトークンサービスを使用して、Google Cloud へのアクセス権を付与するアクセストークンの外部認証情報を交換する方法について説明します。この操作は、このガイドの後半で説明するように、gcloud CLI、REST API、Cloud クライアントライブラリを使用して行います。

長期間アクセスする必要がある場合は、そのマシンの認証情報を継続的に更新するように長時間プロセスを構成できます。また、認証情報を返すエンドポイントを使用して、ローカルサーバーをバックグラウンドで実行することもできます。

このセクションでは、ブラウザベースのログインフローを使用するように gcloud CLI を構成する方法について説明します。これを行うには、ログイン構成ファイルを作成してから、gcloud auth login の呼び出しでファイルを参照します。あるいは、デフォルトで使用されるように、このファイルを有効にします。

ログイン構成ファイルを作成するには、次のコマンドを実行します。必要に応じて、--activate フラグを使用することで、このファイルを gcloud CLI のデフォルトとして有効にできます。

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

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

WORKFORCE_POOL_ID: Workforce プール ID
PROVIDER_ID: プロバイダ ID
LOGIN_CONFIG_FILE: 指定した構成ファイルのパス（例: login.json）

このファイルには、gcloud CLI でブラウザベースの認証フローを有効にし、このガイドの前半で作成したプロバイダにオーディエンスを設定するために使用するエンドポイントが含まれています。ファイルに機密情報は含まれていません。

出力は次のようになります。

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

ブラウザベースのログイン認証を使用して認証するには、次のいずれかの方法を使用します。

構成ファイルの作成時に --activate フラグを使用した場合、または gcloud config set auth/LOGIN_CONFIG_FILE で構成ファイルを有効にした場合、gcloud CLI は構成ファイルを自動的に使用します。
```
gcloud auth login
```
構成ファイルの場所を指定してログインするには、次のコマンドを実行します。
```
gcloud auth login --login-config=LOGIN_CONFIG_FILE
```
環境変数を使用して構成ファイルの場所を指定するには、CLOUDSDK_AUTH_LOGIN_CONFIG_FILE を構成パスに設定します。

ログイン構成ファイルの使用を停止するには、次の手順を行います。

構成ファイルの作成時に --activate フラグを使用した場合、または gcloud config set auth/LOGIN_CONFIG_FILE で構成ファイルを有効にした場合は、次のコマンドを実行して設定を解除する必要があります。
```
gcloud config unset auth/login_config_file
```
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境変数が設定されている場合は、クリアします。

ログインに構成ファイルを使用する

このセクションでは、ブラウザベースのログインの代わりに、認証情報の構成ファイルを使用して認証済みの Google Cloud アクションにアクセスできるようにするさまざまな方法について説明します。構成ファイルを設定する際に、gcloud CLI にログインする必要はありません。

構成ファイルの設定方法は、IdP が OIDC と SAML のどちらを使用しているかによって異なります。

OIDC

構成ファイルの設定に使用する認証情報は、次のソースから提供できます。

ファイル提供の認証情報
URL 提供の認証情報
非対話型の実行可能ファイル提供の認証情報
対話型の実行可能ファイル提供の認証情報

ファイル提供の認証情報

トークンはファイルから読み込まれます。古いトークンが期限切れになる前に、別のプロセスでこのファイルを新しい OIDC トークンで更新する必要があります。たとえば、トークンの有効期間が 1 時間の場合、1 時間経過する前にファイルを更新する必要があります。

次のコマンドを実行して、ファイル提供の認証情報で構成ファイルを生成します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

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

WORKFORCE_POOL_ID: Workforce プール ID
PROVIDER_ID: プロバイダ ID
PATH_TO_OIDC_TOKEN: OIDC IdP 認証情報ファイルのパス
WORKFORCE_POOL_USER_PROJECT: Workforce プールユーザープロジェクトに関連付けられたプロジェクト番号または ID。

プリンシパルには、このプロジェクトに対する serviceusage.services.use 権限が必要です。

このコマンドを実行すると、次のような OIDC IdP 構成ファイルが生成されます。

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

URL 提供の認証情報

トークンは、HTTP GET リクエストに応答するエンドポイントを持つローカルサーバーから読み込まれます。レスポンスは、書式なしテキストまたは JSON 形式の OIDC ID トークンでなければなりません。

次のコマンドを実行して、URL 提供の認証情報で構成ファイルを生成します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
URL_TO_RETURN_OIDC_ID_TOKEN: OIDC ID トークンなどの OIDC 認証情報を取得するために呼び出す URL（例: http://localhost:5000/token）。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号。プリンシパルには、このプロジェクトに対する serviceusage.services.use permission が必要です。

このコマンドを実行すると、次のような OIDC IdP 構成ファイルが生成されます。

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

非対話型の実行可能ファイル提供の認証情報

トークンはローカルの実行可能ファイルから読み込まれます。実行可能ファイルは、期限切れでない有効な OIDC ID トークンを JSON 形式で stdout に提供する必要があります。

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

これらのフィールドは、正常なレスポンスに必要です（expiration_time を除く）。expiration_time フィールドは、認証情報の構成で出力ファイルが指定されている場合にのみ必要です。

実行可能ファイルは、次の JSON 形式で stdout にエラーを表示する必要があります。

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

エラーレスポンスの場合、これらのフィールドがすべて必須です。コードフィールドとメッセージフィールドは、該当するエラーが発生したときにクライアントライブラリで使用されます。

このコマンドは、次のフィールドを返すことができます。

version: JSON 出力のバージョン。version 1 のみサポートしています。
success: レスポンスのステータス。ステータスが true の場合、実行可能ファイルは終了コード 0 で終了し、レスポンスに次のフィールドが含まれている必要があります。
- token_type: id_token
- expiration_time フィールド（出力ファイルが認証情報の構成で指定されている場合）
ステータスが false の場合、実行可能ファイルはゼロ以外の値で終了し、レスポンスに次のフィールドが含まれている必要があります。
- code
- message
token_type: サードパーティのサブジェクトトークンタイプ（urn:ietf:params:oauth:token-type:id_token でなければなりません）
id_token: サードパーティの OIDC トークン
expiration_time: サードパーティの OIDC トークンの有効期限（秒単位、Unix エポック時間）
code: エラーコードの文字列
message: エラーメッセージ

実行可能ファイルの実行時に、クライアントライブラリによって次の環境変数が設定されます。

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 認証情報構成のオーディエンスフィールド。常に存在します。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 想定されるサブジェクトトークンタイプ。常に存在します。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 認証情報構成の出力ファイルの場所。認証情報の構成で指定されている場合にのみ存在します。

実行可能ファイルでは、これらの環境変数を使用することで、値のハードコードを回避できます。

この認証情報の提供方法をクライアントライブラリで有効にするには、GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境変数を 1 に設定する必要があります。

次のコマンドを実行して、実行ファイル提供の認証情報で構成ファイルを生成します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
EXECUTABLE_COMMAND: OIDC ID トークンなどのサブジェクトトークンを取得するために実行する完全なコマンド（引数を含む）。形式は --executable-command="/path/to/command --foo=bar" です。
EXECUTABLE_TIMEOUT: （省略可）実行可能ファイルが実行されるのを待つ時間（ミリ秒単位）。デフォルトは 30 秒です。
EXECUTABLE_OUTPUT_FILE: （省略可）実行可能ファイルによって生成されたサードパーティの認証情報へのファイルパス。これは、認証情報をキャッシュに保存する場合に便利です。認証ライブラリは、実行可能ファイルを実行する前に、まずこのパスを確認します。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use 権限セットが設定されている必要があります。

このコマンドを実行すると、次のような OIDC IdP 構成ファイルが生成されます。

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

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

stdin と stdout を使用して、ユーザーとやり取りする実行可能ファイルを提供できます。ユーザーがログインに成功すると、実行可能ファイルは指定したファイルに、期限切れでない有効な認証情報を書き込みます。

このモードを使用するには、次のフラグが必要です。

--executable-output-file: 実行可能ファイルが認証情報を書き込むファイル
--exeutable-interactive-timeout-millis: インタラクティブモードを示すゼロ以外の値で、タイムアウトを設定します（例: 60 秒のタイムアウトの場合は 6000）。

レスポンスを成功させるには、以下のフィールドが必要です（expiration_time を除く）。

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

この実行可能ファイルは、--executable-output-file で指定されたファイルに次の JSON 形式でエラーを書き込む必要があります。エラーレスポンスを返す際は、次のフィールドがすべて必要です。

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

code フィールドと message フィールドは、該当するエラーを示す必要があります。これらのフィールドは、エラーが発生したときにクライアントライブラリで使用されます。

このコマンドが正常に実行されると、前述の実行可能ファイルから提供されるインタラクティブモードの認証情報または非インタラクティブモードの認証情報のどちらを使用しても、同じフィールドが返されます。

環境変数も、通常の実行可能ファイル提供の認証情報と同じです。

対話型のファイル提供の認証情報を生成するには、--executable-interactive-timeout-millis パラメータと --executable-output-file パラメータを追加します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
EXECUTABLE_COMMAND: サブジェクトトークンを取得するために実行する完全なコマンド（引数を含む）。形式は --executable-command="/path/to/command --arg1=val1 --arg2=val2" です。
EXECUTABLE_INTERACTIVE_TIMEOUT: 実行可能ファイルが実行されるのを待つ時間（ミリ秒単位）。
EXECUTABLE_OUTPUT_FILE: 実行可能ファイルによって生成されたサードパーティの認証情報へのファイルパス。このパスは、認証情報をキャッシュに保存する場合に便利です。認証ライブラリは、実行可能ファイルを実行する前に、まずこのパスを確認します。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use 権限が付与されている必要があります。

このコマンドを実行すると、次のような OIDC IdP 構成ファイルが生成されます。

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

SAML

構成ファイルの設定に使用する認証情報は、次のソースから提供できます。

ファイル提供の認証情報
URL 提供の認証情報
実行可能ファイル提供の認証情報
gcloud インタラクティブモードの実行可能ファイル提供の認証情報

ファイル提供の認証情報

アサーションはファイルから読み込まれます。古いアサーションが期限切れになる前に、別のプロセスで新しい base64 でエンコードされた SAML アサーションを使用してこのファイルを更新する必要があります。たとえば、アサーションの有効期間が 1 時間の場合、1 時間経過する前にファイルを更新する必要があります。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
CREDENTIAL_FILE: IdP によって生成された認証情報のパス。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use permission が必要です。

URL 提供の認証情報

アサーションは、HTTP GET リクエストに応答するエンドポイントを持つローカルサーバーから読み込まれます。レスポンスは、base64 でエンコードされた SAML アサーションまたは base64 でエンコードされた SAML アサーションを含む JSON である必要があります。

URL 提供の認証情報を使用するには、--credential-source-url フラグを使用します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-url=CREDENTIAL_URL \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
CREDENTIAL_URL: ローカルサーバーエンドポイントの URL。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use permission が必要です。

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

アサーションはローカルの実行可能ファイルから読み込まれます。実行可能ファイルは、期限切れでない有効な SAML アサーションを JSON 形式で stdout に提供する必要があります。

{
  "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."
}

このコマンドは、次のフィールドを返すことができます。

version: JSON 出力のバージョン。バージョン 1 のみサポートしています。
success: レスポンスのステータス。ステータスが true の場合、実行可能ファイルは終了コード 0 で終了し、レスポンスに次のフィールドが含まれている必要があります。
- token_type: saml_response
- expiration_time フィールド（出力ファイルが認証情報の構成で指定されている場合）
ステータスが false の場合、実行可能ファイルはゼロ以外の値で終了し、レスポンスに次のフィールドが含まれている必要があります。 + code + message
token_type: サードパーティのサブジェクトトークンタイプ（urn:ietf:params:oauth:token-type:saml2 でなければなりません）
saml_response: サードパーティの SAML レスポンス
expiration_time: サードパーティの SAML レスポンスの有効期限（秒単位、Unix エポック時間）
code: エラーコードの文字列
message: エラーメッセージ

実行可能ファイルの実行時に、クライアントライブラリによって次の環境変数が設定されます。

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 認証情報構成のオーディエンスフィールド。常に存在します。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 想定されるサブジェクトトークンタイプ。常に存在します。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 認証情報構成の出力ファイルの場所。認証情報構成で指定されている場合にのみ存在します。

クライアントライブラリでこの認証情報の提供方法を有効にするには、GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境変数を 1 に設定します。

次のコマンドを実行して、実行ファイル提供の認証情報で構成ファイルを生成します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
EXECUTABLE_COMMAND: サブジェクトトークンを取得するために実行する完全なコマンド（引数を含む）。形式は --executable-command="/path/to/command --foo=bar" です。
EXECUTABLE_TIMEOUT: （省略可）実行可能ファイルが実行されるのを待つ時間（ミリ秒単位）。デフォルトは 30 秒です。
EXECUTABLE_OUTPUT_FILE: （省略可）実行可能ファイルによって生成された 3PI 認証情報へのファイルパス。これは、認証情報をキャッシュに保存する場合に便利です。認証ライブラリは、実行可能ファイルを実行する前にその存在を確認します。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号。プリンシパルには、このプロジェクトに対する serviceusage.services.use 権限が付与されている必要があります。

このコマンドを実行すると、次のような SAML IdP 構成ファイルが生成されます。

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

gcloud インタラクティブモードの実行可能ファイル提供の認証情報

実行可能ファイルは、コマンドラインを介してユーザーとやり取りします。

前述のコマンドで、次のように置き換えます。

EXECUTABLE_OUTPUT_FILE: （必須）実行可能ファイルによって生成された認証情報を提供するファイルのパス。
EXECUTABLE_TIMEOUT: （必須）タイムアウト値がゼロ以外の場合、インタラクティブモードを使用するようにコマンドに指示します。

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

これらのフィールドは、正常なレスポンスに必要です（expiration_time を除く）。expiration_time の欠落は、なんらかの方法で実行可能ファイルを実行するシグナルとして扱われます。

実行可能ファイルは、次の JSON 形式で executable-output-file にエラーを表示する必要があります。

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

成功した実行のコマンド戻りフィールドは、前述の通常の実行可能ファイル提供の認証情報の結果とまったく同じです。

環境変数も、通常の実行可能ファイル提供の認証情報と同じです。

実行可能ファイル提供の対話型の認証情報を生成するには、パラメータ --executable-interactive-timeout-millis を追加します。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: Workforce プール ID。
PROVIDER_ID: プロバイダ ID。
EXECUTABLE_COMMAND: サブジェクトトークンを取得するために実行する完全なコマンド（引数を含む）。形式は --executable-command="/path/to/command --foo=bar") です。
EXECUTABLE_INTERACTIVE_TIMEOUT: 実行可能ファイルが実行されるのを待つ時間（ミリ秒単位）。
EXECUTABLE_OUTPUT_FILE: 実行可能ファイルによって生成されたサードパーティの認証情報へのファイルパス。これは、認証情報をキャッシュに保存する場合に便利です。認証ライブラリは、実行可能ファイルを実行する前に、まずこのパスを確認します。
WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルは、このプロジェクトに対する serviceusage.services.use 権限を設定します。

このコマンドを実行すると、次のような SAML IdP 構成ファイルが生成されます。

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

ログインするには、次のコマンドを実行します。

gcloud auth login --cred-file=/path/to/config.json

CLI（gcloud、bq）は実行可能ファイル提供の認証情報タイプをサポートしていません。

ヘッドレスフローの場合、gcloud は自動的にスコープ https://www.googleapis.com/auth/cloud-platform を使用します。gcloud は、認証情報を Security Token Service エンドポイントに透過的に送信し、そこで一時的な Google Cloud アクセストークンと交換されます。

これで、gcloud CLI を使用して gcloud コマンドを実行できるようになりました。

Google Cloud クライアントライブラリを使用する

サポートされているクライアントライブラリを使用する場合は、Google 認証情報が自動的に生成されるようにクライアントライブラリを構成できます。可能であれば、トークン交換プロセスを自身で実装しなくても済むように、認証情報を自動的に生成することをおすすめします。

Workforce プールの Google Cloud クライアントライブラリのサポートは、Node.js、Java、Python、Go、C ++（gRPC）の言語で提供されています。

これらのサービスや言語でクライアントライブラリを使用する手順は次のとおりです。

bq

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

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

FILEPATH は、認証情報の構成ファイルのパスです。

bq での Workforce Identity 連携は、Google Cloud CLI のバージョン 390.0.0 以降でサポートされています。

C++

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

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

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

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

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

FILEPATH は、認証情報の構成ファイルのパスです。

gcloud での Workforce Identity 連携のサポートは、Google Cloud CLI のバージョン 392.0.0 以降で利用できます。

Go

Go 用クライアントライブラリは、golang.org/x/oauth2 モジュールのバージョン v0.0.0-20211005180243-6b3c2da341f1 以降を使用している場合、Workforce Identity 連携をサポートします。

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

Java

Java 用のクライアントライブラリは、com.google.auth:google-auth-library-oauth2-http アーティファクトのバージョン 1.2.0 以降を使用している場合、Workforce Identity 連携をサポートします。

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Node.js 用のクライアントライブラリは、Workforce Identity 連携をサポートしています。バージョン 7.10.0 以降の google-auth-library パッケージを使用する必要があります。Workload Identity プールとは異なり、Workforce プールは Google Cloud プロジェクトではなく組織に関連付けられます。GoogleAuth オブジェクトを作成するときに、プロジェクト ID を指定する必要があります。詳細については、google-auth-library パッケージの README をご覧ください。

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

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

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

上の例で、ライブラリが自動検出できない場合、project の値は None になることがあります。これは、サービスインスタンスを使用する場合に（ストレージクライアントの例のように）明示的に渡すか、環境変数 GOOGLE_CLOUD_PROJECT を使用して設定できます。

詳細については、google-auth パッケージのユーザーガイドをご覧ください。

REST API を使用する

Google Cloud Security Token Service API を呼び出して、外部認証情報を Google Cloud アクセストークンと交換できます。

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_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=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

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

AUDIENCE: サブジェクトトークンを発行するプロバイダの完全なリソース名。
PROVIDER_ID: プロバイダ ID
SUBJECT_TOKEN_TYPE: 次のいずれかに設定します。
- OIDC ID トークンの場合は urn:ietf:params:oauth:token-type:id_token
- SAML アサーションの場合は urn:ietf:params:oauth:token-type:saml2
EXTERNAL_SUBJECT_TOKEN: アクセストークンがリクエストされたプリンシパルの ID を表す IdP 発行のトークンです。注: OIDC を使用する場合、トークンは JWT 形式になります。
BILLING_PROJECT_NUMBER: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use 権限が必要です。

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

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

gcloud CLI を使用してセッションを管理する

gcloud が Security Token Service エンドポイントから取得する一時的な Google Cloud トークンは、指定した期間が経過すると期限切れになります。トークンの有効期限が切れる直前に、gcloud は、提供された認証情報ファイルを検査し、IdP から受け取った認証情報の有効性を検査します。認証情報がまだ有効な場合、gcloud は新しい Google Cloud アクセストークンを透過的に取得し、現在のセッションを中断することなく実行します。

認証情報が期限切れになっている場合、新しい Google Cloud トークンは発行されません。それらの認証情報を使用して呼び出すと失敗します。この時点で、再認証する必要があります。

セッションを終了するには、次のコマンドを実行します。

gcloud auth revoke

gcloud は複数のユーザーセッションをサポートしています。現在アクティブなセッションを含むセッションのリストを取得するには、次のコマンドを実行します。

gcloud auth list

コマンドの出力は、次のようになります。

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

別のセッションに切り替えてアクティブに設定するには、次のコマンドを実行します。

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

次のステップ

Workforce Identity 連携ユーザーとそのデータを削除する
Workforce Identity 連携をサポートする Google Cloud プロダクトを確認する
コンソール（連携）へのユーザーアクセスを設定する

Workforce Identity 連携の有効期間が短いトークンを取得する

始める前に

Google Cloud アクセス トークンの外部認証情報を交換する

gcloud CLI を使用したブラウザベースのログイン

ログイン構成ファイルを作成する

ブラウザベースの認証を使用してログインする

ブラウザベースのログインを無効にする

ログインに構成ファイルを使用する

OIDC

ファイル提供の認証情報

URL 提供の認証情報

非対話型の実行可能ファイル提供の認証情報

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

SAML

ファイル提供の認証情報

URL 提供の認証情報

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

gcloud インタラクティブ モードの実行可能ファイル提供の認証情報

Google Cloud クライアント ライブラリを使用する

bq

C++

gcloud

Go

Java

Node.js

Python

REST API を使用する

gcloud CLI を使用してセッションを管理する

次のステップ

Google Cloud アクセストークンの外部認証情報を交換する

gcloud インタラクティブモードの実行可能ファイル提供の認証情報

Google Cloud クライアントライブラリを使用する