在 HashiCorp Vault 中配置 OpenID Connect

概览

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 进行两项更改：

1. 为令牌添加权限设置。
2. 使用 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.