在 Docker 中配置 OpenID Connect

Overview

OpenID Connect（OIDC）允许GitHub Actions工作流使用 Docker 进行身份验证，以访问 Docker Hub 和 Docker Build Cloud，而无需将 Docker 密码、personal access tokens或组织访问令牌（OAT）存储在 GitHub 中。

无需管理长期凭据，而是您可以在您的 GitHub 组织与您的 Docker 组织之间配置信任关系。工作流运行时，GitHub 发出一个短期有效的 OIDC 令牌，Docker 会根据你配置的规则集验证该令牌，然后颁发面向该工作流的限定范围访问令牌。

本指南概述了如何将 Docker 配置为信任 GitHub 的 OIDC 作为联合标识，并演示如何在 GitHub Actions 工作流中使用此配置。

有关详细信息，请参阅 Docker 文档中的 OIDC 连接。

Prerequisites

若要了解使用 OpenID Connect（OIDC）及其体系结构和优势的基本概念 GitHub ，请参阅 OpenID Connect。
在继续之前，必须规划安全策略，以确保仅以可预测的方式分配访问令牌。要控制云提供商颁发访问令牌的方式，必须至少定义一个条件，以便不受信任的存储库无法为云资源请求访问令牌。有关详细信息，请参阅 OpenID Connect 参考。
为 Dependabot 更新作业请求的 OIDC 令牌，其 event_name 声明为 dynamic。如果您的信任策略旨在仅向 GitHub Actions 工作流授予权限，并且您的云提供商支持针对 event_name 设置条件，则只允许您的工作流所预期的事件名称。有关详细信息，请参阅 OpenID Connect 参考。
Docker 组织必须使用 Docker Business、Docker Team 或 Docker Hardened Images，或注册 Docker 赞助的开源计划。
您必须是 Docker 组织中的组织所有者或编辑器。
必须规划哪些存储库、分支和工作流需要访问 Docker，并相应地配置规则集。

将标识提供者添加到 Docker

若要将 OIDC 与 Docker 配合使用，请通过创建 OIDC 连接在 GitHub Actions 与 Docker 之间建立信任关系。有关此过程的详细信息，请参阅 Docker 文档中的 “创建和管理 OIDC 连接”。

登录到 Docker Home 并转到您的组织。
转到 标识和身份验证 > OIDC 连接。
选择“ 创建 OIDC 连接”。
配置至少一个规则集来定义哪些 GitHub 存储库、分支或工作流可以通过身份验证。每个规则集指定：
- 规则：与 OIDC 令牌声明（存储库、分支、工作流路径）匹配的条件。支持诸如 repo:my-org/* 这样的通配符模式。
- 资源：Docker Hub 存储库或 Docker Build Cloud 项目，工作流可以访问。
- 作用域：权限级别（read，write）。
保存连接并复制 连接 ID ，以便在工作流中使用。

更新 GitHub Actions 工作流

在 Docker 中创建 OIDC 连接后，更新工作流以使用 docker/login-action 操作进行身份验证。

以下示例使用占位符 YOUR-DOCKER-ORG 表示从 Docker 复制的连接 ID，使用 YOUR-CONNECTION-ID 表示您的 Docker 组织名称。

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档。
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Sign in to Docker Hub with OIDC
        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
        with:
          username: YOUR-DOCKER-ORG
        env:
          DOCKERHUB_OIDC_CONNECTIONID: YOUR-CONNECTION-ID

      - name: Build and push
        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
        with:
          push: true
          tags: YOUR-DOCKER-ORG/my-image:latest

关键工作流设置

permissions.id-token: write 是必需的，以便 GitHub 可以颁发工作流的 OIDC 令牌。
当设置DOCKERHUB_OIDC_CONNECTIONID且省略docker/login-action时，password会在单个步骤中处理 OIDC 令牌交换和 Docker 登录。
username 字段中的内容应为 Docker 组织名称。

主体声明匹配

Docker 根据配置的规则集评估来自 GitHub OIDC 令牌的sub声明。默认主题声明格式为：

repo:<owner>/<repo>:ref:refs/heads/<branch>

注意

在 2026 年 7 月 15 日之后创建的存储库，以及在该日期之后重命名或转移的存储库，使用包含所有者和存储库 ID 的不可变默认 OIDC sub 声明。现有存储库保留以前的格式，除非它们选择加入。有关详细信息，请参阅“OpenID Connect 参考”。

不同的工作流触发器生成不同的主体声明。例如：

Trigger	主题声明格式
分支推送	`repo:my-org/my-repo:ref:refs/heads/main`
拉取请求	`repo:my-org/my-repo:pull_request`
标记	`repo:my-org/my-repo:ref:refs/tags/v1.0`
Environment	`repo:my-org/my-repo:environment:production`

可以在规则集中使用通配符模式来匹配多个存储库或分支。对于旧版主体声明，repo:my-org/* 匹配组织中的所有存储库。对于不可变的主题声明，请使用 repo:my-org@OWNER-ID/*;如果组织包含使用这两种格式的存储库，请配置这两种模式。

有关详细信息，请参阅 Docker 文档中的规则集和主题声明。