Настройка OpenID Connect в Docker

Overview

OpenID Connect (OIDC) позволяет рабочим GitHub Actions процессам проходить проверку подлинности с помощью Docker для доступа к Docker Hub и Docker Build Cloud без хранения паролей Docker или personal access tokensмаркеров доступа организации (OATs).GitHub

Вместо управления длительными учетными данными вы настраиваете отношения доверия между GitHub вашей организацией и организацией Docker. Когда рабочий процесс запускается, выдает кратковременный маркер OIDC, GitHub который Docker проверяет в соответствии с настроенными наборами правил, а затем выдает маркер доступа с областью действия для рабочего процесса.

В этом руководстве представлен обзор настройки Docker для доверия GitHubOIDC в качестве федеративного GitHub Actions удостоверения и демонстрируется использование этой конфигурации в рабочем процессе.

Дополнительные сведения см. в документации по Docker по подключениям OIDC .

Prerequisites

• Основные понятия использования GitHub OpenID Connect (OIDC) и его архитектуры и преимуществ см. в статье OpenID Connect.

• Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе .

• Маркеры OIDC, запрошенные для Dependabot заданий event_name обновления, имеют утверждение dynamic. Если политика доверия предназначена для авторизации только GitHub Actions рабочих процессов, и поставщик облачных служб поддерживает условия event_name, разрешайте только имена событий, ожидаемые рабочими процессами. Дополнительные сведения см. в разделе .

• Ваша организация Docker должна использовать Docker Business, Docker Team или Docker Hardened Images или быть зарегистрирована в программе Docker с открытым исходным кодом.

• Вы должны быть владельцем организации или редактором в организации Docker.

• Необходимо спланировать, какие репозитории, ветви и рабочие процессы должны иметь доступ к Docker и соответствующим образом настраивать наборы правил.

Добавление поставщика удостоверений в Docker

Чтобы использовать OIDC с Docker, установите отношение доверия между GitHub Actions Docker и Docker, создав подключение OIDC. Дополнительные сведения об этом процессе см. в разделе "Создание подключений OIDC и управление ими " в документации по Docker.

1. Войдите в Docker Home и перейдите в вашу организацию.
2. Перейдите к подключениям Identity и auth > OIDC.
3. Выберите "Создать подключение OIDC".
4. Настройте по крайней мере один набор правил, чтобы определить, какие GitHub репозитории, ветви или рабочие процессы могут проходить проверку подлинности. Каждый набор правил указывает:
   • Правила: условия, соответствующие утверждениям токена OIDC (репозиторий, ветвь, путь рабочего процесса). Поддерживаются такие шаблоны подстановочных repo:my-org/* знаков.
   • Ресурсы: Docker Hub репозитории или проекты Docker Build Cloud, к рабочему процессу можно получить доступ.
   • Области: уровни разрешений (read, write).
5. Сохраните подключение и скопируйте идентификатор подключения для использования в рабочем процессе.

Обновление вашего GitHub Actions рабочего процесса

После создания подключения OIDC в Docker обновите рабочий процесс, чтобы пройти проверку подлинности с помощью docker/login-action действия.

В следующем примере используется заполнитель YOUR-CONNECTION-ID для идентификатора подключения, скопированного из Docker, и YOUR-DOCKER-ORG для имени организации 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 для рабочего процесса.
• Он docker/login-action обрабатывает обмен маркерами OIDC и имя входа Docker на одном шаге, когда DOCKERHUB_OIDC_CONNECTIONID задано и password опущено.
• Поле username должно быть именем организации Docker.

Сопоставление утверждений субъекта

Docker оценивает sub утверждение из токена GitHub OIDC по заданным вами правилам. Формат утверждения субъекта по умолчанию:

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

Различные триггеры рабочего процесса создают разные утверждения субъекта. Рассмотрим пример.

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
Окружающая среда	repo:my-org/my-repo:environment:production

Шаблоны подстановочных знаков можно использовать в наборе правил для сопоставления нескольких репозиториев или ветвей. Для устаревших утверждений repo:my-org/* субъекта соответствует всем репозиториям в организации. Для неизменяемых утверждений субъекта используйте repo:my-org@OWNER-ID/*; если организация содержит репозитории с использованием обоих форматов, настройте оба шаблона.

Дополнительные сведения см. в разделе "Наборы правил" и утверждения субъекта в документации по Docker.