配置使用部署流水线的工作负载身份联合

本指南介绍了如何使用工作负载身份联合，让部署流水线向 Google Cloud 进行身份验证。

根据您使用的 CI/CD 系统，您的部署流水线可能会访问特定于环境的环境凭据。例如：

Azure DevOps 流水线可以使用 Microsoft Entra 工作负载身份联合服务连接来获取唯一标识 Azure DevOps 项目的 ID 令牌。
GitHub Actions 工作流可以获取 GitHub OIDC 令牌以唯一标识工作流及其代码库。
借助 GitLab SaaS，CI/CD 作业可以访问 ID 令牌，以唯一标识作业及其项目、环境和存储库。
Terraform Cloud 可以向您的 Terraform 配置提供 OIDC 令牌以唯一标识工作区和环境。

您可以将部署流水线配置为使用这些凭据通过工作负载身份联合向 Google Cloud 进行身份验证。此方法可消除与服务账号密钥相关的维护和安全负担。

准备工作

设置身份验证

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，然后使用您的用户凭据设置应用默认凭据。

Install the Google Cloud CLI.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
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.

如需了解详情，请参阅 Google Cloud 身份验证文档中的为本地开发环境设置身份验证。

所需的角色

如需获得配置工作负载身份联合所需的权限，请让您的管理员为您授予项目的 Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

此外，IAM Owner (roles/owner) 基本角色还具有配置身份联合的权限。您不应在生产环境中授予基本角色，但可以在开发或测试环境中授予这些角色。

准备外部 IdP

Azure DevOps

如需让 Azure DevOps 流水线向 Google Cloud 进行身份验证，您首先需要为 Azure Resource Manager 配置服务连接。此连接可让流水线获取 ID 令牌，然后该令牌可以交换为 Google Cloud 凭据。

如需为 Azure Resource Manager 创建服务连接，请执行以下操作：

在 Azure DevOps 中，打开您的项目，然后前往 Project Settings。
依次点击 Pipelines > Service connections。
点击 Create service connection。
选择 Azure Resource Manager。
点击下一步。
选择 Workload Identity federation (automatic)
点击下一步。
进行以下设置：
- Scope level：选择一个订阅。
  
  即使您不打算使用服务连接来访问 Azure 资源，也必须选择订阅。
- Service connection name：输入一个名称，例如 google-cloud。
点击保存。

在稍后的步骤中，您需要使用服务连接的颁发者和主体标识符。如需查找这些详细信息，请执行以下操作：

点击您刚刚创建的服务连接。
点击 Manage Service Principal。
依次点击 Certificate & secrets > Federated credentials。
点击联合凭据。
在 Edit a credential 页面上，找到以下标识符：
- Issuer：唯一标识 Azure DevOps 组织
- Subject identifier：唯一标识服务连接

Azure DevOps 会自动向与新服务连接关联的服务主账号授予您选择作为范围的订阅的访问权限。由于您不打算使用服务连接来访问 Azure 资源，因此可以通过执行以下操作来撤消此访问权限：

在 Azure 门户中，打开您选择作为范围的订阅。
依次点击 Access control (IAM) > Role assignments。
找到服务连接的角色分配，然后将其移除。

GitHub Actions

您无需在 GitHub 账号中进行任何更改。

将工作负载身份池配置为信任您的 GitHub 代码库后，您可以让该代码库中的工作流使用其 GitHub OIDC 令牌来获取短期 Google Cloud 凭据。

GitLab SaaS

您无需在 GitLab 账号中进行任何更改。

将工作负载身份池配置为信任您的 GitLab 群组后，您可以为各个 CI/CD 作业启用工作负载身份联合。

Terraform Cloud

您无需在 Terraform Cloud 账号中进行任何更改配置。

将工作负载身份池配置为信任 Terraform Cloud 后，您可以为各个工作区启用工作负载身份联合。

配置工作负载身份联合

您必须为每个 GitHub 组织、GitLab 群组或 Terraform Cloud 组织执行这些步骤。

如需开始配置工作负载身份联合，请执行以下操作：

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

Go to project selector

使用专用项目来管理工作负载身份池和提供方

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 中用作主体标识符 (google.subject) 的属性。

您也可以视需要映射其他特性。然后，您可以在授予对资源的访问权限时引用这些附加属性。

Azure DevOps

Azure DevOps ID 令牌包括 sub 声明，其中包含服务连接的主体标识符。主体标识符使用以下格式：

sc://ORGANIZATION/PROJECT/CONNECTION

使用以下属性映射将此标识符映射到 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：作业适用的环境。
ref_path：Git 引用，例如 refs/heads/main。

以下属性映射会将 GitLab ID 令牌中的 google.subject 设置为 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。

以下属性映射会将 Terraform Cloud OIDC 令牌中的 google.subject 设置为 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'

创建工作负载身份池和提供方

现在，您已经收集了创建工作负载身份池和提供商所需的全部信息：

