Authentifizierungsmethoden

Auf dieser Seite wird gezeigt, wie Sie den Client eines Drittanbieters für die Authentifizierung bei Container Registry konfigurieren.

Google Cloud-Dienste, die in Container Registry eingebunden werden, sind mit Berechtigungen für den Zugriff auf Repositories im selben Projekt vorkonfiguriert. Für diese Dienste müssen Sie die Authentifizierung nicht konfigurieren. Sie sollten aber prüfen, ob die Berechtigungen ordnungsgemäß konfiguriert sind.

Hinweis

1. Prüfen Sie, ob Sie die Container Registry API aktiviert und die gcloud CLI installiert haben. Anleitungen finden Sie unter Dienst aktivieren und deaktivieren.

2. Achten Sie darauf, dass das Konto, das Sie für die Authentifizierung verwenden, Berechtigungen zum Zugriff auf Container Registry hat. Wir empfehlen die Verwendung eines Dienstkontos anstelle eines Nutzerkontos.

3. Installieren Sie Docker, falls es noch nicht installiert ist. Docker ist in Cloud Shell enthalten.

4. Docker benötigt für die Interaktion mit Registries Zugriff. Fügen Sie unter Linux oder Windows den Nutzer hinzu, mit dem Sie Docker-Befehle in der Docker-Sicherheitsgruppe ausführen. Dieser Schritt ist nicht für Mac OS erforderlich, da Docker Desktop auf einer virtuellen Maschine als Root-Nutzer ausgeführt wird.

   Linux

   Die Docker-Sicherheitsgruppe heißt docker. Führen Sie den folgenden Befehl aus, um Ihren Nutzernamen hinzuzufügen:

   sudo usermod -a -G docker ${USER}
   

   Windows

   Die Docker-Sicherheitsgruppe heißt docker-users. Führen Sie den folgenden Befehl aus, um einen Nutzer über die Administrator-Eingabeaufforderung hinzuzufügen:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Dabei gilt:

   • DOMAIN ist Ihre Windows-Domain.
   • USERNAME ist Ihr Nutzername.

   Melden Sie sich ab und wieder an, damit Änderungen an der Gruppenmitgliedschaft wirksam werden. Wenn Sie eine virtuelle Maschine verwenden, müssen Sie sie unter Umständen neu starten, damit die Mitgliedschaftsänderungen wirksam werden.

   Hinweis: Die Docker-Sicherheitsgruppe hat dieselben Zugriffsrechte wie der Root- oder Administratornutzer. Fügen Sie nur vertrauenswürdige Nutzer hinzu, die Zugriff auf Docker benötigen. Weitere Informationen zu den Auswirkungen auf die Sicherheit finden Sie unter Sicherheit des Docker-Daemon.

Authentifizierungsmethoden

Sie müssen alle Drittanbieterclients konfigurieren, die auf Container Registry zugreifen sollen.

Die folgenden Authentifizierungsmethoden sind verfügbar:

gcloud Credential Helper (empfohlen)

Konfigurieren Sie Ihre Container Registry-Anmeldedaten für die Verwendung mit Docker direkt in gcloud. Verwenden Sie diese Methode nach Möglichkeit, um einen sicheren, kurzzeitigen Zugriff auf Ihre Projektressourcen zu gewähren. Diese Option unterstützt nur Docker-Versionen ab 18.03.

Eigenständiger Credential Helper

Diese Option dient hauptsächlich zur Konfiguration Ihrer Anmeldedaten zur Verwendung mit Docker, wenn keine Google Cloud CLI vorhanden ist. Diese Option unterstützt nur Docker-Versionen ab 18.03.

Zugriffstoken

Standardanmeldedaten für Anwendungen stellen kurzlebige Zugriffstokens bereit, die ein Dienstkonto für den Zugriff auf Ihre Google Cloud-Ressourcen verwendet. Es ist die sicherste Alternative zur Verwendung von gcloud als Credential Helper.

JSON-Schlüsseldatei

Ein vom Nutzer verwaltetes Schlüsselpaar, das Sie als Anmeldedaten für ein Dienstkonto verwenden können. Da die Anmeldedaten langlebig sind, ist es die unsicherste Option aller verfügbaren Authentifizierungsmethoden.

Verwenden Sie nach Möglichkeit ein Zugriffstoken oder eine andere verfügbare Authentifizierungsmethode, um das Risiko eines unberechtigten Zugriffs auf Ihre Artefakte zu verringern. Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkont oschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.

Warnung: Docker Credential Helper wird nur für Docker 18.03 oder höher unterstützt. Ein Programmfehler in früheren Versionen des Docker-Clients verlangsamt docker build drastisch, wenn Credential Helper konfiguriert sind.

