Standardanmeldedaten für Anwendungen einrichten

Auf dieser Seite wird beschrieben, wie Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zur Verwendung durch Cloud-Clientbibliotheken, Google API-Clientbibliotheken sowie die REST API und die RPC API in verschiedenen Umgebungen bereitstellen. Zum Einrichten von ADC stellen Sie Anmeldedaten für ADC in der Umgebung bereit, in der Ihr Code ausgeführt wird.

Application Default Credentials (ADC) ist eine Strategie, die von den Google-Authentifizierungsbibliotheken verwendet wird, um Anmeldedaten automatisch basierend auf der Anwendungsumgebung zu finden. Die Authentifizierungsbibliotheken stellen diese Anmeldedaten für Cloud-Clientbibliotheken und Google API-Clientbibliotheken zur Verfügung. Wenn Sie ADC verwenden, kann Ihr Code in einer Entwicklungs- oder Produktionsumgebung ausgeführt werden, ohne dass sich die Authentifizierung Ihrer Anwendung bei Google Cloud-Diensten und APIs ändert.

Informationen dazu, wo ADC nach Anmeldedaten sucht und in welcher Reihenfolge dies geschieht, finden Sie unter Funktionsweise von Standardanmeldedaten für Anwendungen.

Wenn Sie API-Schlüssel verwenden, müssen Sie ADC nicht einrichten. Weitere Informationen finden Sie unter API-Schlüssel verwenden.

Anmeldedaten für ADC bereitstellen

Wählen Sie die Umgebung aus, in der Ihr Code ausgeführt wird:

Lokale Entwicklungsumgebung

Sie können entweder Ihre Nutzeranmeldedaten oder die Anmeldedaten für das Dienstkonto in ADC in einer lokalen Entwicklungsumgebung angeben.

Nutzeranmeldedaten

Wenn Ihr Code in einer lokalen Entwicklungsumgebung ausgeführt wird, z. B. auf einer Entwicklungs-Workstation, empfiehlt es sich, die mit Ihrem Nutzerkonto verknüpften Anmeldedaten zu verwenden.

Wenn Sie ADC mit Ihrem Nutzerkonto konfigurieren, sollten Sie sich der folgenden Fakten bewusst sein:

  • Die ADC-Konfiguration mit einem Nutzerkonto funktioniert möglicherweise für einige Methoden und APIs wie die Cloud Translation API oder die Cloud Vision API ohne zusätzliche Parameter oder Konfiguration möglicherweise nicht. Wenn Sie eine Fehlermeldung erhalten, dass die API nicht im Projekt aktiviert ist oder kein Kontingentprojekt verfügbar ist, lesen Sie die Fehlerbehebung für die ADC-Einrichtung.

  • Die lokale ADC-Datei enthält Ihr Aktualisierungstoken. Jeder Nutzer mit Zugriff auf Ihr Dateisystem kann damit ein gültiges Zugriffstoken abrufen. Wenn Sie diese lokalen Anmeldedaten nicht mehr benötigen, können Sie sie mit dem Befehl gcloud auth application-default revoke widerrufen.

  • Ihre lokale ADC-Datei ist mit Ihrem Nutzerkonto verknüpft, nicht mit der gcloud CLI-Konfiguration. Eine Änderung der Konfiguration in eine andere gcloud CLI kann die von der gcloud CLI verwendete Identität ändern. Dies wirkt sich jedoch nicht auf Ihre lokale ADC-Datei oder die ADC-Konfiguration aus.

  • Standardmäßig enthalten die Zugriffstokens, die aus einer mit Nutzeranmeldedaten erstellten lokalen ADC-Datei generiert wurden, den cloudweiten Bereich https://www.googleapis.com/auth/cloud-platform. Um Bereiche explizit anzugeben, verwenden Sie das Flag –scopes mit dem Befehl gcloud auth application-default login.

    Wenn Sie Bereiche für Dienste außerhalb von Google Cloud wie Google Drive hinzufügen möchten, erstellen Sie eine OAuth-Client-ID und geben diese mit dem –client-id-file-Flag an den gcloud auth application-default login-Befehl weiter, wobei Sie Ihre Bereiche mit dem –scopes-Flag angeben.

