ID 連携により有効期間の短い認証情報を取得する

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このガイドでは、Workload Identity プールとプロバイダを使用して、有効期間の短い認証情報を取得する方法について説明します。このプロセスは次のとおりです。

  1. 信頼できる ID プロバイダから認証情報を取得します。
  2. Security Token Service から取得したトークンと認証情報を交換します。
  3. Security Token Service のトークンを使用してサービス アカウントの権限を借用し、有効期間の短い Google アクセス トークンを取得します。

有効期間の短い Google アクセス トークンを使用して、サービス アカウントにアクセス権が付与されているすべての Google Cloud リソースにアクセスできます。

始める前に

  1. IAM, Security Token Service, and Service Account Credentials API を有効にします。

    API を有効にする

  2. Workload Identity プールとプロバイダを作成して、外部 ID プロバイダと連携します。

  3. 外部 ID で権限を借用するサービス アカウントを作成します。

  4. 外部 ID にアクセスを許可するリソースに対するアクセス権をサービス アカウントに付与します。

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

外部 ID にサービス アカウントの権限借用を許可するには、サービス アカウントに Workload Identity ユーザーロール(roles/iam.workloadIdentityUser)を付与する必要があります。このロールは、特定の外部 ID または複数の外部 ID に付与できます。

  • 特定の外部 ID の場合は、google.subject 属性をチェックする属性条件を記述します。
  • 外部 ID のグループの場合は、google.groups 属性またはカスタム属性 attribute.NAME をチェックする属性条件を記述します。
  • Workload Identity プールの外部 ID には属性条件を使用しません。

コンソール

  1. Google Cloud コンソールで、[Workload Identity プール] ページに移動します。

    [Workload Identity プール] に移動

  2. 更新する Workload Identity プールを見つけてクリックします。

  3. [ アクセスを許可] をクリックします。

  4. [サービス アカウント] プルダウン リストで、外部 ID が権限借用するサービス アカウントを選択します。

  5. プール内でサービス アカウントの権限を借用する ID を選択します。

    • Workload Identity プールの特定の ID のみにサービス アカウントの権限借用を許可するには、[フィルタに一致する ID のみ] を選択します。

      [Attribute name] プルダウン リストで、フィルタリングする属性を選択します。

      [属性値] フィールドに、属性の想定値を入力します。

      たとえば、属性マッピング google.subject=assertion.sub を使用する場合は、属性名を subject に、属性値を外部 ID プロバイダによって発行されたトークンの sub クレームの値に設定します。

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

  6. [保存] をクリックします。

  7. [閉じる] をクリックします。

gcloud

  1. 外部 ID の識別子を作成します。

    • 特定の外部 ID:

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
      
    • 外部 ID のグループ:

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
      
    • 特定の属性を持つすべての外部 ID:

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
      
    • Workload Identity プール内のすべての外部 ID:

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
      

    次の値を置き換えます。

    現在のプロジェクトのプロジェクト番号を取得するには、次のコマンドを使用します。

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. サービス アカウントに Workload Identity ユーザーロール(roles/iam.workloadIdentityUser)を付与します。

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

    次の値を置き換えます。

    • SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス。
    • MEMBER_ID: 前のステップで特定したメンバー ID

クライアント ライブラリ、gcloud CLI、または Terraform を使用した認証

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

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

認証情報の構成ファイルをクライアント ライブラリで使用する方法は、外部 ID プロバイダによって異なります。

AWS

クライアント ライブラリは、EC2 インスタンス メタデータから一時的な認証情報を自動的に取得します。

Azure

クライアント ライブラリは、Azure Instance Metadata Service(IMDS)からアクセス トークンを自動的に取得します。

GitHub Actions

GitHub ID トークンを取得するために必要なパラメータはワークフローの実行によって異なるため、GitHub Actions ワークフローで静的な認証情報構成ファイルを使用することはできません。

google-github-actions/auth アクションを使用すると、ワークフローの実行中に認証情報構成ファイルが自動的に生成されます。terraform などのクライアント ライブラリとツールでは、この認証情報構成ファイルを使用して Google 認証情報を自動的に取得できます。

OIDC