Einige Tools oder Workflows bieten keinen guten Support für die Verwendung von gcloud als Credential Helper. Wenn Sie eine der alternativen Optionen verwenden, müssen Sie die Auswirkungen auf die Sicherheit verstehen.

Authentifizierungseinstellungen in der Docker-Konfigurationsdatei

Docker speichert die Authentifizierungseinstellungen in der Konfigurationsdatei config.json.

• Linux: ~/.docker/config.json
• Windows: %USERPROFILE%\.docker\config.json

Die Datei enthält separate Abschnitte für verschiedene Authentifizierungsmethoden:

credHelpers

Wenn Sie Docker Credential Helper für die Authentifizierung verwenden, speichert Container Registry die Einstellungen für die Credential Helper im Abschnitt credHelpers der Datei.

auths

Wenn Sie sich mit Docker mit einem Token oder Dienstkontoschlüssel als Passwort anmelden, speichert Docker Ihre Anmeldedaten im Abschnitt auths der Datei.

credStore

Wenn Sie einen Anmeldedatenspeicher zum Verwalten Ihrer Anmeldedaten konfiguriert haben, befinden sich die Einstellungen für den Anmeldedatenspeicher im Abschnitt credStore der Datei.

Wenn Docker eine Verbindung zu einer Registry herstellt, wird zuerst nach einem Credential Helper gesucht, der dem Host zugeordnet ist. Wenn Ihr config.json also Container Registry-Einstellungen in den Abschnitten credHelpers und auths enthält, werden die Einstellungen im Abschnitt auths ignoriert.

gcloud Credential Helper

Wir empfehlen dringend, diese Methode nach Möglichkeit zu verwenden. Sie bietet kurzlebigen Zugriff auf Ihre Projektressourcen.

Verwenden Sie die gcloud CLI, um die Authentifizierung in Cloud Shell oder in einer Umgebung zu konfigurieren, in der die Google Cloud CLI installiert ist. Cloud Shell enthält eine aktuelle Version von Docker.

So konfigurieren Sie die Authentifizierung:

1. Melden Sie sich in gcloud als Nutzer an, der Docker-Befehle ausführt.

   • Führen Sie den folgenden Befehl aus, um die Authentifizierung mit Nutzeranmeldedaten zu konfigurieren:

     gcloud auth login
     

   • Führen Sie den folgenden Befehl aus, um die Authentifizierung mit Dienstkonto-Anmeldedaten zu konfigurieren:

     gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
     

     Wo

     • ACCOUNT ist der Name des Dienstkontos im Format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com. Sie können vorhandene Dienstkonten auf der Seite Dienstkonten der Google Cloud Console oder mit dem Befehl gcloud iam service-accounts list aufrufen.
     • KEY-FILE ist die Dienstkonto-Schlüsseldatei. Informationen zum Erstellen eines Schlüssels finden Sie in der Dokumentation zur Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM).
   Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.

2. Konfigurieren Sie Docker mit dem folgenden Befehl:

   gcloud auth configure-docker
   

   Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

Hinweis: Wenn Sie normalerweise Docker-Befehle unter Linux mit sudo ausführen, sucht Docker in /root/.docker/config.json statt in $HOME/.docker/config.json nach Container Registry-Anmeldedaten. Wenn Sie sudo mit docker-Befehlen anstelle der Docker-Sicherheitsgruppe verwenden möchten, konfigurieren Sie die Anmeldedaten stattdessen mit sudo gcloud auth configure-docker.

Eigenständiger Credential Helper

Der eigenständige Docker Credential Helper konfiguriert Docker für die Authentifizierung. in Container Registry auf einem System übertragen, in dem die gcloud CLI nicht verfügbar ist.

Credential Helper ruft Ihre Container Registry-Anmeldedaten ab. Dies geschieht entweder automatisch oder von einem mit dem Flag --token-source angegebenen Speicherort. Dann schreibt er die Daten in die Konfigurationsdatei von Docker. Auf diese Weise können Sie das docker-Befehlszeilentool von Docker verwenden, um direkt mit Container Registry zu interagieren.

So konfigurieren Sie die Authentifizierung:

1. Melden Sie sich auf dem Computer als der Nutzer an, der Docker-Befehle ausführt.

2. Laden Sie docker-credential-gcr aus GitHub unter "Releases" herunter:

   Sie können optional das curl-Befehlszeilentool verwenden. Beispiel:

   VERSION=2.1.23
   OS=linux  # or "darwin" for OSX, "windows" for Windows.
   ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
   
   curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
   | tar xz docker-credential-gcr \
   && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
   

