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

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

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

GitHub Actions 工作流可以获取 GitHub OIDC 令牌以唯一标识工作流及其代码库。
Terraform Cloud 可以向您的 Terraform 配置提供 OIDC 令牌以唯一标识工作区和环境。

通过使用工作负载身份联合，您可以避免存储和管理服务帐号密钥，让部署流水线使用其特定于环境的凭据来访问 Google Cloud API。

准备外部 IdP

GitHub Actions

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

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

Terraform Cloud

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

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

配置工作负载身份联合

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

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

在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

转到“项目选择器”

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

确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

启用 IAM, Resource Manager, Service Account Credentials, and Security Token Service API。

启用 API

定义特性映射和条件

部署流水线的特定于环境的凭据包含多个特性，您必须决定要在 Google Cloud 中用作主体标识符 (google.subject) 的特性。

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

GitHub Actions

您的特性映射可以使用在 OIDC 令牌中嵌入的声明作为来源特性，其中包括：

sub：包含代码库名称和 Git 参考，例如 repo:username/reponame:ref:refs/heads/master。
repository：包含所有者和代码库名称，例如 username/reponame。
repository_owner：包含所有者，可以是用户名或 GitHub 组织的名称。
ref：包含 Git 参考，例如 refs/heads/main。

以下特性映射会将 GitHub Actions OIDC 令牌中的 google.subject 设置为 sub 声明。由于 sub 声明同时包含代码库名称和 Git 参考，因此该映射可让您按代码库和分支控制访问权限：

google.subject=assertion.sub

如果某些分支（例如 main）需要与其他分支不同的资源访问权限（例如功能分支），则按代码库和分支控制访问权限非常有用。

如果您不打算按分支区分访问权限，则可以使用以下特性映射，将 google.subject 设置为 repository 声明：

google.subject=assertion.repository

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，则接受凭据。否则，凭据会被拒绝。

GitHub Actions

使用以下条件来限制对 GitHub 组织颁发的令牌的访问权限：

assertion.repository_owner=='ORGANIZATION'

将 ORGANIZATION 替换为您的 GitHub 组织名称。

（可选）扩展特性条件，以限制对部分工作流或分支的访问权限。例如，以下条件限制了对使用 Git 分支 main 的工作流的访问权限：

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

Terraform Cloud

使用以下条件来限制对 Terraform Cloud 组织颁发的令牌的访问权限：

assertion.terraform_organization_id=='ORGANIZATION_ID'

将 ORGANIZATION_ID 替换为您的组织的唯一 ID，例如 org-xxxxxxxxxxxxxxxx。（可选）扩展特性条件，以限制对部分工作流或分支的访问权限。例如，以下条件限制对特定工作区的访问权限：

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

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

所需的角色

如需获得配置工作负载身份联合所需的权限，请让管理员向您授予项目的以下 IAM 角色：

Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
Service Account Admin (roles/iam.serviceAccountAdmin)

如需详细了解如何授予角色，请参阅管理访问权限。

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

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

控制台

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

转到“新建工作负载提供商和池”
在创建身份池下，输入以下内容：
- 名称：池的名称。该名称还用作池 ID。池 ID 创建后便无法更改。
- 说明：描述池用途的文本。
点击继续。
配置提供方设置：
GitHub Actions
- 选择提供方：OpenID Connect (OIDC)。
- 提供方名称：提供方的名称。该名称还用作提供方 ID。提供商 ID 创建后便无法更改。
- 颁发者网址：https://token.actions.githubusercontent.com/
- 受众群体：默认受众群体
Terraform Cloud
- 选择提供方：OpenID Connect (OIDC)。
- 提供方名称：提供方的名称。该名称还用作提供方 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：池的说明。授予对池身份的访问权限时，系统会显示此说明。
添加工作负载身份池提供商：
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：您之前确定的特性条件。如果您没有特性条件，请移除该参数。
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 Actions 工作流或 Terraform Cloud 工作区执行这些步骤。

为部署流水线创建服务帐号

启用 IAM, Security Token Service, and Service Account Credentials API。
启用 API
创建一个服务帐号以代表工作负载。我们建议您为每个部署流水线使用专用服务帐号。

该服务帐号不需要与工作负载身份池位于同一项目中。
向服务帐号授予对您希望外部身份访问的资源的访问权限。

允许部署流水线模拟服务帐号

如需允许外部身份模拟服务帐号，请向其授予服务帐号的 Workload Identity User 角色 (roles/iam.workloadIdentityUser)。您可以向特定外部身份或多个外部身份授予该角色：

对于特定的外部身份，请编写一个检查 google.subject 特性的特性条件。
对于一组外部身份，编写一个检查 google.groups 特性或自定义属性 attribute.NAME 的特性条件。
对于工作负载身份池中的所有外部身份，您不使用特性条件。

控制台

如需使用 Google Cloud 控制台允许外部身份模拟服务帐号，请执行以下操作：

在 Google Cloud 控制台中，转到 Workload Identity 池页面。

