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. Das Konto, das Sie für die Authentifizierung verwenden, muss Berechtigungen für den Zugriff auf die Registry haben. Wir empfehlen die Verwendung eines Dienstkontos anstelle eines Nutzerkontos. Dienstkonten sind keinem bestimmten Nutzer zugeordnet. Google Cloud-Anwendungen können mit dem Konzept der Standardanmeldedaten für Anwendungen die Anmeldedaten automatisch abrufen.

  2. Installieren Sie die neueste Version des Cloud SDK. Führen Sie den Befehl gcloud components update aus, um eine vorhandene Installation zu aktualisieren.

  3. Für Docker müssen sich Credential Helper im System-PATH befinden. Prüfen Sie, ob der Befehl gcloud im System PATH ist.

  4. Installieren Sie Docker, falls es noch nicht installiert ist.

  5. Docker benötigt für die Interaktion mit Registries Zugriff. Wenn Sie Docker unter Linux oder Windows installieren, fügen Sie den Nutzer, den Sie zum Ausführen von Docker-Befehlen verwenden, der Docker-Sicherheitsgruppe hinzu.

    Unter MacOS wird Docker auf einer virtuellen Maschine mit dem Root-Nutzer ausgeführt. Dieser Schritt ist daher nicht erforderlich. Weitere Informationen zu Docker unter MacOS finden Sie in der Docker-Dokumentation.

    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.

Authentifizierungsmethoden

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

Die folgenden Authentifizierungsmethoden sind verfügbar:

gcloud als 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 Docker Credential Helper
Diese Option dient hauptsächlich zur Konfiguration Ihrer Anmeldedaten zur Verwendung mit Docker, wenn kein Cloud SDK 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 sicherste 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. Wenn Sie einen Dienstkontoschlüssel verwenden müssen, folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.

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.

Credential Helper

Docker Credential Helper konfigurieren Docker für die Authentifizierung mit einer bestimmten Registry. Container Registry bietet:

  • Einen gcloud-Credential Helper
  • Ein eigenständiger Credential Helper für Systeme, in denen das Cloud SDK nicht verfügbar ist

gcloud als Docker Credential Helper

Wir empfehlen dringend, diese Methode nach Möglichkeit zu verwenden. Sie gewährleistet sicheren Zugriff auf Ihre Projektressourcen für beschränkte Zeit.

Verwenden Sie gcloud, um die Authentifizierung in Cloud Shell oder in einer Umgebung zu konfigurieren, in der das Cloud SDK 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
      

      Dabei gilt:

  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

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.

Eigenständiger Docker Credential Helper

Der eigenständige Docker Credential Helper konfiguriert Docker für die Authentifizierung bei Container Registry auf einem System, auf dem das Cloud SDK 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.0.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
    
  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.

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

Ein Zugriffstoken sind kurzlebige Anmeldedaten, die Zugriff auf Ihre Google Cloud-Ressourcen ermöglicht. Sie können ein Zugriffstoken als Passwort verwenden, um eine Verbindung zu Container Registry herzustellen.