クライアント ライブラリは、ローカル ファイル、HTTP URL、ローカル実行可能ファイルから認証情報を取得します。

  • ファイル提供の認証情報: トークンはファイルから読み込まれます。古いトークンが期限切れになる前に、別のプロセスでこのファイルを新しい OIDC トークンで更新する必要があります。たとえば、トークンの有効期間が 1 時間の場合、1 時間経過する前にファイルを更新する必要があります。
  • URL 提供の認証情報: トークンは、HTTP GET リクエストに応答するエンドポイントを持つローカル サーバーから読み込まれます。レスポンスは、書式なしテキストまたは JSON 形式の OIDC ID トークンでなければなりません。
  • 実行可能ファイル提供の認証情報: トークンはローカルの実行可能ファイルから読み込まれます。実行可能ファイルは、有効期限内の有効な 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 で終了する必要があります。false の場合、レスポンスにエラーコードとメッセージ フィールドが含まれ、ゼロ以外の値で終了する必要があります。
    • token_type: サードパーティのサブジェクト トークン タイプ。サポートされる値は、urn:ietf:params:oauth:token-type:id_tokenurn:ietf:params:oauth:token-type:jwt です。
    • id_token: サードパーティの OIDC トークン。
    • expiration_time: OIDC トークンの有効期限(秒単位、エポック時間)。
    • code: エラーコードの文字列。
    • message: エラー メッセージ。

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

    • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 認証情報構成のオーディエンス フィールド。常に存在します。
    • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 想定されるサブジェクト トークン タイプ。常に存在します。
    • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: サービス アカウントのメールアドレス。サービス アカウントの権限借用が使用されている場合にのみ存在します。
    • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 認証情報構成の出力ファイルの場所。認証情報の構成で指定されている場合にのみ存在します。

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

    この認証情報のソーシング メソッドをクライアント ライブラリで有効にするには、GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境変数を 1 に設定する必要があります。

OIDC(AD FS)

クライアント ライブラリは、ローカル ファイルまたは HTTP URL から認証情報を取得できますが、Windows の統合認証(IWA)は直接サポートされません。ログイン ユーザーのアクセス トークンを取得してローカル ファイルに保存するには、次の PowerShell コマンドを使用します。

(Invoke-RestMethod `
    -Uri "https://ADFS_DOMAIN/adfs/oauth2/token/" `
    -Method POST `
    -Body @{
        client_id = 'CLIENT_ID'
        grant_type = 'client_credentials'
        scope = 'openid'
        resource = 'RELYING_PARTY_ID'
        use_windows_client_authentication = 'true'
        } `
    -UseDefaultCredentials).access_token | Out-File -Encoding ASCII TOKEN_FILEPATH

次の値を置き換えます。

  • ADFS_DOMAIN: ファームの AD FS サーバーのパブリック ドメイン名。
  • CLIENT_ID: AD FS のアプリケーション登録のクライアント ID。
  • RELYING_PARTY_ID: AD FS で Workload Identity プール用のウェブ API アプリケーションを作成する場合に使用した証明書利用者 ID。
  • TOKEN_FILEPATH: AD FS トークンを保存する一時ファイルのパス。このファイルが、正規のユーザーだけが内容を読み取ることができる場所に保存されていることを確認してください。

有効期間が短い Google の認証情報は、限られた時間(デフォルトでは 1 時間)しか有効でないため、このコマンドを定期的に再実行する必要があります。

SAML

クライアント ライブラリは、ローカル ファイル、HTTP URL、ローカル実行可能ファイルから認証情報を取得します。

  • ファイル提供の認証情報: アサーションはファイルから読み込まれます。古いアサーションが期限切れになる前に、別のプロセスで新しい base64 でエンコードされた SAML アサーションを使用してこのファイルを更新する必要があります。たとえば、アサーションの有効期間が 1 時間の場合、1 時間経過する前にファイルを更新する必要があります。
  • URL 提供の認証情報: アサーションは、HTTP GET リクエストに応答するエンドポイントを持つローカル サーバーから読み込まれます。レスポンスは、base64 でエンコードされた SAML アサーションまたは base64 でエンコードされた SAML アサーションを含む JSON である必要があります。
  • 実行可能ファイル提供の認証情報: アサーションはローカルの実行可能ファイルから読み込まれます。この実行可能ファイルは、有効期限内の有効な 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 で終了する必要があります。false の場合、レスポンスにエラーコードとメッセージ フィールドが含まれ、ゼロ以外の値で終了する必要があります。
    • 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_IMPERSONATED_EMAIL: サービス アカウントのメールアドレス。サービス アカウントの権限借用が使用されている場合にのみ存在します。* GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 認証情報構成の出力ファイルの場所。認証情報の構成で指定されている場合にのみ存在します。

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

    この認証情報のソーシング メソッドをクライアント ライブラリで有効にするには、GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境変数を 1 に設定する必要があります。