转到“工作负载身份池”
找到您要更新的工作负载身份池并选择它。
如需授予对所选工作负载身份池的访问权限，请点击 授予访问权限。
在服务帐号列表中，选择您要模拟的外部身份的服务帐号。
如需选择池中的哪些身份可以模拟服务帐号，请执行以下某项操作：
- 如需仅允许工作负载身份池的特定身份来模拟服务帐号，请选择仅限与过滤条件匹配的身份。
  
  在特性名称列表中，选择过滤根据的特性。
  
  在特性值字段中，输入特性的预期值；例如，如果您使用特性映射 google.subject=assertion.sub，请将特性名称设置为 subject，并将特性值设置为外部身份提供方颁发的令牌中 sub 声明的值。
- 若要允许工作负载身份池的所有外部身份模拟服务帐号，请选择池中的所有身份。
如需保存配置，请点击保存，然后点击关闭。

gcloud

如需使用 gcloud CLI 允许外部身份模拟服务帐号，请执行以下操作：

如需获取当前项目的编号，请执行以下命令：

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

如需向符合特定条件的外部身份授予 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"

所有外部身份

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/*"

请替换以下内容：

SERVICE_ACCOUNT_EMAIL：服务帐号的电子邮件地址
PROJECT_NUMBER：包含工作负载身份池的项目的编号
POOL_ID：工作负载身份池的池 ID
SUBJECT：已映射到 google.subject 的特性的预期值
GROUP：已映射到 google.groups 的特性的预期值
ATTRIBUTE_NAME：特性映射中的自定义特性的名称

配置部署流水线

您现在可以在部署流水线中使用工作负载身份联合了。

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@v0'
  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：服务帐号的电子邮件地址

示例：

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'
        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 操作，请参阅设置工作负载身份联合。

Terraform Cloud

配置工作区，以便配置可以获取 Terraform Cloud OIDC 令牌：

在 Terraform Cloud 中，打开工作区，然后转至变量。
点击添加变量，然后添加以下变量：
- 变量类别：环境变量
- 键：TFC_WORKLOAD_IDENTITY_AUDIENCE
- 值：
```
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
替换以下值：
- PROJECT_NUMBER：包含工作负载身份池的项目的编号
- POOL_ID：工作负载身份池的 ID
- PROVIDER_ID：工作负载身份池提供方的 ID
点击保存变量。

更新 Terraform 配置以使用“可执行凭据”和 shell 脚本从 TFC_WORKLOAD_IDENTITY_AUDIENCE 环境变量中读取 OIDC 令牌，并将其用于工作负载身份联合：

在 Terraform Cloud 的工作区配置中，再添加两个额外变量：

变量类别	键	值
环境变量	`GOOGLE_APPLICATION_CREDENTIALS`	`.google-cloud/workload-identity.json`
环境变量	`GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`	`1`

这些变量会指示 terraform 和客户端库使用可执行文件溯源凭据以及存储在 .google-cloud/workload-identity.json 文件中的配置。

在源代码库中，创建文件 .google-cloud/workload-identity.json 并复制以下配置：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "executable": {
      "command": "/bin/bash .google-cloud/workload-token.sh",
      "timeout_millis": 5000
    }
  },
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken"
}

替换以下值：

PROJECT_NUMBER：包含工作负载身份池的项目的编号
POOL_ID：工作负载身份池的 ID
PROVIDER_ID：工作负载身份池提供方的 ID
SERVICE_ACCOUNT_EMAIL：服务帐号的电子邮件地址

此配置指示客户端库运行脚本 .google-cloud/workload-token.sh 来获取 Terraform Cloud OIDC 令牌。

在源代码库中，创建另一个文件 .google-cloud/workload-token.sh，然后复制以下脚本：

#!/bin/sh
if [ -z $TFC_WORKLOAD_IDENTITY_TOKEN ]
then
    echo '{"version": 1, "success": false, "code": "missing-variable", "message": "TFC_WORKLOAD_IDENTITY_TOKEN not defined in workspace."}'
else
    echo '{"version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:id_token", "id_token": "'"$TFC_WORKLOAD_IDENTITY_TOKEN"'"}'
fi

此脚本从环境变量 TFC_WORKLOAD_IDENTITY_TOKEN 中读取 Terraform Cloud OIDC 令牌，并以客户端库所需的格式返回令牌。

验证您的 Terraform 配置使用 4.48.0 或更高版本的 Google Cloud 提供程序，并根据需要进行更新，如下所示：
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.48.0"
    }
  }
}
```
将更改提交到源代码库。

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

准备外部 IdP

GitHub Actions

Terraform Cloud

配置工作负载身份联合

定义特性映射和条件

GitHub Actions

Terraform Cloud

GitHub Actions

Terraform Cloud

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

所需的角色

控制台

GitHub Actions

Terraform Cloud

gcloud

GitHub Actions

Terraform Cloud

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

为部署流水线创建服务帐号

允许部署流水线模拟服务帐号

控制台

gcloud

按主体

按群组

按特性

所有外部身份

配置部署流水线

GitHub Actions

Terraform Cloud

后续步骤