GCP Authentifizierung: Der ultimative Praxis-Guide für gcloud CLI & Google Cloud ADC
Management Summary
Wenn du mit der Google Cloud Platform arbeitest, triffst du zwangsläufig auf verschiedene Wege zur GCP Authentifizierung. Oft ist auf den ersten Blick nicht klar, welche Methode in welcher Situation die richtige ist. In diesem Artikel geben wir dir einen strukturierten Überblick über alle gcloud Authentifizierungsmethoden, erklären dir das Kernkonzept der zwei Hauptgruppen und zeigen dir direkt im Anschluss an fünf praxisnahen Szenarien, wann du welche Methode am besten einsetzt.
Dieser Artikel bietet Input zu:
Zwei Gruppen der GCP Authentifizierung
Wenn wir über GCP Authentifizierung sprechen, unterscheiden wir grundsätzlich zwei Bereiche: die Authentifizierung für gcloud CLI Befehle und die für deinen Code.
Gruppe 1: gcloud CLI Befehle
Diese erste Gruppe greift bei allen nachfolgenden Befehlen in der gcloud CLI. Ein typisches Beispiel für das Ressourcen-Management ist: gcloud sql instances create …
Gruppe 2: Application Default Credentials (ADC) für Code
Die zweite Gruppe kommt in ganz anderen Situationen zum Einsatz, nämlich wenn dein Code über das Google Cloud SDK kommuniziert. Nutzt du beispielsweise Node.js, lädt das Cloud Storage SDK im Hintergrund die google-auth-library. Diese nutzt dann deinen Google Cloud ADC User für die GCP Authentifizierung.
Die folgende Code-Zeile importiert den Google Cloud Storage Client, der sich automatisch auf den ADC-Workflow verlässt. So wird deine Anwendung authentifiziert, ohne dass du Zugangsdaten fest einkodieren musst:
const { Storage } = require('@google-cloud/storage');
Zusätzlich wird diese Methode auch von Terraform verwendet. Ein Befehl wie terraform apply führt Änderungen ebenfalls auf Basis der Google Cloud ADC aus. Diese beiden Gruppen decken zwar nicht zu 100 % alle Sonderfälle ab, beinhalten aber die wichtigsten Szenarien.
Ausnahmen und Spezialfälle
Ein interessanter Fall ist der Cloud SQL Proxy. Führst du ihn über die gcloud CLI aus (
gcloud alpha cloud-sql proxy …
, wird der über gcloud auth login
authentifizierte User verwendet. Startest du ihn jedoch über die lokale Binary
cloud-sql-proxy my-project:us-central1:my-db-instance
startet der Google Cloud ADC Workflow.
Ein weiteres gutes Beispiel ist die VS Code Extension „Cloud Code“ von Google. Intuitiv würdest du vielleicht erwarten, dass hier gcloud CLI Befehle und damit der gcloud-Nutzer zum Einsatz kommen. Tatsächlich laufen im Hintergrund aber Skaffold und gcloud CLI Befehle ab, weshalb auch diese Extension auf Google Cloud ADC setzt.
| ID | Used by | Description | Activation | Human / SA |
|---|---|---|---|---|
| 1 | gcloud commands | gcloud user | gcloud auth login | Human |
| 2 | gcloud commands | gcloud SA impersonation | gcloud config set auth/impersonate_service_account=… | SA |
| 3 | gcloud commands | gcloud SA key-file | gcloud auth activate-service-account –key-file=… | SA |
| 4 | gcloud commands | gcloud SA impersonation (one time) | gcloud … –impersonate-service-account=… (can be used for any gcloud command) | SA |
| 5 | Code | ADC user | gcloud auth application-default login | Human |
| 6 | Code | ADC SA impersonation | gcloud auth application-default login –impersonate-service-account=… | SA |
| 7 | Code | ADC SA key-file | GOOGLE_APPLICATION_CREDENTIALS=/path/key.json | SA |
| ID | Storage Location (Linux) | Parallel usage in different terminals possible? | Stored in gcloud config? |
|---|---|---|---|
| 1 | ~/.config/gcloud/credentials.db | No (global) | No |
| 2 | ~/.config/gcloud/configurations/* | No (global) | Yes (gcloud config …) |
| 3 | ~/.config/gcloud/credentials.db | No (global) | No |
| 4 | Not stored locally | Yes (per process) | No |
| 5 | ~/.config/gcloud/application_default_credentials.json | No (global) | No |
| 6 | ~/.config/gcloud/application_default_credentials.json | No (global) | No |
| 7 | Any file path | Yes (per terminal) | No |
Abbreviations / Abkürzungen
- SA… Service Account
- ADC… Application Default Credentials (see our previous article on Google APIs and service account impersonation)
Takeaways
Die GCP Authentifizierung ist weitaus strukturierter, als es anfangs scheint. Die wichtigsten Takeaways für dich:
- Zwei unabhängige Gruppen: Die gcloud CLI Methoden (IDs 1–4) und die Google Cloud ADC Methoden für Code (IDs 5–7) arbeiten unabhängig voneinander. Du kannst in beiden Gruppen gleichzeitig unterschiedliche aktive Identitäten haben.
- Bevorzuge Impersonation statt Key-Files: Service Account impersonation (IDs 2, 4, 6) ist immer die sicherere Wahl im Vergleich zu statischen JSON-Key-Files (IDs 3, 7). Key-Files solltest du nur dann nutzen, wenn Workload Identity Federation nicht möglich ist.
- Achte auf Überraschungen: Tools wie die eigenständige Cloud SQL Proxy Binary und die VS Code Cloud Code Extension nutzen Google Cloud ADC, selbst wenn du intuitiv die gcloud CLI Nutzer-Authentifizierung erwarten würdest.
- ID 7 erlaubt parallele Nutzung: Im Gegensatz zu den meisten anderen Methoden ist GOOGLE_APPLICATION_CREDENTIALS eine Umgebungsvariable pro Terminal. Du kannst also in verschiedenen Terminals gleichzeitig auf unterschiedliche Key-Files verweisen.
Im nächsten Abschnitt wenden wir diese Methoden anhand konkreter Anwendungsfälle in der Praxis an – von der anfänglichen Einrichtung der Infrastruktur bis hin zur Bereitstellung in der Produktion.
GCP Authentifizierung in der Praxis: 5 Use Cases
Die Theorie steht. Schauen wir uns nun an fünf konkreten Szenarien an, welche Methode in den einzelnen Phasen eines realen Projekts zum Einsatz kommen sollte – von der ersten Einrichtung der Infrastruktur bis hin zur Produktionsbereitstellung auf einer Hosting-Plattform eines Drittanbieters.
Am Beispiel eines Tech Leads und eines Entwicklers, die eine Cloud Run Anwendung mit Cloud SQL-Datenbank aufsetzen, zeigen wir, wie verschiedene Authentifizierungsmethoden über den gesamten Projektlebenszyklus hinweg zusammenspielen: von der initialen Infrastruktur-Einrichtung (ID 5), über das erste Ressourcen-Setup via gcloud CLI (ID 1), die lokale Entwicklung mit Service Account impersonation (ID 6), die einmalige Impersonation für das Deployment (ID 4), persistente Impersonation für das Debugging (ID 2), on-premises CI/CD mit einem Key-File (ID 3), bis hin zum externen Hosting auf einer Drittanbieter-Plattform (ID 7). Eine Übersicht am Ende zeigt dir, wie du den jeweiligen Authentifizierungsstatus prüfen und zurücksetzen kannst.
Use Case 1: Node.js App auf Cloud Run mit lokaler Entwicklung [ID 1], [ID 4], [ID 6]
Das Szenario: Ein Entwickler baut und deployt eine Node.js/Express-Anwendung auf Cloud Run, angebunden an eine Cloud SQL Datenbank. Über den Entwicklungszyklus hinweg kommen drei Methoden zur GCP Authentifizierung zum Einsatz: ein persönlicher gcloud CLI Nutzer für das erste Ressourcen-Setup, Google Cloud ADC Service Account impersonation für lokale Tests (um die produktive Laufzeitidentität exakt abzubilden) sowie eine einmalige Service Account impersonation für das Deployment – so bleibt die lokale ADC-Konfiguration völlig unangetastet.
Die beteiligten Personen:
- Mark Sudo (Tech Lead)
- Project Owner: Benötigt, um Service Accounts (SAs) zu erstellen, IAM-Rollen zuzuweisen und die volle administrative Kontrolle über das Projekt zu behalten.
- Billing Account Administrator: Erforderlich, um das GCP-Projekt mit einem Rechnungskonto zu verknüpfen (zwingend nötig für kostenpflichtige Services wie Cloud SQL oder Cloud Run).
- John Doe (Entwickler)
- Project Viewer: Erlaubt ihm, Ressourcen in der Google Cloud Console zu durchsuchen und den Projektstatus zu überwachen.
- Cloud Run Admin & Cloud SQL Admin: Notwendig, um die Cloud Run Services sowie die Cloud SQL Instanz, Datenbanken und User beim initialen Setup anzulegen.
- SA Token Creator (für beide SAs): Essenziell für die Service Account impersonation bei lokalen Tests, da er so kurzlebige Credentials für die SAs generieren kann.
- Service Account User: Erforderlich, um den App_SA während des Setups an den Cloud Run Service anzuhängen, damit der Service unter dieser Identität läuft.
Die eingesetzten Service Accounts (SAs):
- App_SA (Laufzeitidentität für die Cloud Run App)
- Cloud SQL Instance User: Nötig, um sich über die IAM-Datenbankauthentifizierung (statt mit einem statischen Passwort) an der Datenbank anzumelden.
- Cloud SQL Client: Wird für die sichere Verbindung zur Cloud SQL Instanz benötigt (z. B. via Cloud SQL Auth Proxy).
- Logging Log Writer: Erlaubt der Anwendung, ihre Logs direkt in Google Cloud Logging zu schreiben.
- Deployment_SA (Identität für CI/CD Pipelines & Deployments)
- Service Account User (beschränkt auf App_SA): Zwingend nötig, um neue Cloud Run Revisionen zu deployen.
- Cloud Build Editor & Artifact Registry Writer: Um Cloud Build Jobs zu triggern und das fertige Docker-Image in die Artifact Registry zu pushen.
- Cloud Run Developer & Storage Object Admin: Um die neue Revision auf Cloud Run zu deployen und Quellcode in den Staging-Bucket hochzuladen.
Die Architektur im Überblick:
- Frontend: React + Nutzerverwaltung für To-Dos.
- Backend: Node.js/Express, gehostet in Cloud Run + Verbindung zur Cloud SQL Datenbank.
- Cloud Run: Wird über den App_SA ausgeführt. Cloud Run sucht via Google Cloud ADC nach dem passenden Account, findet den App_SA und nutzt diesen.
Schritt-für-Schritt Ablauf:
Schritt 1: Vorbereitung
Mark Sudo erstellt die Service Accounts und weist allen Accounts die nötigen IAM-Rollen zu. Er achtet auf eine saubere Trennung zwischen Menschen und SAs. John Doe übernimmt die Admin-Aufgaben, die Ausführung der App erfolgt durch den App_SA und das Deployment durch den Deployment_SA.
Schritt 2: Setup
John Doe loggt sich ein und erstellt alle notwendigen Ressourcen mit seinem persönlichen Nutzerkonto.
gcloud auth login # All following gcloud commands will use John Doe's personal user [ID 1]
gcloud sql instances create ... # Create Cloud SQL instance, database etc.
Schritt 3: Lokales Testing
John Doe schreibt die Express-App und richtet die Verbindung zur Cloud SQL Datenbank ein. Anschließend startet er die App lokal via Service Account impersonation. Der Gedanke dahinter: Auf der lokalen Workstation des Entwicklers sollte exakt dieselbe Authentifizierung genutzt werden wie in der produktiven Laufzeitumgebung. Da der App_SA in Cloud Run verwendet wird, nutzen wir diesen auch für lokale Tests.
gcloud auth application-default login --impersonate-service-account=App_SA@myproject.com # SA Impersonation [ID 6]
node server.js # The code, or more precisely, the Google SDK will use the SA user.
Schritt 4: Deployment
John Doe möchte den neuesten Code auf Cloud Run deployen. Um seine lokale ADC-Konfiguration (App_SA) aus Schritt 3 nicht zu überschreiben, nutzt er für die Deployment-Befehle die einmalige Impersonation. Das funktioniert einwandfrei, da Gruppe 1 (gcloud CLI Befehle) und Gruppe 2 (Google Cloud ADC) unabhängig voneinander sind. Ein –impersonate-service-account Flag bei einem gcloud-Befehl beeinflusst die ADC-Konfiguration nicht.
gcloud builds submit --impersonate-service-account=Deployment_SA@myproject.com ... # [ID 4]
gcloud run deploy --impersonate-service-account=Deployment_SA@myproject.com ... # [ID 4]
Use Case 2: Persistente Impersonation für effizientes Debugging [ID 2]
Szenario: Ein Entwickler muss zur Fehlersuche bei einem fehlgeschlagenen Deployment mehrere gcloud CLI Befehle hintereinander als Deployment_SA ausführen. Statt jedem einzelnen Befehl das Flag –impersonate-service-account anzuhängen, konfiguriert er eine persistente Impersonation in seiner aktiven gcloud-Konfiguration.
# Enable impersonation persistently for the current gcloud configuration
gcloud config set auth/impersonate_service_account Deployment_SA@myproject.iam.gserviceaccount.com
# These commands will now automatically be executed as the Deployment_SA
gcloud builds list
gcloud run services list
# Disable impersonation to return to your personal user identity
gcloud config unset auth/impersonate_service_account
Use Case 3: On-Premises CI/CD mit Service Account Key-File [ID 3]
Szenario: Eine lokale CI/CD-Pipeline (z. B. Jenkins) muss gcloud CLI Befehle ausführen, um eine Anwendung in der GCP bereitzustellen. Da das System außerhalb der Google Cloud läuft, kann keine Workload Identity Federation genutzt werden. Als letzter Ausweg kommt ein Service Account JSON-Key-File zum Einsatz.
Wichtiger Sicherheitshinweis: Die Nutzung statischer, langlebiger JSON-Keys stellt ein Sicherheitsrisiko dar. Diese Methode der GCP Authentifizierung sollte wirklich nur als letzter Ausweg gewählt werden, wenn sich Workload Identity Federation nicht einrichten lässt.
# Authenticate gcloud using the securely mounted JSON key file
gcloud auth activate-service-account Deployment_SA@myproject.iam.gserviceaccount.com
--key-file=/secrets/deployment-key.json
# The pipeline can now run gcloud commands as the Deployment_SA
gcloud run deploy my-app --image=...
Use Case 4: Bootstrapping – das Henne-Ei-Problem lösen [ID 5]
Szenario: Bevor eine automatisierte CI/CD-Pipeline oder ein Service Account übernehmen kann, muss die initiale Infrastruktur stehen. Mark Sudo, der Project Owner, führt die allerersten Terraform-Skripte mit seinem persönlichen Account aus. Diese Skripte erstellen den Deployment_SA, den App_SA und weisen die ersten IAM-Rollen zu.
# Mark logs in with his personal Project Owner account to create the local ADC file
gcloud auth application-default login
# Terraform uses Mark's permissions to create the first Service Accounts and Buckets
terraform apply
Warum dieser Weg? Es ist der unverzichtbare Startpunkt. Du nutzt eine menschliche Identität, um das „Bootstrapping“ der Maschinen-Identitäten (Service Accounts) durchzuführen, die später alle automatisierten Aufgaben und Deployments übernehmen.
Use Case 5: Hosting auf einer Drittanbieter-Plattform [ID 7]
Szenario: John Doe deployt sein Node.js-Backend auf einer Plattform außerhalb der GCP (z.B. Render.com). Das Backend muss sich mit der Google Cloud SQL Datenbank oder dem Cloud Storage verbinden. Da Render nicht in der Google Cloud läuft, können die Credentials nicht automatisch vom GCP-Metadaten-Server bezogen werden.
Setup auf Render.com:
- Generiere einen JSON-Key für den App_SA in der Google Cloud Console. (Erinnerung: Behandle statische Keys immer mit äußerster Vorsicht).
- Nutze im Render.com Dashboard die „Secret Files“-Funktion, um den Inhalt des JSON-Keys sicher zu speichern. Render bindet diese Datei dann an einem spezifischen Pfad ein, z. B. /etc/secrets/gcp-key.json.
- Füge in deinen Render Service-Einstellungen folgende Umgebungsvariable hinzu: GOOGLE_APPLICATION_CREDENTIALS=/etc/secrets/gcp-key.json
Ergebnis: Wenn die Node.js-App auf Render startet, erkennt das Google Cloud SDK (z.B. const { Storage } = require(‚@google-cloud/storage‘);) automatisch die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS, liest die JSON-Datei aus und authentifiziert die Anwendung sicher als App_SA.
Übersicht: Authentifizierungsstatus prüfen und zurücksetzen
Bei der Fehlerbehebung bei Authentifizierungsproblemen oder beim Wechsel zwischen Identitäten ist es hilfreich zu wissen, welche Identität derzeit aktiv ist. Die folgende Tabelle zeigt, wie du den aktuellen Authentifizierungsstatus für jede Gruppe überprüfen und wie du ihn widerrufen oder zurücksetzen kannst.
| Group | Scope | How to check (Command) | How to logout / clear |
|---|---|---|---|
| Group 1 | gcloud CLI (gcloud commands) | gcloud auth list | gcloud auth revoke |
| Group 2 | ADC (Code, SDKs, Terraform) | cat ~/.config/gcloud/application_default_credentials.json | gcloud auth application-default revoke |
| Extra | Impersonation (Config) | gcloud config get-value auth/impersonate_service_account | gcloud config unset auth/impersonate_service_account |
| Extra | Environment Variable | echo $GOOGLE_APPLICATION_CREDENTIALS | unset GOOGLE_APPLICATION_CREDENTIALS |
Takeaways
Ein durchdachtes Design für deine GCP Authentifizierung bedeutet nicht, sich auf eine einzige Methode festzulegen, sondern sie intelligent zu kombinieren:
- Trenne menschliche und maschinelle Identitäten: Menschen nutzen persönliche Accounts für interaktive Aufgaben; Service Accounts übernehmen automatisierte Workloads.
- Spiegele das Produktions-Setup in der lokalen Entwicklung: Nutze Google Cloud ADC Service Account impersonation (ID 6), um Berechtigungsfehler schon beim Entwickeln zu finden.
- Halte deine Umgebung sauber: Nutze das –impersonate-service-account Flag (ID 4) für Einzelbefehle, um deine persistenten Konfigurationen nicht zu überschreiben.
- Vermeide Key-Files: Nutze Workload Identity Federation für externe Systeme. Reserviere Key-Files (IDs 3, 7) nur für absolute Ausnahmefälle.
- Kenne deinen Status: Wenn etwas schiefgeht, zeigt dir die Check-Übersicht oben genau, mit welchen Befehlen du überprüfst, welche Identität gerade aktiv ist.
Fazit:
Die richtige GCP Authentifizierung basiert auf einfachen Grundregeln: Trenne menschliche Logins von maschinellen Accounts, simuliere die Produktion lokal über Impersonation und vermeide statische Key-Files, wo immer es geht. So bleibt dein Cloud-Setup von Anfang an sicher, übersichtlich und flexibel.
