注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
概览
OpenID Connect (OIDC) 允许您的 GitHub Actions 工作流程使用 HashiCorp Vault 进行身份验证以检索机密。
本指南概述如何配置 HashiCorp Vault 信任 GitHub 的 OIDC 作为联合身份,并演示如何在 hashicorp/vault-action 操作中使用此配置从 HashiCorp Vault 检索机密。
基本要求
-
要了解 GitHub 如何使用 OpenID Connect (OIDC) 的基本概念及其体系结构和优势,请参阅“关于使用 OpenID Connect 进行安全强化”。
-
在继续之前,必须规划安全策略,以确保仅以可预测的方式分配访问令牌。 要控制云提供商颁发访问令牌的方式,必须至少定义一个条件,使不受信任的存储库无法为云资源请求访问令牌。 更多信息请参阅“使用云配置 OIDC 信任”。
将身份提供商添加到 HashiCorp Vault
要将 OIDC 与 HashiCorp Vault 配合使用,您需要为 GitHub OIDC 提供商添加信任配置。 更多信息请参阅 HashiCorp Vault 文档。
配置 Vault 接受 JSON Web 令牌 (JWT) 进行身份验证:
- 对于
oidc_discovery_url
,请使用https://HOSTNAME/_services/token
- 对于
bound_issuer
,请使用https://HOSTNAME/_services/token
- 确保针对您的安全要求正确定义了
bound_subject
。 更多信息请参阅“使用云配置 OIDC 信任”和hashicorp/vault-action
。
更新 GitHub Actions 工作流程
要更新 OIDC 的工作流程,您需要对 YAML 进行两项更改:
- 为令牌添加权限设置。
- 使用
hashicorp/vault-action
操作将 OIDC 令牌 (JWT) 交换为云访问令牌。
要将 OIDC 集成添加到您的工作流程中,以允许他们访问 Vault 中的密钥,您需要添加以下代码更改:
- 授予从 GitHub OIDC 提供商获取令牌的权限:
- 工作流需要
permissions:
设置将id-token
值设为write
。 这使您可以从工作流程中的每个作业中获取 OIDC 令牌。
- 工作流需要
- 向 GitHub OIDC 提供商请求 JWT,并将其提供给 HashiCorp Vault 以接收访问令牌:
- 您可以使用操作工具包来获取作业的令牌,也可以使用
hashicorp/vault-action
操作来获取 JWT 并从 Vault 接收访问令牌。
- 您可以使用操作工具包来获取作业的令牌,也可以使用
此示例演示如何将 OIDC 与官方操作结合使用,以向 HashiCorp Vault 请求机密。
添加权限设置
作业或工作流程运行需要具有 id-token: write
的 permissions
设置。 如果将 id-token
的 permissions
设置设为 read
或 none
,您将无法请求 OIDC JWT ID 令牌。
id-token: write
设置允许使用以下方法之一从 GitHub 的 OIDC 提供商请求 JWT:
- 在运行器上使用环境变量(
ACTIONS_ID_TOKEN_REQUEST_URL
和ACTIONS_ID_TOKEN_REQUEST_TOKEN
)。 - 从 Actions 工具包使用
getIDToken()
。
如果您只需要为单个作业获取 OIDC 令牌,则可以在该作业中设置此权限。 例如:
permissions:
id-token: write
您可能需要在此处指定其他权限,具体取决于工作流程的要求。
请求访问令牌
hashicorp/vault-action
操作从 GitHub OIDC 提供商接收 JWT,然后从 HashiCorp Vault 实例请求访问令牌以检索机密。 更多信息请参阅 HashiCorp Vault 文档。
此示例演示如何创建从 HashiCorp Vault请求机密的作业。
<Vault URL>
:将此值替换为您的 HashiCorp Vault 的URL。<Role name>
:将此值替换为您在 HashiCorp Vault 信任关系中设置的角色。<Audience>
:将此值替换为您在 HashiCorp Vault 信任关系中定义的受众。<Secret-Path>
:将此值替换为您从 HashiCorp Vault 检索的机密的路径。 例如:secret/data/ci npmToken
。
jobs:
retrieve-secret:
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@v2.4.0
with:
url: <Vault URL>
role: <Role name>
method: jwt
jwtGithubAudience: <Audience>
secrets: <Secret-Path>
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.