透過部署管道設定 Workload Identity Federation

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」。

必要的角色

如要取得設定 Workload Identity 聯盟所需的權限，請要求管理員授予您專案的工作負載身分集區管理員 (roles/iam.workloadIdentityPoolAdmin) 身分與存取權管理角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

或者，IAM 擁有者 (roles/owner) 基本角色也包含設定身分識別聯盟的權限。您不應在正式版環境中授予基本角色，但可以在開發或測試環境中授予。

準備外部 IdP

Azure DevOps

如要讓 Azure DevOps 管道向 Google Cloud進行驗證，請先設定 Azure Resource Manager 的服務連線。管道可透過這個連線取得 ID 權杖，然後換取Google Cloud 憑證。

如要為 Azure Resource Manager 建立服務連線，請按照下列步驟操作：

1. 在 Azure DevOps 中開啟專案，然後前往「Project Settings」。
2. 依序前往「Pipelines」>「Service connections」。
3. 按一下「建立服務連線」。
4. 選取「Azure Resource Manager」。
5. 點選「下一步」。

6. 進行下列設定：

   • 身分識別類型：應用程式註冊 (自動)
   • 憑證：工作負載身分聯盟

   • 範圍層級：訂閱項目。

     即使您不打算使用服務連線存取 Azure 資源，也必須選取訂閱項目。

   • 服務連線名稱：輸入名稱，例如 google-cloud。

7. 按一下 [儲存]。

在後續步驟中，您需要服務連結的簽發者和主體 ID。如要查詢這些詳細資料，請按照下列步驟操作：

1. 按一下您剛建立的服務連線。
2. 按一下「管理應用程式註冊」。
3. 依序選取「管理」>「憑證和密鑰」>「同盟憑證」。
4. 按一下同盟憑證。

5. 在「編輯憑證」頁面中，找出下列 ID：

   • 核發者：Azure DevOps 機構的專屬 ID
   • 主體 ID：服務連線的專屬 ID

Azure DevOps 會自動授予您選取為範圍的訂用帳戶，存取與新服務連線相關聯的服務主體。由於您不打算使用服務連線存取 Azure 資源，因此可以按照下列步驟撤銷存取權：

1. 在 Azure 入口網站中，開啟您選為範圍的訂閱項目。
2. 依序前往「存取權控管 (IAM)」>「角色指派」。
3. 找出服務連線的角色指派作業並移除。

GitHub Actions

您不需要在 GitHub 帳戶中進行任何設定變更。

設定工作負載身分集區以信任 GitHub 存放區後，該存放區中的工作流程就能使用 GitHub OIDC 權杖取得短期 Google Cloud 憑證。

GitLab SaaS

您不需要在 GitLab 帳戶中進行任何設定變更。

設定工作負載身分池，信任 GitLab 群組後，即可為個別 CI/CD 作業啟用 Workload Identity Federation。

Terraform Cloud

您不需要在 Terraform Cloud 帳戶中進行任何設定變更。

設定工作負載身分集區，讓 Terraform Cloud 信任該集區後，即可為個別工作區啟用 Workload Identity 聯盟。

設定 Workload Identity 聯盟

您必須為每個 GitHub 機構、GitLab 群組或 Terraform 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

定義屬性對應

部署管道的環境專屬憑證可以包含多個屬性，您必須決定要在 Google Cloud中將哪個屬性做為主體 ID (google.subject)。

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

Azure DevOps

Azure DevOps ID 權杖包含 sub 宣告，其中含有服務連線的主體 ID。主體 ID 採用下列格式：

sc://ORGANIZATION/PROJECT/CONNECTION

使用下列屬性對應，將這個 ID 對應至 google.subject：

google.subject=assertion.sub

GitHub Actions

屬性對應可以使用 GitHub Actions OIDC 權杖中的任何聲明。這些權杖聲明金鑰及其值由 GitHub 控制。您至少應將 google.subject 對應至 assertion.sub，這會對應至 GitHub Actions OIDC 權杖主體：

google.subject=assertion.sub

GitHub Actions OIDC 權杖主體的價值可能因來源事件而異。其他聲明屬性可能包括：

• repository：包含擁有者和存放區名稱，例如 "google/guava"。

