透過 AWS 或 Azure 設定 Workload Identity 聯盟

本指南說明如何使用 Workload Identity Federation，讓 AWS 和 Azure 工作負載向 Google Cloud 進行驗證，不必使用服務帳戶金鑰。

透過 Workload Identity Federation，在 AWS EC2 和 Azure 上執行的工作負載可以將環境專屬憑證換成短期 Google CloudSecurity Token Service 權杖。

特定環境的憑證包括：

• AWS EC2 執行個體可使用執行個體設定檔要求臨時憑證。
• Azure VM 可使用受控識別取得 Azure 存取權權杖。

設定 Workload Identity 聯盟後，這些工作負載就能以這些環境專屬的憑證，換取短期 Google Cloud 憑證。工作負載可使用這些短期憑證存取Google Cloud API。

事前準備

• 設定驗證方法。

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  Python

  如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command:

     gcloud init

  4. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

     If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  詳情請參閱 Google Cloud 驗證說明文件中的「 為本機開發環境設定 ADC」。

準備外部識別資訊提供者

每個 Microsoft Entra ID 租戶或 AWS 帳戶只需執行一次這些步驟。

設定 Workload Identity 聯盟

每個 AWS 帳戶或 Microsoft Entra ID 租戶只需執行一次這些步驟。然後，您就能在多個工作負載和多個 Google Cloud 專案中使用相同的工作負載身分識別集區和提供者。

如要開始設定 Workload Identity 聯盟，請按照下列步驟操作：

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

   Go to project selector

建議您 使用專案管理 workload identity pool 和提供者。

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

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

Enable the APIs

定義屬性對應和條件

AWS 或 Azure 工作負載的環境專屬憑證包含多個屬性，您必須決定要在 Google Cloud中使用哪個屬性做為主體 ID (google.subject)。

Google Cloud 會使用 Cloud 稽核記錄和主體 ID 中的主體 ID，不重複地識別 AWS 或 Azure 使用者或角色。

你也可以視需要對應其他屬性。 授予資源存取權時，您可以參考這些額外屬性。

google.subject=assertion.arn
attribute.account=assertion.account
attribute.aws_role=assertion.arn.extract('assumed-role/{role}/')
attribute.aws_ec2_instance=assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')

google.subject=assertion.sub

google.subject=assertion.sub.extract('/eid1/c/pub/t/{sub_claim}')

視需要定義屬性條件。屬性條件是 CEL 運算式，可檢查聲明屬性和目標屬性。如果屬性條件評估結果為 true，系統就會接受該憑證。否則系統會拒絕認證。

assertion.arn.startsWith('arn:aws:sts::AWS_ACCOUNT_ID:assumed-role/')

建立工作負載身分集區和提供者

您現在已收集建立 workload identity pool 和提供者所需的所有資訊：

驗證工作負載

您必須為每個工作負載執行這些步驟一次。

允許外部工作負載存取 Google Cloud 資源

如要授予工作負載資源存取權，建議您直接授予主體資源存取權。 Google Cloud 在本例中，主體是聯合使用者。部分 Google Cloud 產品有 Google Cloud API 限制。如果工作負載呼叫的 API 端點設有限制，您可以改用服務帳戶模擬功能。在本例中，主體是Google Cloud 服務帳戶，也就是身分。您授予資源的服務帳戶存取權。

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

下載或建立憑證設定

Cloud 用戶端程式庫、gcloud CLI 和 Terraform 可以自動取得外部憑證，並使用這些憑證模擬服務帳戶。如要讓程式庫和工具完成這項程序，您必須提供憑證設定檔。這個檔案定義了下列項目：

• 如何取得外部憑證
• 要使用的 workload identity pool 和提供者
• 要模擬哪個服務帳戶

如要建立憑證設定檔，請按照下列步驟操作：

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

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

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

使用憑證設定存取 Google Cloud

如要讓工具和用戶端程式庫使用憑證設定，請在 AWS 或 Azure 環境中執行下列操作：

1. 初始化環境變數 GOOGLE_APPLICATION_CREDENTIALS，並指向憑證設定檔：

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   其中 FILEPATH 是憑證設定檔的相對路徑。

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   其中 FILEPATH 是憑證設定檔的相對路徑。