3. Konfigurieren Sie Docker mit dem folgenden Befehl:

   docker-credential-gcr configure-docker
   

   Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

Weitere Informationen finden Sie in der Dokumentation zum eigenständigen Docker-Credential Helper auf GitHub.

Hinweis Wenn Sie normalerweise Docker-Befehle unter Linux mit sudo ausführen, sucht Docker in /root/.docker/config.json statt in $HOME/.docker/config.json nach Container Registry-Anmeldedaten. Wenn Sie sudo mit docker-Befehlen anstelle der Docker-Sicherheitsgruppe verwenden möchten, konfigurieren Sie die Anmeldedaten stattdessen mit sudo docker-credential-gcr configure-docker.

Docker ist jetzt für die Authentifizierung bei Container Registry konfiguriert. Um Images hoch- und herunterladen zu können, müssen die Berechtigungen richtig konfiguriert sein.

Zugriffstoken

Sie können ein kurzlebiges OAuth-Zugriffstoken generieren, um sich bei Container Registry zu authentifizieren. Da das Token 60 Minuten lang gültig ist, sollten Sie es weniger als eine Stunde vor dem Herstellen einer Verbindung zu Container Registry anfordern.

1. Erstellen Sie ein neues Dienstkonto, das mit Container Registry interagiert.

   Console

   1. Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.

      Zur Seite "Dienstkonto erstellen"

   2. Wählen Sie das Projekt aus, das Sie verwenden möchten.

   3. Geben Sie im Feld Dienstkontoname einen Namen ein.

   4. Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.

   5. Klicken Sie auf Erstellen.

   6. Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen basierend auf den Berechtigungen, die Sie dem Dienstkonto zuweisen möchten, eine geeignete Cloud Storage-Rolle aus.

   7. Klicken Sie auf Fertig.

   gcloud

   Sie können die folgenden Befehle mit der Google Cloud CLI auf Ihrem lokalen Computer ausführen: oder in Cloud Shell.

   1. Erstellen Sie das Dienstkonto. Ersetzen Sie NAME durch einen Namen für das Dienstkonto.

      gcloud iam service-accounts create NAME

   2. Weisen Sie dem Dienstkonto die Rolle zu. Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID und ROLE durch die entsprechende Cloud Storage-Rolle für das Dienstkonto. Diese Rolle gilt für alle Repositories im Projekt. Sie können die Rolle später ändern und dem Dienstkonto für bestimmte Repositories auch verschiedene Rollen zuweisen.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

2. Rufen Sie einen Schlüssel für das Dienstkonto ab, das mit Container Registry interagiert.

   Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.

   Console

   1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.

      Zur Seite „Dienstkonten“

   2. Klicken Sie auf die E-Mail-Adresse des Dienstkontos, das Sie nutzen möchten.

   3. Klicken Sie auf Schlüssel.

   4. Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.

   5. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

      In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für diese Schlüsseldatei verwendet.

   6. Klicken Sie auf Schließen.

   gcloud

   Sie können den folgenden Befehl mit der Google Cloud CLI auf Ihrem lokalen Computer ausführen: oder in Cloud Shell.

   In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für die Schlüsseldatei verwendet.

   gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

3. Führen Sie den folgenden Befehl aus, um sich in der Google Cloud CLI als Dienstkonto anzumelden.

   gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
   

   Dabei gilt:

   • ACCOUNT ist der Name des Dienstkontos im Format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
   • KEY-FILE ist die Dienstkonto-Schlüsseldatei. Weitere Informationen zum Erstellen eines Schlüssels erhalten Sie in der IAM-Dokumentation.

4. Prüfen Sie, ob die Berechtigungen für das Dienstkonto ordnungsgemäß konfiguriert sind. Wenn Sie das Compute Engine-Dienstkonto verwenden, müssen Sie sowohl Berechtigungen als auch Zugriffsbereiche richtig konfigurieren.

5. Rufen Sie ein Zugriffstoken für das Dienstkonto ab. Da das Token nur kurzlebig ist, fordern Sie es innerhalb von weniger als einer Stunde an, bevor Sie es zur Verbindung mit Container Registry verwenden.

   Führen Sie dazu diesen Befehl aus:

   Linux

   gcloud auth print-access-token | docker login -u oauth2accesstoken \
       --password-stdin https://HOSTNAME
   

   Windows

   gcloud auth print-access-token |
       docker login -u oauth2accesstoken --password-stdin https://HOSTNAME
   

   Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

   Hinweis: Google Cloud-Dienste, die Images in der Subdomain gcr.io bereitstellen, erfordern möglicherweise eine Authentifizierung. Beispielsweise müssen Sie sich bei marketplace.gcr.io authentifizieren, um Images von Google Cloud Marketplace herunterladen zu können.