• repository_id：包含專屬的存放區 ID，例如 "20300177"。

• repository_owner：包含擁有者，可以是使用者名稱或 GitHub 機構的名稱，例如 "google"。

• repository_owner_id：包含專屬擁有者 ID，例如 "1342004"。

這份清單是可能出現的聲明子集，如需完整清單，請參閱 GitHub 上的聲明範例文件。請務必對應您打算用做屬性條件或未來 principalSet 條件一部分的任何聲明。

這些欄位是專屬欄位，無法重複使用。

GitLab SaaS

屬性對應可使用嵌入 GitLab ID 權杖中的聲明做為來源屬性，包括：

• sub：專案名稱和 Git 參照，例如 project_path:groupname/projectname:ref_type:branch:ref:main。
• namespace_id：專屬群組 ID。
• project_id：專屬專案 ID。
• user_id：專屬使用者 ID。
• environment：工作適用的環境。
• ：Git 參照，例如 refs/heads/main。ref_path

下列屬性對應會將 google.subject 設為 GitLab ID 權杖中的 sub 聲明。由於 sub 聲明包含專案名稱和 Git 參照，因此您可以透過這項對應，依存放區和分支版本控管存取權：

google.subject=assertion.sub

如果特定分支 (例如 main) 需要與其他分支 (例如功能分支) 不同的資源存取權，依存放區和分支控管存取權就很有用。

在某些情況下，只要依專案或群組區分存取權就已足夠。因此，下列對應包含兩個額外屬性， 內含 GitLab project_id 和 namespace_id：

google.subject=assertion.sub
attribute.project_id=assertion.project_id
attribute.namespace_id=assertion.namespace_id

Terraform Cloud

屬性對應可使用 Terraform Cloud OIDC 權杖中內嵌的聲明，包括下列項目：

• terraform_organization_id：包含機構的專屬 ID，例如 org-xxxxxxxxxxxxxxxx。
• terraform_workspace_id：包含工作區的專屬 ID，例如 ws-xxxxxxxxxxxxxxxx。
• terraform_workspace_name：包含工作區的顯示名稱。
• sub：包含機構、工作區和階段的顯示名稱，例如 organization:example-org:workspace:example-workspace:run_phase:apply。

下列屬性對應會將 google.subject 設為 Terraform Cloud OIDC 權杖中的 terraform_workspace_id 聲明：

google.subject=assertion.terraform_workspace_id

透過這項對應，您可以依工作區控管 Google Cloud 資源的存取權。

定義屬性條件

屬性條件是 CEL 運算式，可檢查聲明屬性和目標屬性。如果屬性條件評估為 true，系統就會接受該憑證。否則系統會拒絕認證。你必須為所有屬性條件欄位建立屬性對應。

Azure DevOps

(選用) 使用屬性條件限制特定服務連線的存取權。舉例來說，下列條件會限制對特定 Azure DevOps 專案中連線的存取權：

assertion.sub.startsWith('sc://ORGANIZATION/PROJECT/')

更改下列內容：

• ORGANIZATION：Azure DevOps 機構的名稱。
• PROJECT：Azure DevOps 專案的名稱。

GitHub Actions

使用下列屬性條件，限制存取 GitHub 機構發行的權杖：

assertion.repository_owner=='ORGANIZATION'

將 ORGANIZATION 替換成 GitHub 機構的名稱。

您也可以選擇擴充屬性條件，限制存取部分工作流程或分支。舉例來說，下列條件會限制存取使用 Git 分支 main 的工作流程：

assertion.repository_owner=='ORGANIZATION' && assertion.ref=='refs/heads/main'

GitLab SaaS

使用下列屬性條件，限制存取 GitLab 群組發行的權杖

assertion.namespace_id=='GROUP_ID'

將 GROUP_ID 替換成 GitLab 群組首頁上顯示的群組 ID。

您也可以選擇擴充屬性條件，限制對部分專案、分支或環境的存取權。舉例來說，下列條件會限制只能存取使用 production 環境的工作：

assertion.namespace_id=='GROUP_ID' && assertion.environment=='production'

Terraform Cloud

使用下列屬性條件，限制存取 Terraform Cloud 機構發行的權杖：