控制台

在 Google Cloud 控制台中，前往新建工作负载提供方和池页面。

转到“新建工作负载提供商和池”
在创建身份池下，输入以下内容：
- 名称：池的名称。该名称还用作池 ID。池 ID 创建后便无法更改。
- 说明：描述池用途的文本。
点击继续。
配置提供方设置：
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
- 受众群体：默认受众群体
点击继续。
在配置提供商特性下，添加您之前识别的特性映射。
在属性条件下，输入您之前确定的属性条件。
点击保存以创建工作负载身份池和提供方。

gcloud

创建新的工作负载身份池：
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
替换以下值：
- POOL_ID：池的唯一 ID
- DISPLAY_NAME：池的名称
- DESCRIPTION：池的说明。授予对池身份的访问权限时，系统会显示此说明

添加工作负载身份池提供商：

Azure DevOps

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --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/" \
    --allowed-audiences="api://AzureADTokenExchange" \
    --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：您之前确定的属性条件。

更新工作负载身份提供方的属性条件

本部分介绍了如何更新现有工作负载身份池提供方的属性条件，以限制对 GitHub 组织、GitLab 群组或 Terraform Cloud 组织颁发的令牌的访问权限。

如需找到建议用于流水线的属性条件，请参阅定义属性条件。

控制台

在 Google Cloud 控制台中，进入工作负载身份池页面。

转到“工作负载身份池”
找到包含提供方的工作负载身份池，然后点击池对应的 展开节点图标。
找到您要修改的工作负载身份池提供方，然后点击修改。
在属性条件中，输入您之前确定的属性条件。
如需更新工作负载身份池和提供方，请点击保存。

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 存储桶的 Storage Object Viewer (roles/storage.objectViewer) 角色。

在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
进入“存储桶”
在存储桶列表中，点击您要针对其授予角色的存储桶的名称。
选择页面顶部附近的权限标签。
点击 授予访问权限按钮。

系统会显示“添加主账号”对话框。
在新主账号字段中，输入需要访问您存储桶的一个或多个身份。
按主体
```
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
- GROUP：从您的 IdP 映射的群组，例如：administrator-group@example.com
按特性
```
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：属性的值
从选择角色下拉菜单中选择一个或多个角色。您选择的角色将显示在窗格中，其中包含对角色授予的权限的简短说明。
点击保存。

gcloud

如需使用 gcloud CLI 针对项目中的资源授予 IAM 角色，请执行以下操作：

获取定义资源的项目的编号。

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

授予对资源的访问权限。

