Configuration d’OpenID Connect dans Docker

Overview

OpenID Connect (OIDC) permet à vos GitHub Actions flux de travail de s’authentifier auprès de Docker pour accéder à Docker Hub et Docker Build Cloud sans stocker les mots de passe Docker, personal access tokens, ou les jetons d’accès de l’organisation (OAT) dans GitHub.

Au lieu de gérer les informations d’identification de longue durée, vous configurez une relation d’approbation entre votre organisation GitHub et votre organisation Docker. Lorsqu’un flux de travail s’exécute, GitHub émet un jeton OIDC de courte durée que Docker valide par rapport à vos ensembles de règles configurés, puis émet un jeton d’accès à portée limitée pour le flux de travail.

Ce guide donne une vue d’ensemble de la configuration de Docker pour faire confiance à l’OIDC de GitHub comme identité fédérée et montre comment utiliser cette configuration dans un GitHub Actions flux de travail.

Pour plus d’informations, consultez les connexions OIDC dans la documentation Docker.

Prerequisites

• Pour découvrir les concepts de base de l’utilisation GitHub d’OpenID Connect (OIDC) et de son architecture et de ses avantages, consultez OpenID Connect.

• Avant de continuer, vous devez planifier votre stratégie de sécurité pour veiller à ce que les jetons d’accès soient uniquement alloués de manière prévisible. Pour contrôler la façon dont votre fournisseur de cloud émet des jetons d’accès, vous devez définir au moins une condition, afin que les dépôts non approuvés ne puissent pas demander de jetons d’accès à vos ressources cloud. Pour plus d’informations, consultez Informations de référence sur OpenID Connect.

• Les jetons OIDC demandés pour les travaux de mise à jour Dependabot comportent un claim event_name de valeur dynamic. Si votre stratégie d’approbation est destinée à autoriser uniquement GitHub Actions les flux de travail et que votre fournisseur de cloud prend en charge les conditions sur event_name, autorisez uniquement les noms d’événements attendus par vos flux de travail. Pour plus d’informations, consultez Informations de référence sur OpenID Connect.

• Votre organisation Docker doit utiliser Docker Business, Docker Team ou Docker Hardened Images, ou être inscrite dans le programme Open Source Parrainé Docker.

• Vous devez être propriétaire ou éditeur de votre organisation Docker.

• Vous devez planifier les dépôts, les branches et les workflows qui ont besoin d’accéder à Docker et configurer les ensembles de règles en conséquence.

Ajout du fournisseur d’identité à Docker

Pour utiliser OIDC avec Docker, établissez une relation de confiance entre GitHub Actions et Docker en créant une connexion OIDC. Pour plus d’informations sur ce processus, consultez Créer et gérer des connexions OIDC dans la documentation Docker.

1. Connectez-vous à Docker Home et accédez à votre organisation.
2. Accédez à Identité et authentification > Connexions OIDC.
3. Sélectionnez Créer une connexion OIDC.
4. Configurez au moins un ensemble de règles pour définir les GitHub référentiels, branches ou workflows qui peuvent être authentifiés. Chaque ensemble de règles spécifie :
   • Règles : Conditions correspondant aux claims du jeton OIDC (référentiel, branche, chemin du workflow). Les motifs génériques comme repo:my-org/* sont pris en charge.
   • Ressources : dépôts Docker Hub ou projets Docker Build Cloud auxquels le flux de travail peut accéder.
   • Portées : niveaux d’autorisation (read, write).
5. Enregistrez la connexion et copiez l’ID de connexion à utiliser dans votre flux de travail.

Mise à jour de votre GitHub Actions flux de travail

Une fois que vous avez créé une connexion OIDC dans Docker, mettez à jour votre workflow pour vous authentifier à l’aide de l’action docker/login-action .

L’exemple suivant utilise l’espace réservé YOUR-CONNECTION-ID pour l’ID de connexion que vous avez copié à partir de Docker et YOUR-DOCKER-ORG pour le nom de votre organisation Docker.

# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub.
# Elles sont fournies par un tiers et régies par
# des conditions d’utilisation du service, une politique de confidentialité et un support distincts.
# documentation en ligne.
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

Paramètres clés du flux de travail

• permissions.id-token: write est nécessaire pour pouvoir GitHub émettre un jeton OIDC pour le flux de travail.
• Le docker/login-action gère l’échange de jetons OIDC et la connexion Docker en une seule étape lorsque DOCKERHUB_OIDC_CONNECTIONID est défini et password est omis.
• Le username champ doit être le nom de votre organisation Docker.

Correspondance des revendications du sujet

Docker évalue la revendication du GitHub jeton OIDC par rapport aux jeux de règles que vous avez configurés. Le format de revendication de sujet par défaut est :

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

Différents déclencheurs de flux de travail produisent différentes revendications de sujet. Par exemple:

Trigger	Format de revendication du sujet
Pousser la branche	repo:my-org/my-repo:ref:refs/heads/main
Demande de tirage (pull request)	repo:my-org/my-repo:pull_request
Tag	repo:my-org/my-repo:ref:refs/tags/v1.0
Environnement	repo:my-org/my-repo:environment:production

Vous pouvez utiliser des motifs génériques dans vos ensembles de règles pour faire correspondre plusieurs référentiels ou branches. Pour les revendications de sujet héritées, repo:my-org/* correspond à tous les dépôts de l’organisation. Pour les revendications de sujet immuables, utilisez repo:my-org@OWNER-ID/*; si l’organisation contient des dépôts utilisant les deux formats, configurez les deux motifs.

Pour plus d’informations, consultez Les jeux de règles et les revendications du sujet dans la documentation Docker.