assertion.terraform_organization_id=='ORGANIZATION_ID'

將 ORGANIZATION_ID 替換為貴機構的專屬 ID，例如 org-xxxxxxxxxxxxxxxx。您也可以選擇擴充屬性條件，限制存取部分工作流程或分支。舉例來說，下列屬性條件會限制對特定工作區的存取權：

assertion.terraform_organization_id=='ORGANIZATION_ID' && assertion.terraform_workspace_id=='WORKSPACE_ID'

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

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

主控台

1. 前往 Google Cloud 控制台的「New workload provider and pool」(新的工作負載供應商和集區) 頁面。

   前往「New workload provider and pool」(新增工作負載提供者和集區)

2. 在「建立身分集區」下方，輸入下列資訊：

   • 名稱：集區名稱。這個名稱也會用來做為集區 ID。 集區 ID 設定後即無法變更。
   • 說明：說明集區用途的文字。

3. 按一下「繼續」。

4. 設定提供者設定：

   Azure DevOps

   • 選取供應商：OpenID Connect (OIDC)。
   • 供應商名稱：Azure DevOps 專案的名稱，或自訂名稱。
   • 供應商 ID：Azure DevOps 專案的名稱或自訂 ID。供應商 ID 設定後即無法變更。
   • 簽發者網址：您先前查閱的服務連線簽發者。

   • 目標對象：選取「允許的目標對象」，然後貼上下列值

     api://AzureADTokenExchange
     

   GitHub Actions

   • 選取供應商：OpenID Connect (OIDC)。
   • 供應商名稱：供應商的名稱。
   • 提供者 ID：提供者的 ID。供應商 ID 設定後即無法變更。
   • 簽發者網址：https://token.actions.githubusercontent.com/
   • 目標對象：預設目標對象

   GitLab SaaS

   • 選取供應商：OpenID Connect (OIDC)。
   • 供應商名稱：供應商的名稱。
   • 提供者 ID：提供者的 ID。供應商 ID 設定後即無法變更。
   • 簽發者網址：https://gitlab.com
   • 目標對象：預設目標對象

   Terraform Cloud

   • 選取供應商：OpenID Connect (OIDC)。
   • 供應商名稱：供應商的名稱。
   • 提供者 ID：提供者的 ID。供應商 ID 設定後即無法變更。
   • 簽發者網址：https://app.terraform.io
   • 目標對象：預設目標對象

5. 按一下「繼續」。

6. 在「設定供應商屬性」下方，新增先前識別的屬性對應。

7. 在「屬性條件」下方，輸入先前識別的屬性條件。

8. 按一下「儲存」，建立 workload identity pool 和提供者。

gcloud

1. 建立新的 workload identity pool：

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   替換下列值：

   • POOL_ID：集區的專屬 ID
   • DISPLAY_NAME：集區名稱
   • DESCRIPTION：集區的說明。授予集區身分的存取權時會顯示這項說明

2. 新增工作負載身分集區提供者：

   Azure DevOps

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="ISSUER" \
       --allowed-audiences="api://AzureADTokenExchange" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   替換下列值：

   • PROVIDER_ID：Azure DevOps 專案的名稱，或是供應商的自訂 ID。
   • POOL_ID：集區的 ID
   • ISSUER：您先前查詢的服務連線簽發者。
   • MAPPINGS：以半形逗號分隔的屬性對應清單，這些屬性對應是您先前識別的
   • CONDITIONS：先前識別的屬性條件

   GitHub Actions

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://token.actions.githubusercontent.com/" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   替換下列值：

   • PROVIDER_ID：供應商的專屬 ID
   • POOL_ID：集區的 ID
   • MAPPINGS：以半形逗號分隔的屬性對應清單，這些屬性對應是您先前識別的
   • CONDITIONS：先前識別的屬性條件

   GitLab SaaS

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://gitlab.com" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   替換下列值：

   • PROVIDER_ID：供應商的專屬 ID
   • POOL_ID：集區的 ID
   • MAPPINGS：以半形逗號分隔的屬性對應清單，這些屬性對應是您先前識別的
   • CONDITIONS：先前識別的屬性條件

   Terraform Cloud

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://app.terraform.io" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   替換下列值：

   • PROVIDER_ID：供應商的專屬 ID。
   • POOL_ID：集區的 ID。
   • MAPPINGS：以半形逗號分隔的屬性對應清單 (先前已識別)。
   • CONDITIONS：您先前識別的屬性條件。