クライアント ライブラリまたは Terraform が Workload Identity 連携を使用して認証できるようにするには、次の手順を行います。

  1. 認証情報構成ファイルを作成します。

    コンソール

    Google Cloud コンソールで、認証情報の構成ファイルをダウンロードします。

    1. Google Cloud コンソールで、[Workload Identity プール] ページに移動します。

      [Workload Identity プール] に移動

    2. 使用する ID プロバイダを含む Workload Identity プールを見つけてクリックします。

    3. [接続済みサービス アカウント] を選択します。

    4. 使用するサービス アカウントを見つけて、[ダウンロード] をクリックします。

    5. [アプリケーションの構成] ダイアログで、サービス アカウントの権限を借用する外部 ID を含むプロバイダを選択します。

    6. 次の追加設定を行います。

      AWS

      追加の設定は必要ありません。

      Azure

      リソースパス: Azure アプリケーションのアプリケーション ID URI

      OIDC

      OIDC トークンパス: 認証情報を取得するローカル ファイルパスまたは URL。

      フォーマット タイプ: ID トークンを取得するファイルまたは URL のレスポンスの形式。

      サブジェクト トークン フィールド名: レスポンス内でトークンが含まれるフィールド(フォーマット タイプが json の場合)。

      SAML

      SAML アサーション パス: 認証情報を取得するローカル ファイルパスまたは URL。

      フォーマット タイプ: アサーションを取得するファイルまたは URL のレスポンスの形式。

      アサーション フィールド名: アサーションを含むレスポンス内のフィールド(フォーマット タイプが json の場合)。

    7. [構成をダウンロード] を選択して認証情報の構成ファイルをダウンロードしてから、[閉じる] をクリックします。

    gcloud

    gcloud iam workload-identity-pools create-cred-config を使用して、認証情報の構成ファイルを作成します。

    AWS

    ライブラリが EC2 インスタンス メタデータからアクセス トークンを取得できるように認証情報の構成ファイルを作成します。

    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 \
        --aws \
        --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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル

    AWS IMDSv2 を使用している場合は、--enable-imdsv2 フラグを gcloud iam workload-identity-pools create-cred-config コマンドに追加する必要があります。

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --aws \
        --enable-imdsv2 \
        --output-file=FILEPATH.json
    

    Azure

    ライブラリが Azure Instance Metadata Service(IMDS)からアクセス トークンを取得できるように認証情報の構成ファイルを作成します。

    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 \
        --azure \
        --app-id-uri APPLICATION_ID_URI \
        --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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • APPLICATION_ID_URI: Azure アプリケーションのアプリケーション ID URI
    • FILEPATH: 構成を保存するファイル

    OIDC

    ファイルソースの認証情報を使用するには--credential-source-file フラグを使用します。

    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 \
        --output-file=FILEPATH.json \
        --credential-source-file=TOKEN_FILEPATH \
        --credential-source-type=SOURCE_TYPE \
        --credential-source-field-name=FIELD_NAME
    

    次の値を置き換えます。

    • 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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • TOKEN_FILEPATH: OIDC ID トークンが保存されているパス
    • SOURCE_TYPE: OIDC ID トークン ファイルの形式。text(デフォルト)または json に設定します。
    • FIELD_NAME: トークンを含むテキスト ファイルのフィールド(SOURCE_TYPEjson の場合)

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

    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 \
        --output-file=FILEPATH.json \
        --credential-source-url="TOKEN_URL" \
        --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
        --credential-source-type=SOURCE_TYPE \
        --credential-source-field-name=FIELD_NAME
    

    次の値を置き換えます。

    • PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
    • POOL_ID: Workload Identity プールの ID
    • PROVIDER_ID: Workload Identity プール プロバイダの ID
    • SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス。
    • SERVICE_ACCOUNT_TOKEN_LIFETIME: サービス アカウントのアクセス トークンの存続期間(秒単位)。指定しない場合のデフォルトは 1 時間です。1 時間を超える有効期間が必要な場合は、constraints/iam.allowServiceAccountCredentialLifetimeExtension 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • TOKEN_URL: OIDC ID トークンを取得する URL
    • KEY_nVALUE_n: TOKEN_URL への HTTP リクエストに含めるカスタム ヘッダー
    • SOURCE_TYPE: OIDC ID トークン ファイルの形式。text(デフォルト)または json に設定します。
    • FIELD_NAME: トークンを含むテキスト ファイルのフィールド(SOURCE_TYPEjson の場合)

    実行可能ファイル提供の認証情報を使用するには--executable-command フラグを使用します。

    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 \
        --output-file=FILEPATH.json \
        --executable-command=EXECUTABLE_COMMAND \
        --executable-timeout-millis=EXECUTABLE_TIMEOUT \
        --executable-output-file=EXECUTABLE_OUTPUT_FILE
    

    次の値を置き換えます。

    • 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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • EXECUTABLE_COMMAND: OIDC ID トークンを取得するために実行される完全なコマンド(引数を含む)(例: --executable-command="/path/to/command --foo=bar")
    • EXECUTABLE_TIMEOUT: 実行可能ファイルの実行を待つオプションの時間(ミリ秒単位、デフォルトは 30 秒)。
    • EXECUTABLE_OUTPUT_FILE: このファイルのパスは、実行可能ファイルによって生成された 3PI 認証情報を参照します。これは、認証情報をキャッシュに保存する場合に便利です。このパスを指定すると、Auth ライブラリは実行可能ファイルを実行する前に、まずその存在を確認します。

    OIDC(AD FS)

    一時構成ファイルから AD FS アクセス トークンを読み取れるように認証情報の構成ファイルを作成します。

    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 \
        --output-file=FILEPATH.json \
        --credential-source-file=TOKEN_FILEPATH \
        --credential-source-type=text
    

    次の値を置き換えます。

    • 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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • TOKEN_FILEPATH: AD FS トークンを含む一時ファイルのパス

    SAML

    ファイルソースの認証情報を使用するには--credential-source-file フラグを使用します。

    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 \
        --output-file=FILEPATH.json \
        --credential-source-file=TOKEN_FILEPATH \
        --credential-source-type=SOURCE_TYPE \
        --credential-source-field-name=FIELD_NAME \
        --subject-token-type=urn:ietf:params:oauth:token-type:saml2
    

    次の値を置き換えます。

    • 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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • TOKEN_FILEPATH: SAML アサーションが保存されるパス
    • SOURCE_TYPE: SAML アサーション ファイルの形式。text(デフォルト)または json に設定します。
    • FIELD_NAME: アサーションを含むテキスト ファイルのフィールド(SOURCE_TYPEjson の場合)

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

    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 \
        --output-file=FILEPATH.json \
        --credential-source-url="TOKEN_URL" \
        --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
        --credential-source-type=source_type \
        --credential-source-field-name=field_name
        --subject-token-type=urn:ietf:params:oauth:token-type:saml2
    

    次の値を置き換えます。

    • 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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • TOKEN_URL: SAML アサーションを取得する URL
    • KEY_nVALUE_n: TOKEN_URL への HTTP リクエストに含めるカスタム ヘッダー
    • SOURCE_TYPE: SAML アサーション ファイルの形式。text(デフォルト)または json に設定します。
    • FIELD_NAME: アサーションを含むテキスト ファイルのフィールド(SOURCE_TYPEjson の場合)

    実行可能ファイル提供の認証情報を使用するには--executable-command フラグを使用します。

    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 \
        --output-file=FILEPATH.json \
        --executable-command=EXECUTABLE_COMMAND \
        --executable-timeout-millis=EXECUTABLE_TIMEOUT \
        --executable-output-file=EXECUTABLE_OUTPUT_FILE
    

    次の値を置き換えます。

    • 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 制約を適用する組織のポリシーの許容値としてサービス アカウントを追加する必要があります。
    • FILEPATH: 構成を保存するファイル
    • EXECUTABLE_COMMAND: SAML アサーションを取得するために実行する完全なコマンド
    • EXECUTABLE_TIMEOUT: 実行可能ファイルの実行を待つオプションの時間(ミリ秒単位、デフォルトは 30 秒)。
    • EXECUTABLE_OUTPUT_FILE: 実行可能レスポンスを保存するオプションの出力ファイル

    GitHub Actions

    GitHub Actions YAML ファイルを編集して、次の内容を追加します。

    • ジョブが GitHub ID トークンを取得できるようにするには、次の構成を追加します。

      permissions:
        id-token: write
        contents: read
      
    • 認証情報構成ファイルを作成するステップを追加します。

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v0.3.1'
        with:
          create_credentials_file: true
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'
      

    次の値を置き換えます。

    • PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
    • POOL_ID: Workload Identity プールの ID
    • PROVIDER_ID: Workload Identity プール プロバイダの ID
    • SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス。

    例:

    jobs:
      build:
        # Allow the job to fetch a GitHub ID token
        permissions:
          id-token: write
          contents: read
    
        runs-on: ubuntu-latest
    
        steps:
          - uses: actions/checkout@v2
    
          - id: 'auth'
            name: 'Authenticate to Google Cloud'
            uses: 'google-github-actions/auth@v0.3.1'
            with:
              create_credentials_file: true
              workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
              service_account: 'SERVICE_ACCOUNT_EMAIL'
    
  2. 環境変数 GOOGLE_APPLICATION_CREDENTIALS を初期化し、認証情報の構成ファイルを指すように設定します。

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
      
    FILEPATH は、認証情報の構成ファイルの相対パスです。

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
      
    FILEPATH は、認証情報の構成ファイルの相対パスです。

    GitHub Actions YAML

    google-github-actions/auth アクションにより、自動的に GOOGLE_APPLICATION_CREDENTIALS が初期化されます。
  3. Workload Identity 連携をサポートし、認証情報を自動的に検索できるクライアント ライブラリを使用します。

    C++

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

    C++ 用 Cloud Storage クライアント ライブラリは、gRPC ではなく REST API を使用するため、ID 連携をサポートしていません。

    Go

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

    クライアント ライブラリが使用しているこのモジュールのバージョンを確認するには、次のコマンドを実行します。

    cd $GOPATH/src/cloud.google.com/go
    go list -m golang.org/x/oauth2
    

    Java

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

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

    mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
    

    Node.js

    Node.js 用クライアント ライブラリは、google-auth-library パッケージのバージョン 7.0.2 以降を使用している場合、ID 連携をサポートします。

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

    npm list google-auth-library
    

    GoogleAuth オブジェクトを作成するときに、プロジェクト ID を指定できます。また、GoogleAuth で自動的にプロジェクト ID を検出することもできます。プロジェクト ID を自動的に検出するには、構成ファイルのサービス アカウントに、プロジェクト上でブラウザのロール(roles/browser)または同等の権限を持つロールが付与されている必要があります。詳細については、google-auth-library パッケージの README をご覧ください。

    Python

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

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

    pip show google-auth
    

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

    gcloud

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

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

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

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

    Terraform

    バージョン 3.61.0 以降を使用している場合、Google Cloud プロバイダは Workload Identity 連携をサポートしています。

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = "~> 3.61.0"
        }
      }
    }
    

    gsutil

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

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

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

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

    [Credentials]
    gs_external_account_file = FILEPATH
    

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

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

    bq

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

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

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

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