如需使用 gcloud CLI 向符合特定条件的外部身份授予 Storage Object Viewer 角色 (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：包含工作负载身份池的项目的编号
- POOL_ID：工作负载身份池的池 ID
- SUBJECT：已映射到 google.subject 的特性的预期值
- GROUP：已映射到 google.groups 的特性的预期值
- ATTRIBUTE_NAME：特性映射中的自定义特性的名称
- ATTRIBUTE_VALUE：属性映射中的自定义属性的值
您可以向支持 IAM 允许政策的任何 Google Cloud 资源授予角色。

注意：您必须在成员标识符中使用项目编号，而不是项目 ID。

服务账号模拟

如需为外部工作负载创建服务账号，请执行以下操作：
1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
  Enable the APIs
2. 创建一个服务账号以代表工作负载。我们建议您为每个工作负载使用专用服务账号。该服务账号不需要与工作负载身份池位于同一项目中，但您必须引用包含该服务账号的项目。
3. 向服务账号授予对您希望外部身份访问的资源的访问权限。
4. 向服务账号授予 Workload Identity User 角色 (roles/iam.workloadIdentityUser)。
如需使用 Google Cloud 控制台或 gcloud CLI 通过服务账号模拟向联合身份授予访问权限，请执行以下操作：

控制台

如需使用 Google Cloud 控制台向具有服务账号的联合身份授予 IAM 角色，请执行以下操作：

同一项目中的服务账号

如需使用服务账号模拟为同一项目中的服务账号授予访问权限，请执行以下操作：
1. 进入工作负载身份池页面。
  
  转到“工作负载身份池”
2. 选择授予访问权限。
3. 在向服务账号授予访问权限对话框中，选择使用服务账号模拟授予访问权限。
4. 在服务账号列表中，选择要模拟的外部身份的服务账号，然后执行以下操作：
5. 如需选择池中的哪些身份可以模拟服务账号，请执行以下操作之一：
  - 如需仅允许工作负载身份池的特定身份模拟服务账号，请选择仅限与过滤条件匹配的身份。
  - 在属性名称列表中，选择您要作为过滤依据的属性。
  - 在属性值字段中，输入属性的预期值；例如，如果您使用属性映射 google.subject=assertion.sub，请将属性名称设置为 subject，并将属性值设置为外部身份提供方颁发的令牌中 sub 声明的值。
6. 如需保存配置，请点击保存，然后点击关闭。

另一个项目中的服务账号

如需向其他项目中的服务账号授予使用服务账号模拟的访问权限，请执行以下操作：
1. 转到服务账号页面。
  
  转到“服务账号”
2. 选择要模拟的服务账号。
3. 点击管理访问权限。
4. 点击添加主账号。
5. 在新主账号字段中，为要模拟服务账号的池中的身份输入以下主账号标识符之一。
  按主体
  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
  - GROUP：从您的 IdP 映射的群组，例如：administrator-group@example.com
  按特性
  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. 在选择角色中，选择 Workload Identity User 角色 (roles/iam.workloadIdentityUser)。
7. 如需保存配置，请点击保存。

gcloud

如需使用 gcloud CLI 向符合特定条件的外部身份授予 Workload Identity User 角色 (roles/iam.workloadIdentityUser)，请运行以下命令。

按主体

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：包含工作负载身份池的项目的编号
POOL_ID：工作负载身份池的池 ID
SUBJECT：已映射到 google.subject 的特性的预期值
GROUP：已映射到 google.groups 的特性的预期值
ATTRIBUTE_NAME：特性映射中的自定义特性的名称
ATTRIBUTE_VALUE：属性映射中的自定义属性的值

配置部署流水线

本部分介绍了如何在部署流水线中使用工作负载身份联合。本部分中的说明假定您的工作负载使用服务账号模拟来访问 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：包含工作负载身份池的项目的编号
POOL_ID：工作负载身份池的 ID
PROVIDER_ID：工作负载身份池提供方的 ID
SERVICE_ACCOUNT_EMAIL：服务账号的电子邮件地址

该配置会执行以下操作：

使用 AzureCLI 任务获取服务连接的 ID 令牌，并在名为 idToken 的变量中提供。
将 ID 令牌保存到名为 .workload_identity.jwt 的临时文件中。
创建凭据配置文件，指示客户端库从 .workload_identity.jwt 读取 ID 令牌，并使用该令牌来模拟服务账号。
将环境变量 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：包含工作负载身份池的项目的编号。
POOL_ID：工作负载身份池的 ID。
PROVIDER_ID：工作负载身份池提供方的 ID。
SERVICE_ACCOUNT_EMAIL：替换为服务账号的电子邮件地址。

以下示例会配置 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 操作，请参阅设置工作负载身份联合。

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：包含工作负载身份池的项目的编号
POOL_ID：工作负载身份池的 ID
PROVIDER_ID：工作负载身份池提供方的 ID
SERVICE_ACCOUNT_EMAIL：服务账号的电子邮件地址

该配置会执行以下操作：

指示 GitLab 发出 ID 令牌，并在名为 WORKLOAD_IDENTITY_TOKEN 的环境变量中提供该令牌。ID 令牌使用工作负载身份池提供方作为受众群体。
将 ID 令牌保存到名为 .workload_identity.jwt 的临时文件中。
创建凭据配置文件，指示客户端库从 .workload_identity.jwt 读取 ID 令牌，并使用该令牌来模拟服务账号。
将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为指向凭据配置文件。

Terraform Cloud

配置您的 Terraform Cloud 工作区，以便它使用 Workload Identity 联合身份验证来使用服务账号模拟功能向 Google Cloud 进行身份验证：

在 Terraform Cloud 中，打开工作区，然后转至变量。

添加以下变量：

变量类别	键	值
环境变量	`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`	工作负载身份池的 ID
环境变量	`TFC_GCP_WORKLOAD_PROVIDER_ID`	工作负载身份池提供方的 ID

您可以选择添加其他环境变量，以便让 Terraform Cloud 在 plan 和 apply 阶段使用不同的服务账号。如需了解详情，请参阅可选环境变量。

在变量列表中，验证您在上一步中添加的五个变量的类别是否设置为 env。
验证 Terraform 配置是否使用 4.48.0 或更高版本的 Google Cloud 提供程序，并根据需要进行更新，如下所示：
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.48.0"
    }
  }
}
```
将更改提交到您的源代码库。

配置使用部署流水线的工作负载身份联合

准备工作

设置身份验证

Console

gcloud

Python

所需的角色

准备外部 IdP

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

配置工作负载身份联合

定义属性映射

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

定义属性条件

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

创建工作负载身份池和提供方

控制台

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

gcloud

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

更新工作负载身份提供方的属性条件

控制台

gcloud

对部署流水线进行身份验证

允许外部工作负载访问 Google Cloud 资源

直接资源访问权限

控制台

按主体

按群组

按特性

gcloud

按主体

按群组

按属性

服务账号模拟

控制台

同一项目中的服务账号

另一个项目中的服务账号

按主体

按群组

按特性

按池

gcloud

按主体

按群组

按属性

配置部署流水线

Azure DevOps

GitHub Actions

GitLab SaaS

Terraform Cloud

后续步骤