更新 Workload Identity 提供者的屬性條件

本節說明如何更新現有工作負載身分集區供應商的屬性條件，限制對 GitHub 機構、GitLab 群組或 Terraform Cloud 機構核發的權杖存取權。

如要找出管道的建議屬性條件，請參閱「定義屬性條件」。

主控台

1. 前往 Google Cloud 控制台的「Workload Identity Pools」頁面。

   前往「Workload Identity Pools」(工作負載身分集區)

2. 找出含有供應商的 workload identity pool，然後點選該 pool 的「展開節點」arrow_right圖示。

3. 找出要編輯的 workload identity pool 提供者，然後按一下 edit「編輯」。

4. 在「屬性條件」中，輸入您先前識別的屬性條件。

5. 如要更新 workload identity pool 和提供者，請按一下「儲存」。

gcloud

如要更新工作負載身分集區提供者，請執行下列指令：

gcloud iam workload-identity-pools providers update-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --attribute-condition="CONDITIONS"

替換下列值：

• PROVIDER_ID：供應商的專屬 ID
• POOL_ID：集區的 ID
• CONDITIONS：先前識別的屬性條件

驗證部署管道

您必須為每個 GitHub Actions 工作流程或 Terraform Cloud 工作區執行這些步驟。

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

如要完成本指南稍後的指示，您必須按照本節說明設定服務帳戶模擬。

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

直接存取資源

您可以使用 Google Cloud 控制台或 gcloud CLI，直接在資源上授予聯盟身分存取權。

控制台

如要使用 Google Cloud 控制台直接在資源上授予 IAM 角色，請前往資源頁面，然後授予角色。下列範例說明如何前往 Cloud Storage 頁面，並直接在 Cloud Storage bucket 上，將「Storage 物件檢視者」(roles/storage.objectViewer) 角色授予同盟身分。

1. 在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。
   

   前往「Buckets」(值區) 頁面

2. 在 bucket 清單中，點選要授予角色的 bucket 名稱。

3. 選取靠近頁面上方的 [Permissions] (權限) 分頁標籤。

4. 按一下「授予存取權」add_box按鈕。

   系統會顯示「新增主體」對話方塊。

5. 在「New principals」(新增主體) 欄位中，輸入需要存取值區的一或多個身分。

   依科目

   principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
   

   更改下列內容：

   • PROJECT_NUMBER：專案編號
   • POOL_ID：工作負載集區 ID
   • SUBJECT：從 IdP 對應的個別主體，例如 administrator@example.com

   依群組

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

   更改下列內容：

   • PROJECT_NUMBER：專案編號
   • WORKLOAD_POOL_ID：工作負載集區 ID
   • ：從 IdP 對應的群組，例如： administrator-group@example.comGROUP

   依屬性

   principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
   

   更改下列內容：

   • PROJECT_NUMBER：專案編號
   • WORKLOAD_POOL_ID：工作負載集區 ID
   • ATTRIBUTE_NAME：從 IdP 對應的其中一個屬性
   • ATTRIBUTE_VALUE：屬性的值

6. 從「Select a role」(請選取角色) 下拉式選單中選取一或多個角色。您選取的角色會顯示在面板中，系統還會針對這些角色所授予的權限提供簡短說明。

7. 按一下 [儲存]。

gcloud

如要使用 gcloud CLI 授予專案中資源的 IAM 角色，請執行下列操作：

1. 取得定義資源的專案編號。

   gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
   