Google Cloud ruft ein Zugriffstoken mit den Standardanmeldedaten für Anwendungen ab.

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

    Console

    1. Öffnen Sie in der Google Cloud Console die Seite Dienstkontoschlüssel erstellen.

      Zur Seite Dienstkontoschlüssel erstellen

    2. Wählen Sie aus der Liste "Dienstkonto" das Dienstkonto aus, das Sie verwenden möchten.

      Wählen Sie zum Erstellen eines neuen Dienstkontos Neues Dienstkonto aus und geben Sie den Dienstkontonamen, die ID und die entsprechende Container Registry-Rolle entsprechend den Berechtigungen an, die Sie für das Dienstkonto gewähren möchten.

    3. Wählen Sie JSON als Schlüsseltyp aus.

    4. 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.

    gcloud

    Sie können die folgenden Befehle mit dem Cloud SDK auf Ihrem lokalen Rechner oder in Cloud Shell ausführen.

    1. Erstellen Sie das Dienstkonto. Ersetzen Sie NAME mit einem Namen für das Dienstkonto.

      gcloud iam service-accounts create NAME
      
    2. Gewähren Sie dem Dienstkonto Berechtigungen. Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID und ROLE durch die entsprechende Container Registry-Rolle für das Dienstkonto. Diese Rolle gilt für alle Repositories im Projekt. Sie können die Rolle später ändern und verschiedene Berechtigungen für das Dienstkonto für bestimmte Repositories festlegen.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Erstellen Sie die Schlüsseldatei. 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
      
  2. Führen Sie den folgenden Befehl aus, um sich beim Cloud SDK 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 Schlüsseldatei des Dienstkontos. Weitere Informationen zum Erstellen eines Schlüssels erhalten Sie in der IAM-Dokumentation.
  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. 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.

    Linux/macOS

    • Nutzername ist oauth2accesstoken.
    • Passwort ist Ihr Zugriffstoken. Beispiel: gcloud auth print-access-token

    Beispiel:

    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.

    Alternative für ältere Docker-Clients, die --password-stdin nicht unterstützen:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]
    

    Windows

    • Nutzername ist oauth2accesstoken.
    • Passwort ist die Ausgabe von gcloud auth print-access-token.
    1. Rufen Sie das Zugriffstoken ab.
    gcloud auth print-access-token
    

    Der zurückgegebene String ist das Zugriffstoken, das Sie als Passwort verwenden. In diesem Beispiel steht ya29.8QEQIfY_... für das zurückgegebene Zugriffstoken.

    ya29.8QEQIfY_...
    
    1. Melden Sie sich mit dem Zugriffstoken an.
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]
    

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

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. Sie sind für die Sicherheit des privaten Schlüssels und andere Schlüsselverwaltungsvorgänge wie die Schlüsselrotation verantwortlich.

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:

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

  1. Erstellen Sie das Dienstkonto für die Interaktion mit Repositories:

    Console

    1. Öffnen Sie in der Google Cloud Console die Seite Dienstkontoschlüssel erstellen.

      Zur Seite Dienstkontoschlüssel erstellen

    2. Wählen Sie aus der Liste "Dienstkonto" die Option Neues Dienstkonto aus.

    3. Geben Sie im Feld Name des Dienstkontos einen Namen ein.

    4. Wählen Sie aus der Liste Rolle die entsprechende Container Registry-Rolle für das Dienstkonto aus.

    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.

    gcloud

    Sie können die folgenden Befehle mit dem Cloud SDK auf Ihrem lokalen Rechner oder in Cloud Shell ausführen.

    1. Erstellen Sie das Dienstkonto. Ersetzen Sie NAME mit einem Namen für das Dienstkonto.

      gcloud iam service-accounts create NAME
      
    2. Gewähren Sie dem Dienstkonto Berechtigungen. Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID und ROLE durch die entsprechende Rolle für das Dienstkonto.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Erstellen Sie die Schlüsseldatei. In diesem Beispiel lautet der Name der Ausgabeschlüsseldatei keyfile.json.

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. 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.

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

    Linux/macOS

    • Nutzername ist _json_key (NICHT der Name Ihres Dienstkontos).
    • keyfile.json ist der von Ihnen erstellte Dienstkontoschlüssel.

    Beispiel:

    cat keyfile.json | docker login -u _json_key --password-stdin https://[HOSTNAME]
    

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

    Alternative für ältere Docker-Clients, die --password-stdin nicht unterstützen:

    docker login -u _json_key -p "$(cat keyfile.json)" https://[HOSTNAME]
    

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

    Windows

    • Nutzername ist _json_key (NICHT der Name Ihres Dienstkontos).
    • keyfile.json enthält den JSON-Schlüssel des Dienstkontos.

    Beispiel:

    docker login -u _json_key --password-stdin https://[HOSTNAME] < keyfile.json
    

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

    Alternative für ältere Docker-Clients, die --password-stdin nicht unterstützen:

    set /p PASS=<keyfile.json
    docker login -u _json_key -p "%PASS%" https://[HOSTNAME]
    

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

Docker ist jetzt bei Container Registry authentifiziert.