2. 使用支援 Workload Identity 聯盟且可自動尋找憑證的用戶端程式庫或工具：

   C++

   自 v2.6.0 版起，Google Cloud C++ 用戶端程式庫支援 Workload Identity Federation。如要使用 Workload Identity 聯盟，您必須使用 1.36.0 以上版本的 gRPC 建構用戶端程式庫。

   Go

   如果 Go 的用戶端程式庫使用 golang.org/x/oauth2 模組的 v0.0.0-20210218202405-ba52d332ba99 以上版本，即可支援 Workload Identity Federation。

   如要查看用戶端程式庫使用的這個模組版本，請執行下列指令：

   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 以上版本，即可支援 Workload Identity 聯盟。

   如要查看用戶端程式庫使用的構件版本，請在應用程式目錄中執行下列 Maven 指令：

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

   Node.js

   如果 Node.js 適用的用戶端程式庫使用 google-auth-library 套件 7.0.2 以上版本，即可支援 Workload Identity Federation。

   如要查看用戶端程式庫使用的套件版本，請在應用程式目錄中執行下列指令：

   npm list google-auth-library
   

   建立 GoogleAuth 物件時，您可以指定專案 ID，也可以允許 GoogleAuth 自動尋找專案 ID。如要自動找出專案 ID，設定檔中的服務帳戶必須在專案中具備「瀏覽器」角色 (roles/browser)，或是其他具備同等權限的角色。詳情請參閱 google-auth-library 套件的README。

   Python

   如果 Python 適用的用戶端程式庫使用 google-auth 套件 1.27.0 以上版本，即可支援 Workload Identity Federation。

   如要查看用戶端程式庫使用的套件版本，請在安裝套件的環境中執行下列指令：

   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 363.0.0 以上版本支援 gcloud CLI 中的 Workload Identity Federation。

   Terraform

   如果您使用 3.61.0 以上版本，Google Cloud 供應商支援工作負載身分聯盟：

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

   bq

   如要使用 Workload Identity 聯盟進行驗證，請使用 gcloud auth login 指令，如下所示：

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

   將 FILEPATH 替換為憑證設定檔的路徑。

   如要在 bq 中使用 Workload Identity Federation，請使用 gcloud CLI 390.0.0 以上版本。

   如果無法使用支援工作負載身分聯盟的用戶端程式庫，可以使用 REST API 透過程式驗證。

進階情境

使用 REST API 驗證工作負載

如果無法使用用戶端程式庫，請按照下列步驟操作，讓外部工作負載使用 REST API 取得短期存取權杖：

1. 從外部 IdP 取得憑證：

   AWS

   建立 JSON 文件，其中包含您通常會在對 AWS GetCallerIdentity() 端點提出的要求中加入的資訊，包括有效的要求簽章。

   Workload Identity Federation 將這個 JSON 文件稱為 GetCallerIdentity 權杖。Workload Identity Federation 可透過這個權杖驗證身分，不必公開 AWS 私密存取金鑰。

   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：AWS STS 端點的網址 (適用於 GetCallerIdentity())，並將標準 GetCallerIdentity() 要求的本文附加為查詢參數。例如：https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15。建議您使用區域 STS 端點，並為工作負載設計可靠的基礎架構。詳情請參閱「區域 AWS STS 端點」。
   • method：HTTP 要求方法：POST。
   • headers：HTTP 要求標頭，必須包含：
     • Authorization：要求簽章。
     • host：url 欄位的主機名稱，例如 sts.amazonaws.com。
     • x-amz-date：您傳送要求的時間，格式為 ISO 8601 Basic 字串。這個值通常會設為目前時間，用於防範重送攻擊。
     • x-goog-cloud-target-resource：身分識別提供者的完整資源名稱，不含 https: 前置字元。例如：

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

     • x-amz-security-token：工作階段符記。如果您使用臨時安全憑證，才需要提供這項資訊。

   下列範例會建立經過網址編碼的 GetCallerIdentity 權杖。 擷取網址編碼的權杖，以供日後使用。此外，系統也會建立可供您參考的易讀權杖：

   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() -> None:
       # 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 是指令碼產生的網址編碼 GetCallerIdentity權杖。

   Azure

   連線至已指派受控身分的 Azure VM，並從 Azure 執行個體中繼資料服務 (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。

2. 使用 Security Token Service API 換取短期存取權杖：

   Bash

   STS_TOKEN=$(curl https://sts.googleapis.com/v1/token \
       --data-urlencode "audience=//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/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=$SUBJECT_TOKEN" | jq -r .access_token)
   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：含有工作負載身分集區的專案專案編號
   • POOL_ID：工作負載身分集區的 ID
   • PROVIDER_ID：工作負載身分集區提供者的 ID

3. 如果您使用服務帳戶模擬，請使用 Security Token Service 的權杖，叫用 IAM Service Account Credentials API 的 generateAccessToken 方法，取得存取權杖。

Cloud Run 服務的權杖

存取 Cloud Run 服務時，您必須使用 ID 權杖。

TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken \
    -H "Content-Type: text/json; charset=utf-8" \
    -H "Authorization: Bearer $STS_TOKEN" \
    -d @- <<EOF | jq -r .token
    {
        "audience": "SERVICE_URL"
    }
EOF
)
echo $TOKEN

$Token = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken" `
    -Headers @{ "Authorization" = "Bearer $StsToken" } `
    -ContentType "application/json" `
    -Body (@{
        "audience" = "SERVICE_URL"
    } | ConvertTo-Json)).token
Write-Host $Token

取代下列項目：

• SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址。
• SERVICE_URL：服務的網址，例如 https://my-service-12345-us-central1.run.app。您也可以將其設為自訂服務端點。詳情請參閱「瞭解自訂目標對象」。

其他平台的權杖

存取其他服務時，您必須使用存取權杖。

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 $TOKEN

$Token = (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 $Token

取代下列項目：

• SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址。

後續步驟

• 進一步瞭解 Workload Identity 聯盟。
• 瞭解使用 Workload Identity Federation 的最佳做法。
• 瞭解如何管理 workload identity pool 和提供者。