2. 授予資源存取權。

   如要使用 gcloud CLI 將 Storage 物件檢視者 (roles/storage.objectViewer) 角色授予符合特定條件的外部身分，請執行下列指令。

   依科目

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

   依群組

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

   依屬性

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

   更改下列內容：

   • BUCKET_ID：要授予存取權的值區
   • PROJECT_NUMBER：含有 workload identity pool 的專案專案編號。
   • POOL_ID：工作負載身分集區的集區 ID
   • SUBJECT：您已對應至 google.subject 的屬性預期值
   • GROUP：您已對應至 google.groups 的屬性預期值
   • ATTRIBUTE_NAME：屬性對應中的自訂屬性名稱
   • ATTRIBUTE_VALUE：屬性對應中自訂屬性的值

   您可以在任何支援 IAM 允許政策的 Google Cloud 資源上授予角色。

服務帳戶模擬

1. 如要為外部工作負載建立服務帳戶，請按照下列步驟操作：

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

      Enable the APIs

   2. 建立服務帳戶，代表工作負載。建議您為每個工作負載使用專屬服務帳戶。服務帳戶不必與工作負載身分集區位於同一專案，但您必須參照包含服務帳戶的專案。

   3. 授予服務帳戶存取權，允許外部身分存取資源。

2. 如要允許聯合身分模擬服務帳戶，請執行下列操作：

控制台

如要使用 Google Cloud 控制台，將 IAM 角色授予具有服務帳戶的同盟身分，請按照下列步驟操作：

同一專案中的服務帳戶

1. 如要使用服務帳戶模擬功能，為同一專案中的服務帳戶授予存取權，請執行下列步驟：

   1. 前往「Workload Identity Pools」(工作負載身分集區) 頁面。

      前往「Workload Identity Pools」(工作負載身分集區)

   2. 選取「授予存取權」。

   3. 在「授予服務帳戶存取權」對話方塊中，選取「透過服務帳戶模擬功能授予存取權」。

   4. 在「服務帳戶」清單中，選取要讓外部身分模擬的服務帳戶，然後執行下列操作：

   5. 如要選擇集區中的哪些身分可以模擬服務帳戶，請執行下列其中一項操作：

      • 如要只允許工作負載身分識別集區的特定身分模擬服務帳戶，請選取「只顯示符合篩選條件的身分」。

      • 在「屬性名稱」清單中，選取要篩選的屬性。

      • 在「屬性值」欄位中，輸入屬性的預期值；舉例來說，如果您使用屬性對應 google.subject=assertion.sub，請將「屬性」名稱設為 subject，並將「屬性值」設為外部身分識別提供者核發的權杖中 sub 聲明的值。

   6. 如要儲存設定，請依序按一下「儲存」和「關閉」。

其他專案中的服務帳戶

1. 如要使用服務帳戶模擬功能，為其他專案中的服務帳戶授予存取權，請按照下列步驟操作：

   1. 前往「Service Accounts」(服務帳戶) 頁面

      前往「Service Accounts」(服務帳戶) 頁面

   2. 選取要模擬的服務帳戶。

   3. 按一下「管理存取權」。

   4. 按一下「新增主體」。

   5. 在「New principal」(新增主體) 欄位中，輸入下列其中一個主體 ID，以指定集區中的身分，這些身分將模擬服務帳戶。

      依科目

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
      

      更改下列內容：

      • PROJECT_NUMBER：專案編號
      • POOL_ID：工作負載集區 ID
      • SUBJECT：從 IdP 對應的個別主體，例如 administrator@example.com

      依群組

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

      更改下列內容：

      • PROJECT_NUMBER：專案編號
      • WORKLOAD_POOL_ID：工作負載集區 ID
      • ：從 IdP 對應的群組，例如： administrator-group@example.comGROUP

      依屬性

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
      

      更改下列內容：

      • PROJECT_NUMBER：專案編號
      • WORKLOAD_POOL_ID：工作負載集區 ID
      • ATTRIBUTE_NAME：從 IdP 對應的其中一個屬性
      • ATTRIBUTE_VALUE：屬性的值

      依集區

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

      更改下列內容：

      • PROJECT_NUMBER：專案編號
      • WORKLOAD_POOL_ID：工作負載集區 ID

   6. 在「Select a role」(選取角色) 欄位，選取 Workload Identity User 角色 (roles/iam.workloadIdentityUser)。

   7. 如要儲存設定，請按一下「儲存」。

gcloud

如要將 Workload Identity 使用者角色 (roles/iam.workloadIdentityUser) 授予已同盟主體或主體集，請執行下列指令。如要進一步瞭解 Workload Identity 聯盟主體 ID，請參閱「主體類型」。

