1. Einführung
Bisher wurden Google API-Schlüssel für den Zugriff auf Google APIs verwendet, wenn andere Methoden nicht verfügbar oder unpraktisch waren. Die häufigsten Anwendungsfälle waren der Zugriff auf die Google Maps API und Google APIs, die von Firebase bereitgestellt werden. Mit der Einführung von KI-Modellen, KI-Agents wie Gemini sowie AI Studio und Agent-Entwicklungs-Frameworks wie dem Agent Development Kit sind API-Schlüssel zu einer primären Methode für den Zugriff auf die Large Language Models von Google geworden.
API-Schlüssel bieten ein geringes Schutzniveau. Obwohl Google Cloud mehrere Methoden bietet, um den Missbrauch der Schlüssel zu verhindern, ermöglicht der Besitz eines aktiven API-Schlüssels den Zugriff auf Google APIs ohne zusätzliche Authentifizierungs- oder Autorisierungsvalidierungen. Die Methoden zum Einschränken der Verwendung von API-Schlüsseln sind in der Dokumentation beschrieben. Im Cloud-Blogbeitrag Gemini- und Google API-Schlüssel schützen finden Sie weitere Empfehlungen zur API-Schlüsselverwaltung. In diesem Codelab setzen Sie diese Empfehlungen in die Praxis um.
Aufgaben
- Überprüfen Sie die erzwungenen Einschränkungen beim Erstellen neuer API-Schlüssel in Google Cloud.
- Katalogisieren Sie alle Ihre API-Schlüssel und suchen Sie nach Schlüsseln ohne Sicherheitsschutz.
- Erzwingen Sie Einschränkungen für die vorhandenen API-Schlüssel basierend auf ihrer Verwendung.
- Definieren Sie die Automatisierung, mit der der Schlüssel bei ungewöhnlicher Verwendung gelöscht wird.
Voraussetzungen
- Ein moderner Webbrowser wie Chrome.
- Ein Google-Konto
2. Einrichtung
In dieser Anleitung wird davon ausgegangen, dass Sie Befehle in Cloud Shell in der Google Cloud Console ausführen. Wenn Sie die gcloud CLI in Ihrer lokalen Umgebung haben, können Sie die Befehle dort ausführen.
Die Vorgänge in den Schritten können zwar über die Benutzeroberfläche der Cloud Console ausgeführt werden, die Methoden sind jedoch unterschiedlich. In diesem Codelab wird die Befehlszeilenschnittstelle verwendet, um die Interaktionen zu vereinfachen und die Integration mit modernen KI-Agents (z. B. Antigravity CLI) zu erleichtern.
Cloud Shell-Terminal starten
- Öffnen Sie die Google Cloud Console unter https://console.cloud.google.com/ in einem neuen Browserfenster. Für eine optimale Nutzererfahrung wird die Verwendung von Chrome empfohlen.
- Melden Sie sich in Google Cloud in Ihrem Google-Konto an.
- Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren
.
Klicken Sie gegebenenfalls auf die folgenden Fenster:- Fahren Sie mit dem Informationsfenster zu Cloud Shell fort.
- Autorisieren Sie Cloud Shell, Ihre Anmeldedaten für Google Cloud API-Aufrufe zu verwenden.
Google Cloud-Projekt auswählen
Nachdem Sie die Cloud Console geöffnet haben, werden Sie authentifiziert und in der Regel wird ein Projekt für Ihre Arbeit ausgewählt. Die Projekt-ID ist eine Folge von 6 bis 30 Zeichen aus Kleinbuchstaben, Ziffern und Bindestrichen, z. B. qwiklabs-gcp-04-3075fc9fd77f. Das Cloud Shell-Terminal konfiguriert die gcloud CLI mit dem ausgewählten Projekt. Die Ausgabe sollte in etwa so aussehen:
Your Cloud Platform project in this session is set to qwiklabs-gcp-04-3075fc9fd77f
Das bedeutet, dass für Ihre weiteren Befehle an gcloud die Projekt-ID qwiklabs-gcp-04-3075fc9fd77f verwendet wird.
Legen Sie die Projekt-ID als Umgebungsvariable PROJECT_ID fest. Mit dem folgenden Befehl können Sie die Liste aller Ihrer Projekte aufrufen:
gcloud projects list
- Ersetzen Sie
your-project-idund führen Sie den Befehl aus, wenn Sie eine andere Projekt-ID als die ingcloudkonfigurierte verwenden möchten.export PROJECT_ID="your-project-id"export PROJECT_ID="qwiklabs-gcp-04-3075fc9fd77f" - Führen Sie den folgenden Befehl aus, wenn Sie die ausgewählte Projekt-ID verwenden möchten:
export PROJECT_ID=$(gcloud config get project)
3. Neuen API-Schlüssel einschränken
In der Vergangenheit konnten Nutzer uneingeschränkte API-Schlüssel erstellen. Uneingeschränkte Schlüssel konnten verwendet werden, um JEDE Google API aufzurufen, die in dem Projekt aktiviert war, in dem der Schlüssel erstellt wurde. Die Google Cloud Console verhindert zwar, dass Nutzer uneingeschränkte Schlüssel erstellen, dies ist aber weiterhin mit der gcloud CLI oder mit direkten API-Aufrufen möglich.
In den folgenden Schritten wird gezeigt, wie Sie einen eingeschränkten API-Schlüssel erstellen, der die Verwendung auf die angegebene API und die angegebene Website beschränkt.
- Führen Sie im Shell-Terminal den folgenden Befehl aus, um einen neuen API-Schlüssel zu erstellen, der nur für die Google Maps Geolocation API verwendet werden kann:
gcloud services api-keys create --key-id=restricted-api-key \ --display-name="restricted api key" \ --api-target=service=geolocation.googleapis.com \ --project=${PROJECT_ID} - Erhöhen Sie die Sicherheit des Schlüssels, indem Sie eine Anwendungseinschränkung hinzufügen. Beschränken Sie die Verwendung des Schlüssels nur auf alle Pfade innerhalb der Website
example.com. Führen Sie den folgenden Befehl aus, um dem Schlüssel die Anwendungseinschränkung hinzuzufügen:gcloud services api-keys update restricted-api-key \ --location=global \ --allowed-referrers="example.com/*" \ --project=${PROJECT_ID}--allowed-applicationeine zulässige Android-App oderallowed-ipszulässige IP-Adressen definieren. Die vollständige Dokumentation mit allen Optionen finden Sie hier.
Bereinigen
Löschen Sie den erstellten API-Schlüssel, es sei denn, Sie möchten ihn verwenden:
gcloud services api-keys delete --key-id=restricted-api-key \
--project=${PROJECT_ID}
4. API-Schlüssel katalogisieren
In diesem Schritt verwenden Sie die gcloud CLI, um eine Bestandsaufnahme Ihrer API-Schlüssel zu erhalten. Die resultierende Liste enthält alle aktiven (nicht gelöschten) API-Schlüssel, auf die Sie Zugriff haben.
- Führen Sie den folgenden Befehl aus, um alle Schlüsselnamen, IDs und Erstellungsdaten aufzurufen:
gcloud services api-keys list --project=${PROJECT_ID} \ --format='value(displayName,name.basename(),createTime.date())'api key 1 api-key-1 2024-05-10T07:53:24 api key 2 api-key-2 2025-06-12T14:47:57
- Wählen Sie eine der Schlüssel-IDs aus und fügen Sie den folgenden Befehl ein, um zu prüfen, ob der Schlüssel Einschränkungen hat. Ersetzen Sie
your-key-iddurch den Wert der ausgewählten Schlüssel-ID:gcloud services api-keys describe "your-key-id" --project=${PROJECT_ID}
Die Ausgabe (im YAML-Format) enthält eine Liste der Einschränkungen unter restrictions.
createTime: '2024-05-10T07:53:24.986528Z'
displayName: api key 1
etag: W/"u1WuY41K2tPKUZd7cfLoKg=="
name: projects/123456789012/locations/global/keys/api-key-1
restrictions:
apiTargets:
- service: geolocation.googleapis.com
browserKeyRestrictions:
allowedReferrers:
- https://example.com/*
uid: 1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6
updateTime: '2024-05-10T07:53:24.071228Z'
Wenn der Schlüssel nie aktualisiert wurde, haben die Felder createTime und updateTime denselben Zeitstempel.
- Laden Sie das Skript herunter und führen Sie es aus, das alle Ihre Projekte durchläuft und alle API-Schlüssel ohne Einschränkungen ausgibt:
curl -fsSL -o unrestricted_api_keys.sh \ "https://github.com/GoogleCloudPlatform/devrel-demos/blob/main/security/api-key-audit/unrestricted_api_keys.sh" chmod +x unrestricted_api_keys.sh ./unrestricted_api_keys.shDISPLAY NAME KEY ID PROJECT ID CREATION DATE Key 1 1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6 my-project-1 2024-05-10T07:53:24.071228Z
5. Verwendung eines API-Schlüssels ermitteln
In diesem Schritt fragen Sie Google Cloud-Messwerte ab, mit denen Sie herausfinden können, welche APIs mit Ihrem API-Schlüssel aufgerufen wurden. Anhand dieser Informationen können Sie die aktuelle Verwendung der Schlüssel überprüfen und API-Einschränkungen auf den Schlüssel anwenden, die auf tatsächlichen Informationen basieren, anstatt nur Vermutungen anzustellen.
- Verwenden Sie dieselbe Schlüssel-ID wie im vorherigen Schritt oder wählen Sie eine andere Schlüssel-ID aus. Ersetzen Sie
your-key-idim folgenden Befehl durch die ausgewählte Schlüssel-ID:export KEY_UID=$( gcloud services api-keys describe "your-key-id" \ --format='value(uid)' \ --project=${PROJECT_ID}) - Legen Sie fest, dass die Suche die Nutzung der letzten 365 Tage umfassen soll. Wenn Sie einen längeren oder kürzeren Zeitraum berücksichtigen möchten, ersetzen Sie
365(Anzahl der Tage) durch eine andere positive Zahl.export DAYS=365 - Aktualisieren Sie die Standardanmeldedaten für Anwendungen (ADC), um einen direkten Aufruf der Cloud Monitoring API zu ermöglichen. Führen Sie den folgenden Befehl aus und folgen Sie der Anleitung im Terminal:
gcloud auth application-default login - Führen Sie den folgenden Befehl aus, um eine Anfrage für Messwertdaten zur Dienstnutzung an die Cloud Monitoring API zu senden:
curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data-urlencode "filter=metric.type=\"serviceruntime.googleapis.com/api/request_count\" AND resource.labels.credential_id=\"apikey:${KEY_UID}\"" \
--data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)" \
--data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
"https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries" \
| jq -r '.timeSeries[]?.resource.labels.service' | sort -u
Mit dem Befehl werden die Datenpunkte für den integrierten Messwert „serviceruntime/api/request_count“ mit dem Label credential_id abgefragt, die mit der eindeutigen ID des ausgewählten API-Schlüssels übereinstimmen. Anschließend werden die Werte für das Label service abgerufen und die Werte ohne Wiederholungen ausgegeben.
API-Schlüssel härten
In diesem Schritt verwenden Sie die in den vorherigen Schritten erfassten Informationen, um die Einschränkungskonfiguration des API-Schlüssels basierend auf den Nutzungsdaten zu aktualisieren.
Sie verwenden denselben API-Schlüssel wie im vorherigen Schritt. Führen Sie bei Bedarf die Anleitung aus den vorherigen Schritten noch einmal aus, um sicherzustellen, dass die Umgebungsvariablen PROJECT_ID, KEY_UID und DAYS festgelegt sind.
- Führen Sie den folgenden Befehl aus, um die Liste der Google APIs abzurufen, die mit dem API-Schlüssel aufgerufen wurden:
SERVICES=$(curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
–data-urlencode "filter=metric.type="serviceruntime.googleapis.com/api/request_count" AND resource.labels.credential_id="apikey:${KEY_UID}""
–data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)"
–data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
"https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries"
| jq -r ‘.timeSeries[]?.resource.labels.service' | sort -u)
1. Build the list of arguments to restrict the API usage for the API key based
on the retrieved list.
```shell
API_TARGET_ARGS=()
for SERVICE in $SERVICES; do
API_TARGET_ARGS+=("--api-target=service=${SERVICE}")
done
- Ersetzen Sie die Liste der eingeschränkten APIs durch die nicht leere Liste:
if [ ${#API_TARGET_ARGS[@]} -gt 0 ]; then gcloud services api-keys update "projects/${PROJECT_ID}/locations/global/keys/${KEY_UID}" \ ${API_TARGET_ARGS} fi
6. Erkennung von Anomalien bei der Nutzung definieren
In den vorherigen Schritten wurde gezeigt, wie Sie API-Schlüssel untersuchen und härten. In diesem Schritt erfahren Sie, wie Sie mit Monitoring-Benachrichtigungen automatisch auf unerwartete Spitzen bei der Nutzung des Schlüssels reagieren können.
Mit der folgenden Anleitung wird eine Benachrichtigung erstellt, die ausgelöst wird, wenn die Rate der API-Aufrufe, die einen API-Schlüssel verwenden, in den letzten 5 Minuten um mehr als 10% gestiegen ist. Die Benachrichtigung ist so konfiguriert, dass ein Cloud Build-Skript ausgelöst wird, das den API-Schlüssel löscht, um eine weitere Verwendung zu verhindern. Der Schlüssel kann innerhalb der nächsten 30 Tage wiederhergestellt werden. Informationen zum Wiederherstellen des Schlüssels finden Sie in der Dokumentation.
In der Anleitung werden die Variablen PROJECT_ID und KEY_UID wiederverwendet, die Sie in den vorherigen Schritten verwendet haben. Wenn Sie einen anderen Schlüssel und/oder ein anderes Projekt auswählen möchten, legen Sie die neuen Werte für diese Variablen fest, wie in den Schritten Einrichtung und Verwendung eines API-Schlüssels ermitteln beschrieben.
- Führen Sie das folgende Skript aus, um eine Benachrichtigungsrichtliniendatei zu erstellen:
cat <<EOF > alert_policy.json { "displayName": "Credential API Request Count Increase Alert (Project: ${PROJECT_ID})", "combiner": "OR", "conditions": [ { "displayName": "API Request Count Increase > 10% in 5m with Min Volume", "conditionPrometheusQueryLanguage": { "query": "(sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) / (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m] offset 5m)) or on() vector(1)) > 1.10) and (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) > 50)", "duration": "0s", "evaluationInterval": "60s" } } ], "enabled": true } EOF(sum( increase( serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m]) ) / (sum( increase( serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m] offset 5m) ) or on() vector(1)) > 1.10) and (sum( increase( serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\"YOUR_CREDENTIAL_ID_HERE\"}[5m])) > 50)NaN(Löschen durch Null) zu vermeiden, wenn die Rate der vorherigen 5 Minuten 0 war, wird der Nenner durch 1 ersetzt, wenn die Rate des vorherigen Zeitraums 0 ist. Sie können die Benachrichtigungsparameter ändern, z. B. die Länge des Zeitraums (5m), den Mindestschwellenwert (50) oder den Schwellenwert für die Steigerung um 10 % (1.10). Zusätzliche Richtlinienparameter definieren, dass die Benachrichtigung ausgelöst werden soll, sobald die Bedingung erreicht ist (duration), und dass die Bedingung alle 60 Sekunden geprüft werden soll (evaluationInterval). - Führen Sie den folgenden Befehl aus, um ein Pub/Sub-Thema zu erstellen, das zum Veröffentlichen von Benachrichtigungen verwendet wird:
gcloud pubsub topics create api-key-alert-notifications --project=$PROJECT_ID - Führen Sie den folgenden Befehl aus, um Benachrichtigungskanäle für Benachrichtigungen zu erstellen, die Pub/Sub verwenden:
CHANNEL_NAME=$(gcloud beta monitoring channels create \ --display-name="Pub/Sub Alert Channel" \ --type="pubsub" \ --channel-labels="topic=projects/$PROJECT_ID/topics/api-key-alert-notifications" \ --format='value(name)' \ --project=$PROJECT_ID)CHANNEL_NAMEim Schritt Bereinigen. - Führen Sie den folgenden Befehl aus, um eine neue Monitoring-Benachrichtigung zu erstellen:
gcloud monitoring policies create --policy-from-file=alert_policy.json \ --project=$PROJECT_ID - Führen Sie den folgenden Befehl aus, um dem Cloud Build-Dienst Berechtigungen zum Löschen der API-Schlüssel im Projekt zu gewähren:
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \ --role="roles/apikeys.admin"apikeys.adminso einzuschränken, dass nur bestimmte Instanzen der API-Schlüssel bearbeitet werden können. Weitere Informationen finden Sie unter IAM Conditions. - Führen Sie das folgende Skript aus, um einen Cloud Build-Trigger zu erstellen, der den API-Schlüssel löscht:
cat <<EOF > trigger_config.yaml name: "delete-compromised-api-key" description: "Triggered by Pub/Sub alert to automatically delete the leaking API Key" pubsubConfig: topic: "projects/${PROJECT_ID}/topics/api-key-alert-notifications" build: steps: - name: "gcr.io/google.com/cloudsdktool/cloud-sdk:slim" args: - "gcloud" - "services" - "api-keys" - "delete" - "${KEY_UID}" - "--quiet" EOF - Führen Sie den folgenden Befehl aus, um einen neuen Monitoring-Benachrichtigungstrigger zu erstellen:
gcloud builds triggers create pubsub \ --trigger-config=trigger_config.yaml \ --project=$PROJECT_ID
Sie können jetzt die Konfigurationsdateien für die Benachrichtigungsrichtlinie und den Cloud Build-Trigger löschen:
rm alert_policy.json trigger_config.yaml
Alternativ können Sie diese Automatisierung mit einem Terraform-Plan einrichten. Laden Sie die Terraform-Dateien aus dem abnormal-usage-detection Ordner im Google Cloud DevRel Repository herunter. Der Plan akzeptiert eine Projekt-ID und eine API-Schlüssel-UID als Eingabeparameter und richtet die Ressourcen und Konfigurationen ein, die Sie in diesem Schritt gesehen haben.
7. Bereinigen
Um unerwartete Kosten für Ihr Google Cloud-Konto zu vermeiden, löschen Sie das Pub/Sub-Thema, den Cloud Build-Trigger und die Benachrichtigungsrichtlinien, die Sie in dieser Übung erstellt haben.
Führen Sie die folgenden Befehle aus, um alle von Ihnen erstellten Ressourcen zu löschen:
gcloud builds triggers delete delete-compromised-api-key \
--project=$PROJECT_ID
gcloud beta monitoring channels delete $CHANNEL_NAME \
--project=$PROJECT_ID \
--quiet
gcloud pubsub topics delete api-key-alert-notifications \
--project=$PROJECT_ID
gcloud projects remove-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
--role="roles/apikeys.admin"
8. Zusammenfassung
In diesem Codelab haben Sie ein robustes Ende-zu-Ende-Sicherheits- und Automatisierungs-Framework für Google Cloud API-Schlüssel implementiert:
- Härtung der Standardkonfigurationen: Sie haben API-Schlüssel erstellt und eingeschränkt, um den Zugriff ausschließlich auf die erforderlichen APIs und vertrauenswürdigen Plattformen (z. B. bestimmte HTTP-Referrer) zu beschränken.
- Überprüfung des Schlüsselbestands: Sie haben Ihre Projektumgebungen gescannt, um uneingeschränkte Schlüssel zu erkennen und zu isolieren, die ein unmittelbares Sicherheitsrisiko darstellen.
- Analyse von Nutzungsdaten: Sie haben programmatisch Messwertdaten aus Cloud Monitoring abgefragt, um die bisherige Schlüsselnutzung zu analysieren. So konnten Sie Schlüssel basierend auf verifizierten Nutzungsmustern einschränken.
- Automatisierte Bedrohungsabwehr: Sie haben einen reaktiven "Leistungsschalter" eingerichtet, indem Sie eine Benachrichtigungsrichtlinie von Cloud Monitoring mit einem Pub/Sub-Thema und einem Cloud Build-Trigger verknüpft haben. So können Sie kompromittierte Schlüssel bei ungewöhnlichen Traffic-Spitzen automatisch löschen.
Nächste Schritte
- Einschränkungen auf alle Ihre API-Schlüssel anwenden: Nutzen Sie die Informationen aus diesem Lab, um alle teilweise eingeschränkten oder uneingeschränkten API-Schlüssel zu erkennen und API- und Clienteinschränkungen anzuwenden.
- „Schutzschalter“ für API-Schlüssel einrichten: Schützen Sie Ihre API-Schlüssel weiter vor unerwarteter Verwendung, indem Sie die automatische Löschung von Schlüsseln bei einem plötzlichen Anstieg der Nutzung einrichten. Verwenden Sie dazu die
gcloud-Befehle oder Terraform, die im Lab gezeigt werden. Sie können die Berechtigungen auch einschränken, indem Sie IAM Conditions verwenden. - Monitoring-Benachrichtigungen kennenlernen: Weitere Informationen zum Einrichten von Benachrichtigungen mit dem Google Cloud Monitoring-Dienst.
- Weitere Informationen zur Zugriffssteuerung in Google Cloud: Informationen zu Richtlinien für Zugriffsgrenzen und zur Weitergabe von Zugriffsänderungen.