REST API を使用した認証

クライアント ライブラリを使用できない場合は、REST API を使用して外部 ID で有効期間の短いアクセス トークンを取得できるように、次の手順を行います。

  1. 外部 ID プロバイダから認証情報を取得します。

    AWS

    有効なリクエスト署名など、AWS GetCallerIdentity() エンドポイントへのリクエストに通常含まれる情報を含む JSON ドキュメントを作成します。

    Workload Identity 連携では、この JSON ドキュメントを GetCallerIdentity トークンと呼びます。このトークンを使用すると、Workload Identity 連携で AWS シークレット アクセスキーを公開せずに ID を確認できます。

    GetCallerIdentity トークンは次のような形式になります。

    {
      "url": "https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
      "method": "POST",
      "headers": [
        {
          "key": "Authorization",
          "value" : "AWS4-HMAC-SHA256 Credential=AKIASOZTBDV4D7ABCDEDF/20200228/us-east-1/sts/aws4_request, SignedHeaders=host;x-amz-date,Signature=abcedefdfedfd"
        },
        {
          "key": "host",
          "value": "sts.amazonaws.com"
        },
        {
          "key": "x-amz-date",
          "value": "20200228T225005Z"
        },
        {
          "key": "x-goog-cloud-target-resource",
          "value": "//iam.googleapis.com/projects/12345678/locations/global/workloadIdentityPools/my-pool/providers/my-aws-provider"
        },
        {
          "key": "x-amz-security-token",
          "value": "GizFWJTqYX...xJ55YoJ8E9HNU="
        }
      ]
    }
    

    このトークンには次のフィールドがあります。

    • url: GetCallerIdentity() の AWS STS エンドポイントの URL。標準の GetCallerIdentity() リクエストの本文がクエリ パラメータとして追加されます。例: https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15。リージョン エンドポイントもサポートされます。
    • method: HTTP リクエスト メソッド: POST
    • headers: HTTP リクエスト ヘッダー。次の情報を含める必要があります。
      • Authorization: リクエストの署名。
      • host: url フィールドのホスト名。たとえば、sts.amazonaws.com
      • x-amz-date: リクエストを送信する時刻。ISO 8601 の基本文字列の形式になります。通常、この値は現在の時刻に設定され、リプレイ攻撃の防止に使用されます。
      • x-goog-cloud-target-resource: https: 接頭辞のない ID プロバイダの完全なリソース名。次に例を示します。
        //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
        
      • x-amz-security-token: セッション トークン。一時的なセキュリティ認証情報を使用する場合にのみ必要です。

    次の例では、URL エンコードされた GetCallerIdentity トークンを作成します。後で使用するために、URL エンコードされたトークンを抽出します。また、参照用に人間が読める形式のトークンも作成します。

    import json
    import urllib
    
    import boto3
    from botocore.auth import SigV4Auth
    from botocore.awsrequest import AWSRequest
    
    def create_token_aws(project_number: str, pool_id: str, provider_id: str) -> None:
        # Prepare a GetCallerIdentity request.
        request = AWSRequest(
            method="POST",
            url="https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15",
            headers={
                "Host": "sts.amazonaws.com",
                "x-goog-cloud-target-resource": f"//iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/providers/{provider_id}"
            })
    
        # Set the session credentials and Sign the request.
        # get_credentials loads the required credentials as environment variables.
        # Refer:
        # https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
        SigV4Auth(boto3.Session().get_credentials(), "sts", "us-east-1").add_auth(request)
    
        # Create token from signed request.
        token = {
            "url": request.url,
            "method": request.method,
            "headers": []
        }
        for key, value in request.headers.items():
            token["headers"].append({"key": key, "value": value})
    
        # The token lets workload identity federation verify the identity without revealing the AWS secret access key.
        print("Token:\n%s" % json.dumps(token, indent=2, sort_keys=True))
        print("URL encoded token:\n%s" % urllib.parse.quote(json.dumps(token)))
    
    def main():
        # TODO(Developer): Replace the below credentials.
        # project_number: Google Project number (not the project id)
        project_number = "my-project-number"
        pool_id = "my-pool-id"
        provider_id = "my-provider-id"
    
        create_token_aws(project_number, pool_id, provider_id)
    
    if __name__ == "__main__":
        main()

    次の変数を初期化します。

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:aws:token-type:aws4_request"
    SUBJECT_TOKEN=TOKEN
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:aws:token-type:aws4_request"
    $SubjectToken = "TOKEN"
    

    TOKEN は、上記のスクリプトによって生成された、URL エンコードされた GetCallerIdentity トークンです。

    Azure

    マネージド ID が割り当てられている Azure VM に接続し、Azure Instance Metadata Service(IMDS)からアクセス トークンを取得します

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
    SUBJECT_TOKEN=$(curl \
      "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
      -H "Metadata: true" | jq -r .access_token)
    echo $SUBJECT_TOKEN
    

    このコマンドは jq ツールを使用します。Cloud Shell では jq がデフォルトで使用されます。

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = (Invoke-RestMethod `
      -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
      -Headers @{Metadata="true"}).access_token
    Write-Host $SubjectToken
    

    APP_ID_URI は、Workload Identity 連携用に構成したアプリケーションのアプリケーション ID URI です。

    GitHub Actions

    google-github-actions/auth を使用して GitHub ID トークンを取得し、有効期間が短いアクセス トークンと交換します。

    • ジョブが GitHub ID トークンを取得できるようにするには、次の構成を追加します。

      permissions:
        id-token: write
        contents: read
      
    • アクセス トークンを生成し、変数 ${{ steps.auth.outputs.access_token }} で利用可能にするステップを追加します。

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v0.3.1'
        with:
          token_format: 'access_token'
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'
      

    次の値を置き換えます。

    • PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
    • POOL_ID: Workload Identity プールの ID
    • PROVIDER_ID: Workload Identity プール プロバイダの ID
    • SERVICE_ACCOUNT_EMAIL: サービス アカウントのメールアドレス。

    例:

    jobs:
      build:
        # Allow the job to fetch a GitHub ID token
        permissions:
          id-token: write
          contents: read
    
        runs-on: ubuntu-latest
    
        steps:
          - uses: actions/checkout@v2
    
          - id: 'auth'
            name: 'Authenticate to Google Cloud'
            uses: 'google-github-actions/auth@v0.3.1'
            with:
              token_format: 'access_token'
              workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
              service_account: 'SERVICE_ACCOUNT_EMAIL'
    

    以下の手順をスキップします。

    OIDC

    外部 ID プロバイダからトークンを取得し、次の変数を初期化します。

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
    SUBJECT_TOKEN=TOKEN
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = "TOKEN"
    

    ここで、TOKEN は外部 ID プロバイダから発行されたトークンです。

    OIDC(AD FS)

    次の PowerShell コマンドを使用して IWA で AD FS への認証を行い、アクセス トークンを取得します。

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = (Invoke-RestMethod `
        -Uri "https://ADFS_DOMAIN/adfs/oauth2/token/" `
        -Method POST `
        -Body @{
            client_id = 'CLIENT_ID'
            grant_type = 'client_credentials'
            scope = 'openid'
            resource = 'RELYING_PARTY_ID'
            use_windows_client_authentication = 'true'
            } `
        -Credential USER).access_token
    

    次の値を置き換えます。

    • ADFS_DOMAIN: AD FS サーバーまたはファームのパブリック ドメイン名。
    • CLIENT_ID: AD FS のアプリケーション登録のクライアント ID。
    • RELYING_PARTY_ID: AD FS で Workload Identity プール用のウェブ API アプリケーションを作成する場合に使用した証明書利用者 ID。このパラメータは、カスタムの証明書利用者 ID を使用する場合にのみ必要です。
    • USER: IWA に使用する Active Directory ユーザー。または、-Credential-UseDefaultCredentials に置き換えて現在の認証情報を使用します。

    SAML

    外部 ID プロバイダからアサーションを取得し、変数を初期化します。

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:saml2"
    SUBJECT_TOKEN=ASSERTION
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:saml2"
    $SubjectToken = "ASSERTION"
    

    ASSERTION は、外部 ID プロバイダによって発行され、base64 でエンコードされたアサーションです。

  2. Security Token Service API を使用して、有効期間の短いアクセス トークンと認証情報を交換します。

    Bash

    STS_TOKEN=$(curl -0 -X POST https://sts.googleapis.com/v1/token \
        -H 'Content-Type: text/json; charset=utf-8' \
        -d @- <<EOF | jq -r .access_token
        {
            "audience"           : "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
            "grantType"          : "urn:ietf:params:oauth:grant-type:token-exchange",
            "requestedTokenType" : "urn:ietf:params:oauth:token-type:access_token",
            "scope"              : "https://www.googleapis.com/auth/cloud-platform",
            "subjectTokenType"   : "$SUBJECT_TOKEN_TYPE",
            "subjectToken"       : "$SUBJECT_TOKEN"
        }
    EOF
    )
    echo $STS_TOKEN
    

    PowerShell

    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
    $StsToken = (Invoke-RestMethod `
        -Method POST `
        -Uri "https://sts.googleapis.com/v1/token" `
        -ContentType "application/json" `
        -Body (@{
            "audience"           = "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID"
            "grantType"          = "urn:ietf:params:oauth:grant-type:token-exchange"
            "requestedTokenType" = "urn:ietf:params:oauth:token-type:access_token"
            "scope"              = "https://www.googleapis.com/auth/cloud-platform"
            "subjectTokenType"   = $SubjectTokenType
            "subjectToken"       = $SubjectToken
        } | ConvertTo-Json)).access_token
    Write-Host $StsToken
    

    次の値を置き換えます。

    • PROJECT_NUMBER: Workload Identity プールを含むプロジェクトのプロジェクト番号
    • POOL_ID: Workload Identity プールの ID
    • PROVIDER_ID: Workload Identity プール プロバイダの ID
  3. セキュリティ トークン サービスから取得したトークンを使用して、IAM Service Account Credentials APIgenerateAccessToken メソッドを呼び出し、アクセス トークンを取得します。

    Bash

    ACCESS_TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken \
        -H "Content-Type: text/json; charset=utf-8" \
        -H "Authorization: Bearer $STS_TOKEN" \
        -d @- <<EOF | jq -r .accessToken
        {
            "scope": [ "https://www.googleapis.com/auth/cloud-platform" ]
        }
    EOF
    )
    echo $ACCESS_TOKEN
    

    PowerShell

    $AccessToken = (Invoke-RestMethod `
        -Method POST `
        -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" `
        -Headers @{ "Authorization" = "Bearer $StsToken" } `
        -ContentType "application/json" `
        -Body (@{
            "scope" = , "https://www.googleapis.com/auth/cloud-platform"
        } | ConvertTo-Json)).accessToken
    Write-Host $AccessToken
    

    SERVICE_ACCOUNT_EMAIL は、サービス アカウントのメールアドレスに置き換えます。