依科目

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"

更改下列內容：

• SERVICE_ACCOUNT_EMAIL： 服務帳戶的電子郵件地址
• PROJECT_NUMBER：含有 workload identity pool 的專案專案編號。
• POOL_ID：工作負載身分集區的集區 ID
• SUBJECT：您已對應至 google.subject 的屬性預期值
• GROUP：您已對應至 google.groups 的屬性預期值
• ATTRIBUTE_NAME：屬性對應中的自訂屬性名稱
• ATTRIBUTE_VALUE：屬性對應中自訂屬性的值

設定部署管道

本節說明如何在部署管道中使用 Workload Identity 聯盟。本節中的操作說明假設工作負載使用服務帳戶模擬來存取 Google Cloud資源。

Azure DevOps

編輯 azure-pipelines.yml 檔案，並在工作設定中新增下列項目：

variables:
- name: Azure.WorkloadIdentity.Connection
  value: CONNECTION
- name: GoogleCloud.WorkloadIdentity.ProjectNumber
  value: PROJECT_NUMBER
- name: GoogleCloud.WorkloadIdentity.Pool
  value: POOL_ID
- name: GoogleCloud.WorkloadIdentity.Provider
  value: PROVIDER_ID
- name: GoogleCloud.WorkloadIdentity.ServiceAccount
  value: SERVICE_ACCOUNT_EMAIL
- name: GOOGLE_APPLICATION_CREDENTIALS
  value: $(Pipeline.Workspace)/.workload_identity.wlconfig

steps:
  - task: AzureCLI@2
    inputs:
      connectedServiceNameARM: $(Azure.WorkloadIdentity.Connection)
      addSpnToEnvironment: true
      scriptType: 'bash'
      scriptLocation: 'inlineScript'
      inlineScript: |
        echo $idToken > $(Pipeline.Workspace)/.workload_identity.jwt
        cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
        {
          "type": "external_account",
          "audience": "//iam.googleapis.com/projects/$(GoogleCloud.WorkloadIdentity.ProjectNumber)/locations/global/workloadIdentityPools/$(GoogleCloud.WorkloadIdentity.Pool)/providers/$(GoogleCloud.WorkloadIdentity.Provider)",
          "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
          "token_url": "https://sts.googleapis.com/v1/token",
          "credential_source": {
            "file": "$(Pipeline.Workspace)/.workload_identity.jwt"
          },
          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$(GoogleCloud.WorkloadIdentity.ServiceAccount):generateAccessToken"
        }
        EOF

替換下列值：

• CONNECTION：服務連線的名稱。
• PROJECT_NUMBER：包含 workload identity pool 的專案專案編號。
• POOL_ID：工作負載身分集區的 ID。
• PROVIDER_ID：Workload Identity Pool 提供者的 ID。
• SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址 (如果您使用服務帳戶模擬)。如果您使用直接資源存取權，請省略 GoogleCloud.WorkloadIdentity.ServiceAccount 和 service_account_impersonation_url。

這項設定會執行下列操作：

1. 使用 AzureCLI 工作取得服務連線的 ID 權杖，並在名為 idToken 的變數中提供該權杖。
2. 將 ID 權杖儲存至名為 .workload_identity.jwt 的暫存檔案。
3. 建立憑證設定檔，指示用戶端程式庫從 .workload_identity.jwt 讀取 ID 權杖，並使用該權杖模擬服務帳戶。
4. 設定環境變數 GOOGLE_APPLICATION_CREDENTIALS，指向憑證設定檔。

GitHub Actions

google-github-actions/auth 動作可讓您在工作流程執行期間，自動產生憑證設定檔。用戶端程式庫和 terraform 等工具隨後可以使用這個憑證設定檔，自動取得 Google 憑證。

編輯 GitHub Actions YAML 檔案，並新增下列內容：

• 新增下列設定，允許作業擷取 GitHub ID 權杖：

  permissions:
    id-token: write
    contents: read
  

• 新增建立憑證設定檔的步驟：

  - id: 'auth'
    name: 'Authenticate to Google Cloud'
    uses: 'google-github-actions/auth@v1'
    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 的專案專案編號。
