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

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

このガイドで説明する方法は、ヘッドレス マシンで使用できます。

有効期間が短いトークンは、このプロセスの概要を使用して取得できます。このプロセスについて詳しくは、このドキュメントの後半で説明します。

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

始める前に

  1. Workforce Identity 連携を構成する。IdP 固有の手順については、次のガイドをご覧ください。

    Workforce Identity プール ID と Workforce Identity プール プロバイダ ID をメモします。

  2. Identity and Access Management(IAM)権限 serviceusage.services.use があることを確認します。この権限を含む最小権限のロールは Service Usage ユーザー(roles/serviceusage.serviceUsageConsumer)です。

  3. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  4. Install the Google Cloud CLI, then initialize it by running the following command:

    gcloud init

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

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

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

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

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

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

ログイン構成ファイルを作成するには、次のコマンドを実行します。必要に応じて、--activate フラグを追加することで、このファイルを gcloud CLI のデフォルトとして有効にできます。その後、構成ファイルのパスを毎回指定しなくても gcloud auth login を実行できます。

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

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

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

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

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

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

gcloud auth login がこの構成ファイルを自動的に使用しないようにするには、gcloud config unset auth/login_config_file を実行して設定を解除します。

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

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

  • 構成ファイルの作成時に --activate フラグを使用した場合、または gcloud config set auth/login_config_file で構成ファイルを有効にした場合、gcloud CLI は構成ファイルを自動的に使用します。

    gcloud auth login
  • 構成ファイルの場所を指定してログインするには、次のコマンドを実行します。

    gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
  • 環境変数を使用して構成ファイルの場所を指定するには、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

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

ファイル提供の認証情報

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

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

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 Identity プールの ID
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ 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/WORKFORCE_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 提供の認証情報

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

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

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 Identity プールの ID。
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ 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/WORKFORCE_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 出力のバージョン。バージョン 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/WORKFORCE_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 Identity プールの ID。
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ 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/WORKFORCE_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"
    }
  }
}

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

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

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

  • --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/WORKFORCE_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 Identity プールの ID。
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ 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/WORKFORCE_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",
    }
  }
}

対話型の実行可能ファイルが非インタラクティブ モードで実行可能な場合もあるため、timeout_millis フィールドが返されます。インタラクティブ モードでは、このコマンドによりデフォルトのタイムアウトが返されます。

SAML

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

ファイル提供の認証情報

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

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 Identity プールの ID。
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ ID。
  • CREDENTIAL_FILE: IdP によって生成された認証情報のパス。
  • WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use permission が必要です。

URL 提供の認証情報

アサーションは、HTTP `GET` リクエストに応答するエンドポイントを持つローカル サーバーから読み込まれます。レスポンスは、[base64 でエンコードされた](https://toolbox.googleapps.com/apps/encode_decode/)SAML アサーションまたは base64 でエンコードされた SAML アサーションを含む JSON である必要があります。URL 提供の認証情報を使用するには、「--credential-source-url」フラグを使用します。 ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 Identity プール ID。WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ ID。CREDENTIAL_URL: ローカル サーバー エンドポイントの URL。WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する「serviceusage.services.use 権限」が必要です。

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

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

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

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

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

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

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 インタラクティブ モードの実行可能ファイル提供の認証情報

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/WORKFORCE_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 Identity プールの ID。
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ 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>WORKFORCE_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

gcloud CLI も bq コマンドライン ツールも、実行可能ファイル提供の認証情報タイプをサポートしていません。

ヘッドレス フローの場合、gcloud CLI は自動的にスコープ https://www.googleapis.com/auth/cloud-platform を使用します。gcloud CLI は、認証情報を 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 クライアント ライブラリのほとんどは、ChannelCredentials を呼び出して作成される grpc::GoogleDefaultCredentials() オブジェクトを使用して 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 CLI での Workforce Identity 連携は、Google Cloud CLI のバージョン 392.0.0 以降でサポートされています。

Go

Go 用 Cloud クライアント ライブラリは、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 用 Cloud クライアント ライブラリは、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 用 Cloud クライアント ライブラリは、google-auth-library パッケージのバージョン 7.10.0 以降を使用している場合、Workforce Identity 連携をサポートします。

Workload Identity プールとは異なり、Workforce Identity プールは 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 用 Cloud クライアント ライブラリは、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)

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

詳細については、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/WORKFORCE_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: サブジェクト トークンを発行するプロバイダの完全なリソース名
  • WORKFORCE_POOL_ID: Workforce Identity プールの ID
  • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ 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 CLI が Security Token Service エンドポイントから取得する一時的な Google Cloud トークンは、指定した期間が経過すると期限切れになります。トークンの有効期限が切れる直前に、gcloud CLI は、提供された認証情報ファイルを検査し、IdP から受け取った認証情報の有効性を検査します。認証情報がまだ有効な場合、gcloud CLI は新しい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

次のステップ