Docker ist jetzt bei Container Registry authentifiziert.

JSON-Schlüsseldatei

Ein Dienstkontoschlüssel ist ein langlebiges Schlüsselpaar, das Sie als Anmeldedaten für ein Dienstkonto verwenden können. Im Gegensatz zum OAuth-Zugriffstoken läuft ein Dienstkontoschlüssel nicht ab.

Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.

Jeder, der Zugriff auf einen gültigen privaten Schlüssel für ein Dienstkonto hat, kann über das Dienstkonto auf Ressourcen zugreifen. Beispielsweise erhalten einige von Google Cloud automatisch erstellte Dienstkonten wie das Container Registry-Dienstkonto die Rolle Editor mit Lese- und Schreibberechtigungen für das übergeordnete Projekt. Das Compute Engine-Standarddienstkonto ist mit schreibgeschütztem Zugriff auf den Speicher innerhalb desselben Projekts konfiguriert.

Beachten Sie darüber hinaus, dass der Lebenszyklus des Schlüsselzugriffs auf das Dienstkonto (und damit die Daten, auf die das Dienstkonto Zugriff hat) vom Lebenszyklus des Nutzers unabhängig ist, der den Schlüssel heruntergeladen hat.

Richten Sie sich nach den folgenden Richtlinien, um den Zugriff auf Ihre Container-Images zu beschränken:

• Erstellen Sie dedizierte Dienstkonten, die nur für die Interaktion mit Container Registry verwendet werden.
• Gewähren Sie die Rolle mit dem geringstmöglichen Zugriff, den das Dienstkonto benötigt.
• Folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.

So erstellen Sie ein neues Dienstkonto und einen Dienstkontoschlüssel nur für die Verwendung mit Container Registry-Repositories:

1. Erstellen Sie ein neues Dienstkonto, das mit Container Registry interagiert.

   Console

   1. Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.

      Zur Seite "Dienstkonto erstellen"

   2. Wählen Sie das Projekt aus, das Sie verwenden möchten.

   3. Geben Sie im Feld Dienstkontoname einen Namen ein.

   4. Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.

   5. Klicken Sie auf Erstellen.

   6. Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen eine geeignete Cloud Storage-Rolle für das Dienstkonto aus.

   7. Klicken Sie auf Fertig.

   gcloud

   Sie können die folgenden Befehle mit der Google Cloud CLI auf Ihrem lokalen Computer ausführen: oder in Cloud Shell.

   1. Erstellen Sie das Dienstkonto. Ersetzen Sie NAME durch einen Namen für das Dienstkonto.

      gcloud iam service-accounts create NAME

   2. Weisen Sie dem Dienstkonto die Rolle zu. Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID und ROLE durch die entsprechende Cloud Storage-Rolle für das Dienstkonto.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

2. Rufen Sie einen Schlüssel für das Dienstkonto ab, das mit Container Registry interagiert.

   Console

   1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.

      Zur Seite „Dienstkonten“

   2. Klicken Sie auf die E-Mail-Adresse des Dienstkontos, das Sie nutzen möchten.

   3. Klicken Sie auf Schlüssel.

   4. Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.

   5. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

      In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für diese Schlüsseldatei verwendet.

   6. Klicken Sie auf Schließen.

   gcloud

   Sie können den folgenden Befehl mit der Google Cloud CLI auf Ihrem lokalen Computer ausführen: oder in Cloud Shell.

   In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für die Schlüsseldatei verwendet.

   gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

3. Prüfen Sie, ob die Berechtigungen für das Dienstkonto ordnungsgemäß konfiguriert sind. Wenn Sie das Compute Engine-Dienstkonto verwenden, müssen Sie sowohl Berechtigungen als auch Zugriffsbereiche richtig konfigurieren.

4. Verwenden Sie den Dienstkontoschlüssel als Passwort für die Authentifizierung bei Docker.

   Linux/macOS

   cat KEY-FILE | docker login -u _json_key --password-stdin \
   https://HOSTNAME
   

   Windows

   Get-Content KEY-FILE |
   docker login -u _json_key --password-stdin https://HOSTNAME
   

   Ersetzen Sie Folgendes:

   • KEY-FILE ist der Name der Dienstkonto-Schlüsseldatei im JSON-Format.
   • HOSTNAME ist gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.
   Hinweis: Google Cloud-Dienste, die Bilder in einem gcr.io bereitstellen Für die Subdomain ist möglicherweise eine Authentifizierung erforderlich. Beispielsweise müssen Sie sich bei marketplace.gcr.io authentifizieren, um Images von Google Cloud Marketplace herunterladen zu können.

Docker ist jetzt bei Container Registry authentifiziert.