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

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. 点击 Create service connection。
4. 选择 Azure Resource Manager。
5. 点击下一步。
6. 选择 Workload Identity federation (automatic)
7. 点击下一步。

8. 进行以下设置：

   • Scope level：选择一个订阅。

     即使您不打算使用服务连接来访问 Azure 资源，也必须选择订阅。

   • Service connection name：输入一个名称，例如 google-cloud。

9. 点击保存。

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

1. 点击您刚刚创建的服务连接。
2. 点击 Manage Service Principal。
3. 依次点击 Certificate & secrets > Federated credentials。
4. 点击联合凭据。

5. 在 Edit a credential 页面上，找到以下标识符：

   • Issuer：唯一标识 Azure DevOps 组织
   • Subject identifier：唯一标识服务连接

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

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

GitHub Actions

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

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

GitLab SaaS

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

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

Terraform Cloud

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

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

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 资源的访问权限。

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'

控制台

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

   转到“新建工作负载提供商和池”

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. 点击保存以创建工作负载身份池和提供方。

gcloud

1. 创建新的工作负载身份池：

   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" \
       --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：您之前确定的属性条件。

控制台

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

   转到“工作负载身份池”

2. 找到包含提供方的工作负载身份池，然后点击池对应的 arrow_right 展开节点图标。

3. 找到您要修改的工作负载身份池提供方，然后点击 edit 修改。

4. 在属性条件中，输入您之前确定的属性条件。

5. 如需更新工作负载身份池和提供方，请点击保存。

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：您之前确定的属性条件

直接资源访问权限

您可以使用 Google Cloud 控制台或 gcloud CLI 向联合身份授予直接对资源的访问权限。

服务账号模拟

1. 如需为外部工作负载创建服务账号，请执行以下操作：

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

      Enable the APIs

   2. 创建一个服务账号以代表工作负载。我们建议您为每个工作负载使用专用服务账号。该服务账号不需要与工作负载身份池位于同一项目中，但您必须引用包含该服务账号的项目。

   3. 向服务账号授予对您希望外部身份访问的资源的访问权限。

   4. 向服务账号授予 Workload Identity User 角色 (roles/iam.workloadIdentityUser)。

2. 如需使用 Google Cloud 控制台或 gcloud CLI 通过服务账号模拟向联合身份授予访问权限，请执行以下操作：

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"

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：服务账号的电子邮件地址

该配置会执行以下操作：

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：包含工作负载身份池的项目的编号。
• 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：服务账号的电子邮件地址

该配置会执行以下操作：

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 联合身份验证来使用服务账号模拟功能向 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	工作负载身份池的 ID
   环境变量	TFC_GCP_WORKLOAD_PROVIDER_ID	工作负载身份池提供方的 ID

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

3. 在变量列表中，验证您在上一步中添加的五个变量的类别是否设置为 env。

4. 验证 Terraform 配置是否使用 4.48.0 或更高版本的 Google Cloud 提供程序，并根据需要进行更新，如下所示：

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

5. 将更改提交到您的源代码库。