消除 CI/CD 流水线中存储的凭证

TL;DR：Docker 现已支持 OpenID Connect (OIDC) for GitHub Actions。您的 workflow 可使用每个运行短期的令牌进行身份验证，而无需存储 PAT 或 OAT。无需轮换密钥，无凭证泄露风险。

GitHub OIDC 连接可供拥有 Docker Team、Docker Business 或 Docker Hardened Images (DHI) 订阅的组织，以及已加入 Docker Sponsored Open Source Program (DSOS) 的组织使用。

目录

  • 存储凭证的问题
  • 谁应该使用此功能
  • OIDC 连接的工作原理
  • 入门指南
  • 哪些部分不会改变
  • 了解更多

GitHub Actions 与 Docker 之间的 OIDC 令牌交换流程

diagram final

存储凭证的问题

每个向 Docker Hub 推送或拉取镜像的 GitHub Actions workflow 都使用存储在 GitHub 密钥中的个人访问令牌 (PAT) 或组织访问令牌 (OAT) 进行身份验证。这些凭证是长期有效的。必须有人记得轮换它们。泄露的令牌将授予对您的 registry 的访问权限——拉取私有镜像、推送恶意镜像——并且在有人发现并撤销它之前，这种访问权限将持续存在。轮换是手动的，无法扩展。随着流水线的增多，需要跟踪的凭证也随之增加，而过时令牌是常见的审计发现。

谁应该使用此功能

  1. GitHub 颁发一个签名的身份令牌（JWT），其中包含有关 workflow 运行的仓库、分支、环境和其他元数据。
  2. workflow 调用 docker/login-action，将此令牌呈现给 Docker。
  3. Docker 根据 GitHub 的公钥 registry 验证令牌的签名，并根据管理控制台中配置的规则集进行检查。
  4. 如果令牌与规则集匹配，Docker 将返回一个短期访问令牌，其范围限定为该规则集中定义的资源。
  5. docker/login-action 使用此令牌对 Docker Hub 进行身份验证。此后，docker pull、docker push 和 docker build 命令将照常工作。

整个交换过程无需任何存储的密钥、API 密钥或访问令牌。短期 Docker 访问令牌将在几分钟后过期，且无法重复使用。

这与 AWS 和 GCP 已经用于云资源访问的模式相同（AWS OIDC for GitHub Actions，GCP Workload Identity Federation）。Docker 将其应用于容器 registry 访问。

入门指南

设置是在 Docker Home 中进行的一次性连接，加上对 workflow YAML 的小幅更新。

第 1 步：创建连接

登录 Docker Home，选择您的组织，然后导航到 OIDC 连接。选择“创建 OIDC 连接”，并配置控制哪些仓库、分支和工作流可以访问哪些 Docker Hub 资源的规则集。每个连接最多可以创建五个规则集。当 workflow 触发 OIDC 交换时，Docker 会根据连接中定义的每个规则集检查令牌。如果某个规则集的条件得到满足，Docker 将根据该规则集设置的参数授予访问权限。

规则集使用 OIDC 主体声明来匹配传入的令牌。作为推荐的安全最佳实践，您可以固定到特定的仓库和分支：

  • repo:my-org/my-repo:ref:refs/heads/main — 仅特定仓库的主分支
  • repo:my-org/my-repo:ref:refs/heads/release-* — 所有发布分支
  • repo:my-org/my-repo:* – 此仓库的所有分支
  • repo:my-org/* — 组织中的任何仓库（不推荐）

完成后复制连接 ID。

注意：2026 年 7 月 15 日之后创建的 GitHub 仓库使用不可变的标识符作为默认主体声明。例如：repo:octocat@123456/my-repo@456789:ref:refs/heads/main。有关更多详细信息，请参阅 GitHub 更新日志。

第 2 步：更新 workflow

更新您的 GitHub Actions workflow。将 <YOUR_CONNECTION_ID> 替换为上一步中的 ID，并将 <YOUR_ORG_NAME> 替换为您的 Docker 组织名称：

permissions:
  contents: read
  id-token: write

steps:
    - name: Docker login                                                                                                                                                                 
      uses: docker/login-action@v4 # v4.5.0+                                                                                                                                                                
      with:                           
        username: <YOUR_ORG_NAME>
      env:                                                                                                                                                                               
        DOCKERHUB_OIDC_CONNECTIONID: <YOUR_CONNECTION_ID>

id-token: write 权限允许 workflow 请求 GitHub OIDC 令牌。当设置了 DOCKERHUB_OIDC_CONNECTIONID 时，docker/login-action 会在一步中处理令牌交换和 Docker 登录。此后，docker pull、docker push 和 docker build 命令将照常工作。传入声明 sub 值的详细信息，您可以使用它来诊断连接失败的原因。

第 3 步：验证 OIDC 连接是否正常工作

运行您的 workflow 并确认其成功完成。如果遇到错误，OIDC 连接页面的“失败”选项卡将显示传入声明 sub 值的详细信息，您可以使用它来诊断连接失败的原因。

第 4 步：移除存储的凭证

在验证 workflow 成功使用 OIDC 运行后，从 GitHub 仓库密钥中移除旧的 PAT 或 OAT。您不再需要它。

迁移清单

  • 创建连接
  • 更新 workflow
  • 验证 OIDC 连接是否正常工作
  • 移除存储的凭证

哪些部分不会改变

  • 现有的 PAT 和 OAT 继续正常工作。组织可以按自己的节奏将 workflow 迁移到 OIDC 连接。
  • 镜像、registry 和构建 workflow 保持不变。OIDC 连接仅替换身份验证步骤；下游的一切保持不变。
  • 本地开发和非 GitHub CI 仍使用 PAT 和 OAT。OIDC 连接是专门针对 GitHub Actions 的推荐替代方案。其他 CI 提供商将根据需求跟进。

了解更多