• POOL_ID：工作負載身分集區的 ID。
• PROVIDER_ID：workload identity pool 提供者的 ID。
• SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址 (如果您使用服務帳戶模擬功能)。如果您使用直接資源存取權，請省略 service_account。

以下範例會設定 GitHub 動作：

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@v3

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

如要進一步瞭解如何使用 google-github-actions/auth 動作，請參閱「設定 Workload Identity 聯盟」。

GitLab SaaS

編輯 .gitlab-ci.yml 檔案，並在作業設定中新增下列項目：

job:
  variables:
    WORKLOAD_IDENTITY_PROJECT_NUMBER: PROJECT_NUMBER
    WORKLOAD_IDENTITY_POOL: POOL_ID
    WORKLOAD_IDENTITY_PROVIDER: PROVIDER_ID
    SERVICE_ACCOUNT: SERVICE_ACCOUNT_EMAIL
    GOOGLE_APPLICATION_CREDENTIALS: $CI_BUILDS_DIR/.workload_identity.wlconfig

  id_tokens:
    WORKLOAD_IDENTITY_TOKEN:
      aud: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

  script:
    - |-
      echo $WORKLOAD_IDENTITY_TOKEN > $CI_BUILDS_DIR/.workload_identity.jwt
      cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/projects/$WORKLOAD_IDENTITY_PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_IDENTITY_POOL/providers/$WORKLOAD_IDENTITY_PROVIDER",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "$CI_BUILDS_DIR/.workload_identity.jwt"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SERVICE_ACCOUNT:generateAccessToken"
      }
      EOF

替換下列值：

• PROJECT_NUMBER：含有 workload identity pool 的專案專案編號。
• POOL_ID：工作負載身分集區的 ID。
• PROVIDER_ID：Workload Identity Pool 提供者的 ID。
• SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址 (如果您使用服務帳戶模擬)。如果您使用直接資源存取權，請省略 SERVICE_ACCOUNT 和 service_account_impersonation_url。

這項設定會執行下列操作：

1. 指示 GitLab 發行 ID 權杖，並在名為 WORKLOAD_IDENTITY_TOKEN 的環境變數中提供該權杖。ID 權杖會將工作負載身分集區提供者做為對象。
2. 將 ID 權杖儲存至名為 .workload_identity.jwt 的暫存檔案。
3. 建立憑證設定檔，指示用戶端程式庫從 .workload_identity.jwt 讀取 ID 權杖，並用來模擬服務帳戶。
4. 設定環境變數 GOOGLE_APPLICATION_CREDENTIALS，指向憑證設定檔。

Terraform Cloud

設定 Terraform Cloud 工作區，讓該工作區使用 Workload Identity Federation 向 Google Cloud 進行驗證，方法是模擬服務帳戶：

1. 在 Terraform Cloud 中開啟工作區，然後前往「變數」。

2. 新增下列變數：

   變數類別	鍵	值
   環境變數	TFC_GCP_PROVIDER_AUTH	true
   環境變數	TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL	如果您使用服務帳戶模擬功能，請輸入服務帳戶的電子郵件地址，例如 terraform@my-project-123.iam.gserviceaccount.com。如果您使用直接資源存取權，請省略這個環境變數。
   環境變數	TFC_GCP_PROJECT_NUMBER	包含工作負載身分集區的專案編號
   環境變數	TFC_GCP_WORKLOAD_POOL_ID	Workload Identity 集區的 ID
   環境變數	TFC_GCP_WORKLOAD_PROVIDER_ID	工作負載身分集區提供者的 ID

   如果您使用服務帳戶模擬，可以視需要新增其他環境變數，讓 Terraform Cloud 在 plan 和 apply 階段使用不同的服務帳戶。如要進一步瞭解如何在 Terraform 設定中使用環境變數，請參閱「選用環境變數」。

3. 在變數清單中，確認您在上一步驟中新增的五個變數，「類別」都設為 env。

4. 確認 Terraform 設定使用 4.48.0 或更新版本的供應程式，並視需要更新，方法如下： Google Cloud

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

5. 將變更提交至原始碼存放區。

後續步驟

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