Wie Sie ADC mit Ihrem Nutzerkonto konfigurieren, hängt davon ab, ob Ihr Nutzerkonto von Google verwaltet wird, also ein Google-Konto ist, oder von einem anderen Identitätsanbieter (Identity Provider, IdP) verwaltet wird und mithilfe der Workforce Identity-Föderation föderiert wird.

ADC mit Ihrem Google-Konto konfigurieren

Verwenden Sie die Google Cloud CLI, um ADC mit einem Google-Konto zu konfigurieren:

  1. Installieren und initialisieren Sie die gcloud CLI.

    Achten Sie bei der Initialisierung der gcloud CLI auf ein Google Cloud-Projekt, in dem Sie die Berechtigung für den Zugriff auf die Ressourcen haben, die Ihre Anwendung benötigt.

  2. Konfigurieren Sie ADC:

    gcloud auth application-default login

    Ein Anmeldebildschirm wird angezeigt. Nach der Anmeldung werden Ihre Anmeldedaten in der lokalen Anmeldedatendatei für ADC gespeichert.

ADC mit einem von einem externen IdP verwalteten Konto konfigurieren

So konfigurieren Sie ADC für ein Nutzerkonto, das von einem externen IdP verwaltet und mit der Workforce Identity-Föderation föderiert ist:

  1. Mitarbeiteridentitätsföderation konfigurieren

    Weitere Informationen finden Sie unter Mitarbeiteridentitätsföderation konfigurieren.

  2. Konfigurieren Sie die gcloud CLI für die Verwendung der Workforce Identity-Föderation.

    Weitere Informationen finden Sie unter Externe Anmeldedaten gegen ein Google Cloud-Zugriffstoken austauschen.

  3. Konfigurieren Sie ADC:

    gcloud auth application-default login

    Ein Anmeldebildschirm wird angezeigt. Nach der Anmeldung werden Ihre Anmeldedaten in der lokalen Anmeldedatendatei für ADC gespeichert.

Dienstkonto-Anmeldedaten

Sie können ADC mit Anmeldedaten aus einem Dienstkonto einrichten. Verwenden Sie dazu die Identitätsübernahme des Dienstkontos oder einen Dienstkontoschlüssel.

Identitätsübertragung für ein Dienstkonto

Sie können den Identitätswechsel für ein Dienstkonto verwenden, um eine lokale ADC-Datei (Standardanmeldedaten für Anwendungen) einzurichten. Clientbibliotheken, die den Identitätswechsel unterstützen, können diese Anmeldedaten automatisch verwenden. Lokale ADC-Dateien, die mit Identitätswechsel erstellt wurden, werden in den folgenden Sprachen unterstützt:

  • C#
  • Go
  • Java
  • Node.js
  • Python

Sie benötigen die IAM-Rolle Dienstkonto-Ersteller (roles/iam.serviceAccountTokenCreator) für das Dienstkonto, dessen Identität Sie übernehmen. Weitere Informationen finden Sie unter Erforderliche Rollen.

Verwenden Sie die Identität des Dienstkontos, um eine lokale ADC-Datei zu erstellen: 

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Sie können jetzt Clientbibliotheken mit den unterstützten Sprachen auf die gleiche Weise verwenden wie nach dem Einrichten einer lokalen ADC-Datei mit Nutzeranmeldedaten. Anmeldedaten werden von den Authentifizierungsbibliotheken automatisch gefunden. Weitere Informationen finden Sie unter Für die Verwendung von Clientbibliotheken authentifizieren.

Dienstkontoschlüssel

Wenn Sie kein Nutzerkonto oder Identitätsübernahme eines Dienstkontos für die lokale Entwicklung verwenden können, können Sie einen Dienstkontoschlüssel verwenden.

So erstellen Sie einen Dienstkontoschlüssel und stellen ihn für ADC bereit:

  1. Erstellen Sie ein Dienstkonto mit den Rollen, die Ihre Anwendung benötigt, sowie einen Schlüssel für dieses Dienstkonto. Folgen Sie dazu der Anleitung unter Dienstkontoschlüssel erstellen.

  2. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

Cloudbasierte Entwicklungsumgebung von Google Cloud

Wenn Sie eine cloudbasierte Google Cloud-Entwicklungsumgebung wie Cloud Shell oder Cloud Code verwenden, verwendet das Tool die bei der Anmeldung angegebenen Anmeldedaten und verwaltet die erforderlichen Autorisierungen. In diesen Umgebungen können Sie mit der gcloud CLI nicht ADC konfigurieren. Wenn Sie ein anderes Nutzerkonto zur Konfiguration von ADC verwenden oder ADC mithilfe eines Dienstkontos konfigurieren müssen, verwenden Sie eine lokale Entwicklungsumgebung oder eine Google Cloud-Computing-Ressource als Entwicklungsumgebung.