外部認証情報の確認

Security Token Service API は、外部 ID プロバイダによって発行された認証情報を次の手順で検証します。

AWS

  • GetCallerIdentity トークンの次のフィールドを確認します。

    • url には、ホスト名が sts.amazonaws.com(またはリージョン サブドメイン)で、ポートのない HTTPS URI を指定する必要があります。具体的には、次のクエリ パラメータが存在します。
      • action = getcalleridentity
      • version(任意の値)
    • methodPOST
    • 次の headers が存在します。x-amz-dateauthorizationhostx-goog-cloud-target-resourcex-amz-security-token(省略可)
      • x-goog-cloud-target-resource の値は、Workload Identity プール プロバイダのリソース名です。
      • x-amz-date は直近 15 分以内の値で、将来の値ではありません。
  • sts.amazonaws.com または関連するリージョンのサブドメインに対してリクエストを実行し、AWS アカウント ID が Workload Identity プール プロバイダに構成されたアカウント ID と一致することを確認します。

Azure

Azure トークンは OIDC トークンで、OIDC トークンと同じ方法で検証されます。

GitHub Actions

GitHub トークンは OIDC トークンで、OIDC トークンと同じ方法で検証されます。

OIDC

OIDC トークンは、OIDC 仕様に従って検証されます。具体的には、セキュリティ トークン サービスは次の処理を行います。

  • ディスカバリ ドキュメントと署名の検証:

    • Workload Identity プール プロバイダで構成されている発行者に /.well-known/openid-configuration を追加して、検出エンドポイント URI を作成し、OIDC ディスカバリ ドキュメントを取得します。
    • ディスカバリ ドキュメント内の issuer クレームが、Workload Identity プール プロバイダで構成された発行者と等しいことを確認します。STS は、OIDC 仕様に準拠していない次の発行者に対してカスタム検証ロジックを用意しています。
      • Oracle Cloud(https://*.identity.oraclecloud.com
      • Microsoft(https://login.microsoftonline.com/common/v2.0https://login.microsoftonline.com/consumers/v2.0https://login.microsoftonline.com/organizations/v2.0
    • ディスカバリ ドキュメントにある jwks_uri から JSON Web Key Set(JWKS)を取得します。
    • JWT ヘッダーに kid クレームがある場合は、JWKS にある鍵と一致する鍵 ID を使用して JWT 署名を検証します。一致する鍵が見つからない場合は、トークンを拒否します。JWT ヘッダーに kid クレームがない場合は、JWKS にある各鍵を使用して JWT 署名を検証してください。署名の検証に使用できる鍵がある場合は、署名を受け入れます。
  • ヘッダーの確認:

    • alg クレームが存在し、RS256 または ES256 になっている必要があります。
  • ペイロードの確認:

    • iss クレームが存在し、ディスカバリ ドキュメント内の issuer クレームと一致している必要があります。STS は、OIDC 仕様に準拠していない次の発行者に対してカスタム検証ロジックを用意しています。
      • Oracle Cloud(https://*.identity.oraclecloud.com
      • Microsoft(https://login.microsoftonline.com/common/v2.0https://login.microsoftonline.com/consumers/v2.0https://login.microsoftonline.com/organizations/v2.0
    • aud クレームが存在し、https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID と一致している必要があります。代替の allowed_audiences が構成されている場合、aud クレームはいずれかの値にする必要があります。
    • exp クレームが存在している必要があります。これは将来の日付です。
    • iat クレームが存在している必要があります。これは過去の日付です。
    • exp の値は、iat の値よりも最大で 24 時間大きくする必要があります。

SAML

  • SAML 認証情報を Response または Assertion オブジェクトに Base64 でデコードして、アンマーシャルします。
  • SAML 認証情報を Response オブジェクトにマーシャリング解除した場合は、次の点を確認します。

    • レスポンスの StatusCode が urn:oasis:names:tc:SAML:2.0:status:Success と等しい。
    • Assertion が 1 つだけ存在します。
    • Response または Assertion の少なくとも 1 つが署名されている。署名ごとに、Workload Identity プール プロバイダで構成された各 X.509 証明書を使用して署名の検証を試みます。いずれかの証明書で署名が正常に検証されると、署名が受け入れられます。
    • Response が署名されている場合、ResponseIssuer が存在し、Workload Identity プール プロバイダで構成された SAML ID プロバイダのエンティティ ID と一致している必要があります。また、Format が省略されているか、urn:oasis:names:tc:SAML:2.0:nameid-format:entity と等しいことを確認します。
  • SAML 認証情報が Assertion オブジェクトにマーシャリング解除された場合は、次の点を確認します。

    • Assertion が署名されている。署名ごとに、Workload Identity プール プロバイダで構成された各 X.509 証明書を使用して署名の検証を試みます。いずれかの証明書で署名が正常に検証されると、署名が受け入れられます。
  • SAML 認証情報が Response または Assertion オブジェクトにマーシャリング解除されたかどうかにかかわらず、Assertion に次の属性が含まれていることを確認します。

    • Issuer が存在し、Workload Identity プール プロバイダで構成された SAML ID プロバイダのエンティティ ID と一致している必要があります。IssuerFormat は省略されるか、urn:oasis:names:tc:SAML:2.0:nameid-format:entity と等しい値になります。
    • IssueInstant が存在している必要があります。これは過去 1 時間以内の値です。
    • Subject が存在している必要があります。これには、以下の属性が含まれます。
      • NameID が存在している必要があります。
      • SubjectConfirmation が 1 つだけ存在し、Methodurn:oasis:names:tc:SAML:2.0:cm:bearer と一致している必要があります。NotOnOrAfterSubjectConfirmationData に存在している必要があります。これは将来の日付です。
      • NotBefore は存在しません。
    • Conditions が存在している必要があります。これには、以下の属性が含まれます。
      • NotBefore が存在する場合は、過去の日付でなければなりません。
      • NotOnOrAfter が存在する場合は、将来の日付でなければなりません。
      • 少なくとも 1 つの AudienceRestriction が必要です。すべての AudienceRestriction には、Workload Identity プール プロバイダのリソース名と同じ Audience を含める必要があります。
    • 少なくとも 1 つの AuthnStatement が必要です。
    • SessionNotOnOrAfter が存在する場合は、すべて将来の日付でなければなりません。

上記のプロトコル固有の検証手順に加えて、Security Token Service API は属性の条件が満たされているかどうかも検証します。

次のステップ