注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。
概述
OpenID Connect (OIDC) 允许您的 GitHub Actions 工作流程访问 Google Cloud 平台中的资源,而无需将任何 GCP 凭据存储为长期 GitHub 机密。
本指南概述了如何配置 GCP 信任 GitHub 的 OIDC 作为联合标识,并包含 google-github-actions/auth
操作的工作流示例,该操作使用令牌向 GCP 进行身份验证并访问资源。
先决条件
-
若要了解 GitHub 如何使用 OpenID Connect (OIDC) 及其体系结构和优势的基本概念,请参阅“关于使用 OpenID Connect 进行安全强化”。
-
在继续之前,必须规划安全策略,以确保仅以可预测的方式分配访问令牌。 要控制云提供商颁发访问令牌的方式,必须至少定义一个条件,以便不受信任的存储库无法为云资源请求访问令牌。 有关详细信息,请参阅“关于使用 OpenID Connect 进行安全强化”。
添加 Google Cloud 工作负载身份提供商
要在 GCP 中配置 OIDC 身份提供商,您需要执行以下配置。 若要了解如何进行这些更改,请参阅 GCP 文档。
- 创建新的身份池。
- 配置映射并添加条件。
- 将新池连接到服务帐户。
配置身份提供商的附加指导:
- 有关安全强化,请确保已查看“关于使用 OpenID Connect 进行安全强化”。 有关示例,请参阅“关于使用 OpenID Connect 进行安全强化”。
- 要使服务帐户可用于配置,需要将其分配给
roles/iam.workloadIdentityUser
角色。 有关详细信息,请参阅 GCP 文档。 - 要使用的颁发者 URL:
https://HOSTNAME/_services/token
更新 GitHub Actions 工作流程
要更新 OIDC 的工作流程,您需要对 YAML 进行两项更改:
- 为令牌添加权限设置。
- 使用操作
google-github-actions/auth
将 OIDC 令牌 (JWT) 交换为云访问令牌。
注意****:在工作流或 OIDC 策略中使用环境时,建议将保护规则添加到环境中以提高安全性。 例如,可以在环境中配置部署规则,以限制可以部署到环境或访问环境机密的分支和标记。 有关详细信息,请参阅“管理部署环境”。
添加权限设置
作业或工作流运行需要使用 id-token: write
的 permissions
设置,以允许 GitHub 的 OIDC 提供程序为每个运行创建 JSON Web 令牌。 如果 id-token
的 permissions
未设置为 write
,则无法请求 OIDC JWT ID 令牌,但是此值并不表示授予对任何资源的写权限,而只能提取和设置操作或步骤的 OIDC 令牌,以启用通过短期访问令牌进行身份验证。 任何实际信任设置均通过 OIDC 声明定义,有关详细信息,请参阅“关于使用 OpenID Connect 进行安全强化”。
id-token: write
设置允许使用下列方法之一从 GitHub 的 OIDC 提供程序请求 JWT:
- 在运行器上使用环境变量(
ACTIONS_ID_TOKEN_REQUEST_URL
和ACTIONS_ID_TOKEN_REQUEST_TOKEN
)。 - 使用“操作”工具包中的
getIDToken()
。
如果需要为工作流提取 OIDC 令牌,则可以在工作流级别设置权限。 例如:
permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout
permissions:
id-token: write # This is required for requesting the JWT
contents: read # This is required for actions/checkout
如果只需要为单个作业提取 OIDC 令牌,则可在该作业中设置此权限。 例如:
permissions: id-token: write # This is required for requesting the JWT
permissions:
id-token: write # This is required for requesting the JWT
可能需要在此处指定额外权限,具体取决于你的工作流要求。
对于与调用方工作流属于同一用户、组织或企业的可重用工作流,可以从调用方的上下文访问在可重用工作流中生成的 OIDC 令牌。
对于企业或组织外部的可重用工作流,应在调用方工作流级别或在调用可重用工作流的特定作业中将 id-token
的 permissions
设置显式设置为 write
。
这可确保仅允许可重用工作流中生成的 OIDC 令牌按预期在调用方工作流中使用。
有关详细信息,请参阅“重新使用工作流”。
请求访问令牌
google-github-actions/auth
操作从 GitHub OIDC 提供商接收 JWT,然后从 GCP 请求访问令牌。 有关详细信息,请参阅 GCP 文档。
此示例有一个名为 Get_OIDC_ID_token
的作业,该作业使用操作从 GCP 请求服务列表。
WORKLOAD-IDENTITY-PROVIDER
:将此值替换为指向 GCP 中标识提供者的路径。 例如:projects/example-project-id/locations/global/workloadIdentityPools/name-of-pool/providers/name-of-provider
SERVICE-ACCOUNT
:将此值替换为你在 GCP 中的服务帐户的名称。
此操作使用工作负载联合身份验证将 GitHub OIDC 令牌交换为 Google Cloud 访问令牌。
name: List services in GCP on: pull_request: branches: - main permissions: id-token: write jobs: Get_OIDC_ID_token: runs-on: ubuntu-latest steps: - id: 'auth' name: 'Authenticate to GCP' uses: 'google-github-actions/auth@f1e2d3c4b5a6f7e8d9c0b1a2c3d4e5f6a7b8c9d0' with: create_credentials_file: 'true' workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER' service_account: 'SERVICE-ACCOUNT' - id: 'gcloud' name: 'gcloud' run: |- gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}" gcloud services list
name: List services in GCP
on:
pull_request:
branches:
- main
permissions:
id-token: write
jobs:
Get_OIDC_ID_token:
runs-on: ubuntu-latest
steps:
- id: 'auth'
name: 'Authenticate to GCP'
uses: 'google-github-actions/auth@f1e2d3c4b5a6f7e8d9c0b1a2c3d4e5f6a7b8c9d0'
with:
create_credentials_file: 'true'
workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER'
service_account: 'SERVICE-ACCOUNT'
- id: 'gcloud'
name: 'gcloud'
run: |-
gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
gcloud services list