Google Cloud-Dienste, die das Anhängen eines Dienstkontos unterstützen

Einige Google Cloud-Dienste wie Compute Engine, App Engine und Cloud Functions unterstützen das Anhängen eines nutzerverwalteten Dienstkontos an einige Ressourcentypen. Im Allgemeinen wird das Anhängen eines Dienstkontos unterstützt, wenn die Ressourcen dieses Dienstes ausgeführt oder Anwendungscode enthalten können. Wenn Sie ein Dienstkonto an eine Ressource anhängen, kann der Code, der auf der Ressource ausgeführt wird, dieses Dienstkonto als Identität verwenden.

Zum Anhängen von Anmeldedaten an ADC für den in Google Cloud ausgeführten Produktionscode sollten Sie das Anhängen eines nutzerverwalteten Dienstkontos bevorzugen.

Informationen zum Ermitteln der Rollen, die Sie für Ihr Dienstkonto bereitstellen müssen, finden Sie unter Vordefinierte Rollen auswählen.

Informationen dazu, welche Ressourcen Sie an ein Dienstkonto anhängen können, und Hilfe beim Anhängen des Dienstkontos an die Ressource finden Sie in der IAM-Dokumentation zum Anhängen eines Dienstkontos.

Set up authentication:

  1. Create the service account: 

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Replace SERVICE_ACCOUNT_NAME with a name for the service account.

  2. To provide access to your project and your resources, grant a role to the service account: 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID." --role=ROLE

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • ROLE: the role to grant
  3. To grant another role to the service account, run the command as you did in the previous step.

  4. Grant the required role to the principal that will attach the service account to other resources. 

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID. --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • USER_EMAIL: the email address for a Google Account

GKE oder GKE Enterprise

Die Authentifizierung für containerisierte Anwendungen, die in GKE oder GKE Enterprise ausgeführt werden, wird zwischen lokalen Testumgebungen und Google Cloud-Umgebungen unterschiedlich behandelt.

Containeranwendungen lokal testen

Zum Testen der Containeranwendung auf Ihrer lokalen Workstation können Sie Container so konfigurieren, dass sie sich mit Ihrer lokalen Anmeldedatendatei authentifizieren. Zum Testen der Container verwenden Sie eine lokale Kubernetes-Implementierung wie minikube und das Add-on gcp-auth.

Containeranwendungen auf Google Cloud ausführen

Sie richten die Authentifizierung für Google Cloud-Containerumgebungen je nach Kontext unterschiedlich ein:

Lokal oder bei einem anderen Cloud-Anbieter

Wenn Sie Ihre Anwendung außerhalb von Google Cloud ausführen, müssen Sie Anmeldedaten angeben, die von Google Cloud erkannt werden, um Google Cloud-Dienste zu verwenden.

Identitätsföderation von Arbeitslasten

Die bevorzugte Methode zur Authentifizierung bei Google Cloud mit Anmeldedaten eines anderen Identitätsanbieters ist die Verwendung einer Workload Identity-Föderation. Sie erstellen eine Konfigurationsdatei für Anmeldedaten und legen die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS fest, die auf ihn verweist. Dieser Ansatz ist sicherer als das Erstellen eines Dienstkontoschlüssels.

Informationen zum Einrichten der Workload Identity-Föderation für ADC finden Sie unter Workload Identity-Föderation mit anderen Clouds.

Dienstkontoschlüssel

Wenn Sie keine Workload Identity-Föderation konfigurieren können, müssen Sie ein Dienstkonto erstellen, ihm die von Ihrer Anwendung benötigten IAM-Rollen zuweisen und einen Schlüssel für das Dienstkonto erstellen.

So erstellen Sie einen Dienstkontoschlüssel und stellen ihn für ADC bereit:

  1. Erstellen Sie ein Dienstkonto mit den Rollen, die Ihre Anwendung benötigt, sowie einen Schlüssel für dieses Dienstkonto. Folgen Sie dazu der Anleitung unter Dienstkontoschlüssel erstellen.

    Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

Nächste Schritte