Konfigurieren von OpenID Connect in Docker

Overview

OpenID Connect (OIDC) ermöglicht Ihren GitHub Actions Workflows, sich bei Docker zu authentifizieren, um auf Docker Hub und Docker Build Cloud zuzugreifen, ohne Docker-Kennwörter, personal access tokens oder Organisationszugriffstoken (OATs) in GitHub Workflows zu speichern.

Anstatt langlebige Anmeldeinformationen zu verwalten, konfigurieren Sie eine Vertrauensstellung zwischen Ihrer GitHub Organisation und Ihrer Docker-Organisation. Wenn ein Workflow ausgeführt wird, stellt GitHub ein kurzlebiges OIDC-Token aus, das Docker anhand Ihrer konfigurierten Regelsätze überprüft, und stellt dann ein bereichsbezogenes Zugriffstoken für den Workflow aus.

In diesem Handbuch finden Sie eine Übersicht darüber, wie Sie Docker so konfigurieren, dass dem OIDC von GitHub als Verbundidentität vertraut wird, und wie Sie diese Konfiguration in einem GitHub Actions-Workflow verwenden.

Weitere Informationen finden Sie unter OIDC-Verbindungen in der Docker-Dokumentation.

Prerequisites

• Informationen zu den grundlegenden Konzepten der Verwendung von GitHub OpenID Connect (OIDC) und deren Architektur und Vorteile finden Sie unter OpenID Connect.

• Bevor du fortfährst, musst du deine Sicherheitsstrategie planen, um sicherzustellen, dass Zugriffs-Token nur auf vorhersehbare Weise zugewiesen werden. Zur Steuerung, wie dein Cloud-Anbieter Zugriffs-Token ausgibt, musst du mindestens eine Bedingung definieren, damit nicht vertrauenswürdige Repositorys keine Zugriffs-Token für deine Cloud-Ressourcen anfordern können. Weitere Informationen finden Sie unter OpenID Connect-Referenz.

• Für Aktualisierungsaufträge angeforderte Dependabot OIDC-Token haben einen event_name Anspruch von dynamic. Wenn Ihre Vertrauensrichtlinie nur GitHub Actions Workflows autorisieren soll und Ihr Cloudanbieter Bedingungen für event_name unterstützt, lassen Sie nur die Ereignisnamen zu, die von Ihren Workflows erwartet werden. Weitere Informationen finden Sie unter OpenID Connect-Referenz.

• Ihre Docker-Organisation muss Docker Business, Docker Team oder Docker Hardened Images verwenden oder im Docker-gesponserten Open Source-Programm registriert sein.

• Sie müssen Besitzer oder Editor einer Organisation in Ihrer Docker-Organisation sein.

• Sie müssen planen, welche Repositorys, Verzweigungen und Workflows Zugriff auf Docker benötigen, und Regeln entsprechend konfigurieren.

Hinzufügen des Identitätsanbieters zu Docker

Um OIDC mit Docker zu verwenden, richten Sie eine Vertrauensstellung zwischen GitHub Actions und Docker ein, indem Sie eine OIDC-Verbindung erstellen. Weitere Informationen zu diesem Prozess finden Sie unter Erstellen und Verwalten von OIDC-Verbindungen in der Docker-Dokumentation.

1. Melden Sie sich bei Docker Home an, und navigieren Sie zu Ihrer Organisation.
2. Wechseln Sie zu Identität und Authentifizierung > OIDC-Verbindungen.
3. Wählen Sie "OIDC-Verbindung erstellen" aus.
4. Konfigurieren Sie mindestens einen Regelsatz, um zu definieren, welche GitHub Repositorys, Verzweigungen oder Workflows sich authentifizieren können. Jedes Regelwerk gibt Folgendes an:
   • Regeln: Bedingungen, die mit OIDC-Token-Claims (Repository, Verzweigung, Workflowpfad) übereinstimmen. Wildcardmuster wie repo:my-org/* werden unterstützt.
   • Ressourcen: Docker Hub Repositorys oder Docker Build Cloud-Projekte, auf die der Workflow zugreifen kann.
   • Berechtigungsbereiche: Berechtigungsstufen (read, write).
5. Speichern Sie die Verbindung, und kopieren Sie die Verbindungs-ID für die Verwendung in Ihrem Workflow.

Aktualisieren des GitHub Actions Workflows

Nachdem Sie eine OIDC-Verbindung in Docker erstellt haben, aktualisieren Sie Ihren Workflow so, dass er sich mithilfe der Aktion docker/login-action authentifiziert.

Im folgenden Beispiel wird der Platzhalter YOUR-CONNECTION-ID für die Verbindungs-ID verwendet, die Sie aus Docker kopiert haben, und YOUR-DOCKER-ORG für den Namen Ihrer Docker-Organisation.

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.
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

Zentrale Workflow-Einstellungen

• permissions.id-token: write ist erforderlich, damit GitHub ein OIDC-Token für den Workflow ausstellen kann.
• Die docker/login-action Behandelt den OIDC-Tokenaustausch und die Docker-Anmeldung in einem einzigen Schritt, wenn DOCKERHUB_OIDC_CONNECTIONID festgelegt und password weggelassen wird.
• Das username Feld sollte Der Name Ihrer Docker-Organisation sein.

Abgleich von Betreff-Ansprüchen

Docker wertet den GitHub Claim aus dem sub OIDC-Token anhand der von Ihnen konfigurierten Regeln aus. Das Standardformat für den Subjektanspruch lautet:

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

Unterschiedliche Workflowtrigger erzeugen unterschiedliche Subjektansprüche. Beispiele:

Trigger	Format der Betreffzeile
Branch-Push	repo:my-org/my-repo:ref:refs/heads/main
Pull-Anfrage	repo:my-org/my-repo:pull_request
Tag	repo:my-org/my-repo:ref:refs/tags/v1.0
Umwelt	repo:my-org/my-repo:environment:production

Mit Wildcardmustern können Sie in Ihren Regelets mehrere Repositorys oder Verzweigungen abgleichen. Bei veralteten Subject-Claims trifft repo:my-org/* auf alle Repositorys in der Organisation zu. Verwenden Sie repo:my-org@OWNER-ID/* für unveränderliche Subject-Claims; wenn die Organisation Repositorys in beiden Formaten verwendet, konfigurieren Sie beide Patterns.

Weitere Informationen finden Sie unter "Rulesets" und "Subject Claims" in der Docker-Dokumentation.