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

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

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

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

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

始める前に

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

   • Azure AD ベースの Workforce Identity 連携を構成する
   • Okta ベースの Workforce Identity 連携を構成する

2. Workforce プール ID またはプロバイダ ID を把握している必要があります。

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

4. IAM and Security Token Service API を有効にします。

   API を有効にする

5. Google Cloud CLI をインストールし、次のコマンドを実行して初期化します。

   gcloud init

   注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。

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

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

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

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

このセクションでは、ブラウザベースのログインフローを使用するように 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",
}

注意: まず、このファイルの内容が正しいことを確認して、ファイルを保護することをおすすめします。たとえば、ファイルを読み取り専用にし、ACL でのアクセスを制限します。ファイルは検証されません。このファイルへの書き込みアクセス権を持つ悪意のある人物が、エンドポイントを変更して認証情報を傍受する可能性があります。

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

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

• 構成ファイルの作成時に --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",
    }
  }
}

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

SAML

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

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

ファイル提供の認証情報

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

注: 構成ファイルを生成するときに、--subject-token-type=urn:ietf:params:oauth:token-type:saml2 フラグを渡す必要があります。

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
}

これらのフィールドは、正常なレスポンスに必要です（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/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>",
    }
  }
}

注: timeout_millis は、実行可能ファイルから提供される対話型の認証情報が非インタラクティブ モードで実行される場合があります。gcloud CLI 構成生成ツールは、このフィールドにデフォルトのタイムアウト値（30 秒）を自動的に設定します。

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

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

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

ヘッドレス フローの場合、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)
}

gsutil

Workforce Identity 連携を使用して認証を行うには、次のいずれかの方法を使用します。

gsutil と gcloud を併用する場合は、通常どおりログインします。

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

gsutil をスタンドアロン コマンドライン アプリケーションとして使用する場合は、.boto ファイルを編集して次のセクションを含めます。

[Credentials]
gs_external_account_file = FILEPATH

どちらの場合も、認証情報の構成ファイルへのファイルパスは FILEPATH です。

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

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
*         [e-mail]
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/[e-mail]

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

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

次のステップ

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