Docker 组织现已支持面向 GitHub Actions 的 OIDC 连接-未完纪

消除 CI/CD 流水线中保存的凭据

要点：Docker 现已支持 GitHub Actions 的 OpenID Connect（OIDC）。工作流可以使用每次运行生成的短期令牌进行身份验证，替代保存的 PAT 或 OAT。无需轮换机密，也没有保存的凭据可供泄露。

GitHub OIDC 连接适用于订阅 Docker Team、Docker Business 或 Docker Hardened Images（DHI）的组织，以及加入 Docker Sponsored Open Source Program（DSOS）的组织。

保存凭据带来的问题

每个向 Docker Hub 推送镜像或从中拉取镜像的 GitHub Actions 工作流，都使用保存在 GitHub secret 中的个人访问令牌（PAT）或组织访问令牌（OAT）进行身份验证。这些凭据长期有效，必须有人记得轮换。泄露的令牌会授予对镜像仓库的访问权限——例如拉取私有镜像、推送恶意镜像——这种权限会一直持续，直到有人发现并撤销令牌。手动轮换难以随规模扩展。流水线数量越多，需要跟踪的凭据也越多，而过期未清理的令牌是审计中的常见问题。

谁应使用此功能

GitHub 签发一个经过签名的身份令牌（JWT），其中编码了工作流运行的仓库、分支、环境及其他元数据。
工作流调用 docker/login-action，将这个令牌提交给 Docker。
Docker 根据 GitHub 的公钥注册表验证令牌签名，并按照 Admin Console 中配置的规则集检查令牌。
如果令牌匹配某个规则集，Docker 会返回一个短期访问令牌，其权限范围限定为规则集定义的资源。
docker/login-action 使用此令牌登录 Docker Hub。此后，docker pull、docker push 和 docker build 命令照常工作。

整个交换过程不需要保存任何 secret、API 密钥或访问令牌。短期 Docker 访问令牌会在几分钟内到期，而且不能重复使用。

这与 AWS 和 GCP 已经用于云资源访问的模式相同（面向 GitHub Actions 的 AWS OIDC、GCP Workload Identity Federation）。Docker 将这种模式应用于容器镜像仓库访问。

开始使用

配置只需要在 Docker Home 中一次性创建连接，并对工作流 YAML 做少量调整。

步骤1：创建连接

登录 Docker Home，选择你的组织，进入 OIDC connections。选择 Create OIDC connection，并配置规则集，控制哪些仓库、分支和工作流可以访问哪些 Docker Hub 资源。每个连接最多可以创建五个规则集。工作流触发 OIDC 交换时，Docker 会按照连接中定义的每个规则集检查令牌。如果满足某个规则集的条件，Docker 就会根据该规则集设置的参数授予访问权限。

规则集使用 OIDC subject 声明匹配传入的令牌。推荐的安全最佳实践是限定为特定仓库和分支：

repo:my-org/my-repo:ref:refs/heads/main——仅允许某个仓库的 main 分支。
repo:my-org/my-repo:ref:refs/heads/release-*——允许所有 release 分支。
repo:my-org/my-repo:*——允许该仓库的所有分支。
repo:my-org/*——允许组织中的任意仓库（不推荐）。

完成后复制连接 ID。

步骤2：更新工作流

更新 GitHub Actions 工作流。将 <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 权限允许工作流请求 GitHub OIDC 令牌。设置 DOCKERHUB_OIDC_CONNECTIONID 后，docker/login-action 会在一个步骤中处理令牌交换与 Docker 登录。此后，docker pull、docker push 和 docker build 命令照常工作。传入声明中的 sub 值详情可以帮助诊断连接失败的原因。

步骤3：验证 OIDC 连接正常工作

运行工作流并确认它成功完成。如果遇到错误，OIDC 连接页面的 Failures 标签页会显示传入声明中的 sub 值详情，可用于诊断连接失败原因。

步骤4：移除保存的凭据

确认工作流使用 OIDC 成功运行之后，从 GitHub 仓库的 secrets 中移除旧 PAT 或 OAT。你已经不再需要它。

迁移检查清单

创建连接
更新工作流
验证 OIDC 连接正常工作
移除保存的凭据

保持不变的部分

现有 PAT 和 OAT 继续有效。组织可以按自己的节奏将工作流迁移到 OIDC 连接。
镜像、镜像仓库和构建工作流保持不变。OIDC 连接只替换身份验证步骤，后续流程完全相同。
本地开发和非 GitHub CI 仍使用 PAT 和 OAT。OIDC 连接是专门面向 GitHub Actions 的推荐替代方案。其他 CI 提供商将根据需求陆续获得支持。