Skip to main content

在 HashiCorp Vault 中配置 OpenID Connect

在工作流程中使用 OpenID Connect 通过 HashiCorp Vault 进行身份验证。

概览

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://token.actions.githubusercontent.com
  • 对于 bound_issuer,请使用 https://token.actions.githubusercontent.com
  • 确保针对您的安全要求正确定义了 bound_subject。 更多信息请参阅“使用云配置 OIDC 信任”hashicorp/vault-action

更新 GitHub Actions 工作流程

要更新 OIDC 的工作流程,您需要对 YAML 进行两项更改:

  1. 为令牌添加权限设置。
  2. 使用 hashicorp/vault-action 操作将 OIDC 令牌 (JWT) 交换为云访问令牌。

要将 OIDC 集成添加到您的工作流程中,以允许他们访问 Vault 中的密钥,您需要添加以下代码更改:

  • 授予从 GitHub OIDC 提供商获取令牌的权限:
    • 工作流需要 permissions: 设置将 id-token 值设为 write。 这使您可以从工作流程中的每个作业中获取 OIDC 令牌。
  • 向 GitHub OIDC 提供商请求 JWT,并将其提供给 HashiCorp Vault 以接收访问令牌:

此示例演示如何将 OIDC 与官方操作结合使用,以向 HashiCorp Vault 请求机密。

添加权限设置

 The job or workflow run requires a permissions setting with id-token: write. You won't be able to request the OIDC JWT ID token if the permissions setting for id-token is set to read or none.

The id-token: write setting allows the JWT to be requested from GitHub's OIDC provider using one of these approaches:

  • Using environment variables on the runner (ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN).
  • Using getIDToken() from the Actions toolkit.

如果您只需要为单个作业获取 OIDC 令牌,则可以在该作业中设置此权限。 例如:

YAML
permissions:
  id-token: write

You may need to specify additional permissions here, depending on your workflow's requirements.

请求访问令牌

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
YAML
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.