Auf dieser Seite wird erklärt, wie Sie mit der Google Cloud Console, dem gcloud
-Befehlszeilentool, der Identity and Access Management API oder einer der Google Cloud-Clientbibliotheken Dienstkontoschlüssel erstellen und verwalten.
Voraussetzungen für diese Anleitung
- Sie kennen die Informationen zu Dienstkonten
- Sie haben das
gcloud
-Tool installiert.
Erforderliche Berechtigungen
Damit Nutzer Dienstkontoschlüssel verwalten können, muss ihnen die Rolle „Zentraler Dienstkontoadministrator“ (roles/iam.serviceAccountKeyAdmin
) zugewiesen werden. Weitere Informationen finden Sie unter Dienstkontenrollen.
Einfache IAM-Rollen enthalten auch Berechtigungen zum Verwalten von Dienstkontoschlüsseln. In einer Produktionsumgebung sollten Sie keine einfachen Rollen zuweisen, Sie können sie aber in einer Entwicklungs- oder Testumgebung gewähren.
Dienstkontoschlüssel erstellen
Sie müssen erst die Identität des Dienstkontos bestätigen, um ein Dienstkonto außerhalb von Google Cloud zu verwenden, zum Beispiel auf anderen Plattformen oder lokal. Paare aus öffentlichen und privaten Schlüsseln bieten dafür eine sichere Möglichkeit.
Sie können einen Dienstkontoschlüssel mithilfe der Cloud Console, des gcloud
-Tools, der Methode serviceAccounts.keys.create()
oder einer der Clientbibliotheken erstellen.
Ein Dienstkonto kann bis zu 10 Schlüssel haben.
In den folgenden Beispielen ist sa-name
der Name Ihres Dienstkontos und project-id
die ID Ihres Google Cloud-Projekts. Sie können den String sa-name@project-id.iam.gserviceaccount.com
auf der Seite Dienstkonten in der Cloud Console abrufen.
Console
Rufen Sie in der Cloud Console die Seite Dienstkonten auf.
Klicken Sie auf Projekt auswählen, wählen Sie ein Projekt aus und klicken Sie auf Öffnen.
Suchen Sie nach der Zeile des Dienstkontos, für das Sie einen Schlüssel erstellen möchten. Klicken Sie in dieser Zeile auf die Schaltfläche
und anschließend auf Schlüssel erstellen.Wählen Sie einen Schlüsseltyp aus und klicken Sie auf Erstellen.
Wenn Sie auf Erstellen klicken, wird eine Dienstkontoschlüsseldatei heruntergeladen. Nachdem Sie die Schlüsseldatei heruntergeladen haben, können Sie sie nicht noch einmal herunterladen.
Bewahren Sie die Schlüsseldatei sicher auf, da sie zur Authentifizierung als Ihr Dienstkonto verwendet werden kann. Sie können diese Datei beliebig verschieben und umbenennen.
gcloud
Mit dem Befehl gcloud iam service-accounts keys create
können Sie Dienstkontoschlüssel erstellen.
Befehl:
gcloud iam service-accounts keys create ~/key.json \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Ausgabe:
created key [e44da1202f82f8f4bdd9d92bc412d1d8a837fa83] of type [json] as [/usr/home/username/key.json] for [sa-name@project-id.iam.gserviceaccount.com]
Die Dienstkontoschlüsseldatei wird jetzt auf Ihren Computer heruntergeladen. Nachdem Sie die Schlüsseldatei heruntergeladen haben, können Sie sie nicht noch einmal herunterladen.
Bewahren Sie die Schlüsseldatei sicher auf, da sie zur Authentifizierung als Ihr Dienstkonto verwendet werden kann. Sie können diese Datei beliebig verschieben und umbenennen.
REST
Die Methode projects.serviceAccounts.keys.create
ermöglicht es, einen Schlüssel für ein Dienstkonto zu erstellen.
Ersetzen Sie diese Werte in den folgenden Anweisungen:
project-id
: Ihre Google Cloud-Projekt-ID.sa-name
: Den Namen des Dienstkontos, für das Sie einen Schlüssel erstellen möchten.private-key-type
: Optional. Das Ausgabeformat des privaten Schlüssels. Der Standardwert istTYPE_GOOGLE_CREDENTIALS_FILE
, eine base64-codierte JSON-Schlüsseldatei. Eine Liste aller anwendbaren Werte finden Sie in der Referenz zuServiceAccountPrivateKeyType
.key-algorithm
: Optional. Den Schlüsselalgorithmus, der für den Schlüssel verwendet werden soll. Der Standardwert ist ein 2.048-Bit-RSA-Schlüssel. Dieser Wert kann geändert werden. Eine Liste aller anwendbaren Werte finden Sie in der Referenz zuServiceAccountKeyAlgorithm
.
HTTP-Methode und URL:
POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys
JSON-Text anfordern:
{ "privateKeyType": "private-key-type", "keyAlgorithm": "key-algorithm" }
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Die Antwort enthält einen Schlüssel für Ihr Dienstkonto. Beispiel:
{ "name":"projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c", "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE", "privateKeyData":"MIIJqAIB . . .", "validAfterTime": "2020-05-17T18:48:27Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }
Bewahren Sie die Schlüsseldaten sicher auf, da sie zur Authentifizierung als Ihr Dienstkonto verwendet werden können.
C#
Richten Sie für dieses Beispiel C# wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM C# API.
Go
Richten Sie für dieses Beispiel Go wie in der Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Go API.
Java
Richten Sie für dieses Beispiel Java wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Java API.
Python
Richten Sie für dieses Beispiel Python wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Python API.
Das zurückgegebene Ergebnis privateKeyData
ist eine base64-codierte Stringdarstellung des JSON- oder P12-Schlüssels bzw. der JSON- oder P12-Anmeldedaten des Werts für TYPE_GOOGLE_CREDENTIALS_FILE
.
Bei der Erstellung eines Schlüssels wird ein neues Paar aus öffentlichem und privatem Schlüssel generiert und auf Ihren Rechner heruntergeladen. Es enthält die einzige Kopie des privaten Schlüssels. Sie sind dafür verantwortlich, dass der private Schlüssel sicher aufbewahrt wird. Notieren Sie sich den Speicherort und prüfen Sie, ob die Anwendung auf den Schlüssel zugreifen kann. Sie benötigt den Schlüssel, um authentifizierte API-Aufrufe auszuführen.
Der Schlüssel kann unterschiedliche Formate haben, je nachdem, mit welcher Methode er generiert wurde. Schlüssel, die mit der Cloud Console oder dem gcloud
-Befehlszeilentool erstellt wurden, sehen so aus:
{ "type": "service_account", "project_id": "project-id", "private_key_id": "key-id", "private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n", "client_email": "service-account-email", "client_id": "client-id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://accounts.google.com/o/oauth2/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email" }
Schlüssel, die mit der REST API oder Clientbibliotheken generiert wurden, sehen so aus:
{ "name": "projects/project-id/serviceAccounts/service-account-email/keys/key-id", "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE", "privateKeyData": "private-key", "validAfterTime": "date", "validBeforeTime": "date", "keyAlgorithm": "KEY_ALG_RSA_2048" }
Das zurückgegebene Ergebnis privateKeyData
ist wieder eine base64-codierte Stringdarstellung des JSON- oder P12-Schlüssels bzw. der JSON- oder P12-Anmeldedaten des Werts für TYPE_GOOGLE_CREDENTIALS_FILE
. Sie können das base64-decodierte Element privateKeyData
in einer Datei mit der entsprechenden Erweiterung (entweder .p12
oder .json
) speichern und es als Eingabe für Clientbibliotheken oder den Befehl gcloud auth activate-service-account
verwenden.
Da die Formatierung jeweils von der Methode abhängt, ist es am einfachsten, die Schlüssel mit der Methode zu generieren, die Sie auch für zukünftige API-Aufrufe verwenden möchten. Wenn Sie beispielsweise gcloud
verwenden, erstellen Sie Ihren Schlüssel auch mit gcloud
. Schlüssel, die mit einer anderen Methode erstellt wurden (zum Beispiel mit REST generierte Schlüssel, die Sie mit gcloud
verwenden möchten), müssen bearbeitet und an das geeignete Format angepasst werden.
Google sorgt dafür, dass die öffentlichen Schlüssel für alle Dienstkonten für jeden öffentlich zugänglich und verfügbar sind, sodass mit dem privaten Schlüssel erstellte Signaturen überprüft werden können. Der öffentliche Schlüssel ist unter den folgenden URLs zugänglich:
- x.509-Zertifikat: https://www.googleapis.com/service_accounts/v1/metadata/x509/sa-name@project-id.iam.gserviceaccount.com
- JSON-Webschlüssel (JWK): https://www.googleapis.com/service_accounts/v1/jwk/sa-name@project-id.iam.gserviceaccount.com
- Rohendpunkt: https://www.googleapis.com/service_accounts/v1/metadata/raw/sa-name@project-id.iam.gserviceaccount.com
Dienstkontoschlüssel auflisten
Sie können die Dienstkontoschlüssel für ein Dienstkonto in der Cloud Console, mit dem gcloud
-Tool, der Methode serviceAccount.keys.list()
oder einer der Clientbibliotheken auflisten.
Die Methode serviceAccount.keys.list()
wird in der Regel verwendet, um Dienstkonten und Schlüssel zu überprüfen oder benutzerdefinierte Tools für die Verwaltung von Dienstkonten zu erstellen.
Um herauszufinden, zu welchem Projekt Ihr Schlüssel gehört, können Sie den Schlüssel als JSON-Datei herunterladen und sich anschließend die Datei ansehen.
Eventuell werden Schlüssel aufgelistet, die Sie nicht erstellt haben. Diese Schlüssel werden von Google Cloud verwaltet und von Google Cloud-Diensten wie App Engine und Compute Engine verwendet. Weitere Informationen zum Unterschied zwischen von Nutzern und von Google Cloud verwalteten Schlüsseln finden Sie unter Dienstkontoschlüssel verwalten.
Console
Rufen Sie in der Cloud Console die Seite Dienstkonten auf.
Klicken Sie auf Projekt auswählen, wählen Sie ein Projekt aus und klicken Sie auf Öffnen. In der Console werden alle Dienstkonten des Projekts und die entsprechenden Schlüssel aufgelistet.
gcloud
Mit gcloud iam service-accounts keys list
können Sie Dienstkontoschlüssel löschen.
Befehl:
gcloud iam service-accounts keys list \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Ausgabe:
KEY_ID | CREATED_AT | EXPIRES_AT |
8e6e3936d7024646f8ceb39792006c07f4a9760c | 2016-01-26T21:01:42.000Z | 2026-01-23T21:01:42.000Z |
937c98f870f5c8db970af527aa3c12fd88b1c20a | 2016-01-26T20:55:40.000Z | 2026-01-23T20:55:40.000Z |
REST
Mit der Methode projects.serviceAccounts.keys.list
können Sie alle Dienstkontoschlüssel für ein Dienstkonto auflisten.
Ersetzen Sie diese Werte in den folgenden Anweisungen:
project-id
: Ihre Google Cloud-Projekt-ID.sa-name
: Den Namen des Dienstkontos, dessen Schlüssel Sie auflisten möchten.key-types
: Optional. Eine durch Kommas getrennte Liste der Schlüsseltypen, die Sie in die Antwort aufnehmen möchten. Der Schlüsseltyp gibt an, ob ein Schlüssel vom Nutzer (USER_MANAGED
) oder vom System (SYSTEM_MANAGED
) verwaltet wird. Wenn Sie das Feld leer lassen, werden alle Schlüssel zurückgegeben.
HTTP-Methode und URL:
GET https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys?keyTypes=key-types
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Sie sollten in etwa folgende JSON-Antwort erhalten:
{ "keys": [ { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c", "validAfterTime": "2020-03-04T17:39:47Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }, { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8", "validAfterTime": "2020-03-31T23:50:09Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }, { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e", "validAfterTime": "2020-05-17T18:58:13Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" } ] }
C#
Richten Sie für dieses Beispiel C# wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM C# API.
Go
Richten Sie für dieses Beispiel Go wie in der Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Go API.
Java
Richten Sie für dieses Beispiel Java wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Java API.
Python
Richten Sie für dieses Beispiel Python wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Python API.
Dienstkontoschlüssel abrufen
Die Daten für den privaten Schlüssel des Dienstkontoschlüssels können nur bei der ersten Erstellung des Schlüssels abgerufen werden.
Mit der REST API-Methode projects.serviceAccounts.keys.get()
erhalten Sie grundlegende Informationen zu einem Schlüssel, z. B. ID, Algorithmus und Daten des öffentlichen Schlüssels. Die Verwendung der Cloud Console oder des gcloud
-Befehlszeilentools wird nicht unterstützt.
Öffentliche Schlüssel für Dienstkonten hochladen
Sie können den öffentlichen Schlüssel als Teil eines nutzerverwalteten Schlüsselpaars in ein Dienstkonto hochladen. Nachdem Sie den öffentlichen Schlüssel hochgeladen haben, ist er dauerhaft mit dem Dienstkonto verknüpft und wird wie die vom Nutzer verwalteten Schlüssel für Dienstkonten genutzt. Informationen zum Deaktivieren der Funktion zum Hochladen von Schlüsseln für Ihr Projekt finden Sie unter Dienstkontoschlüssel-Upload einschränken.
Wenn Sie ein vom Nutzer verwaltetes Schlüsselpaar anstelle eines von Google verwalteten Schlüsselpaars verwenden möchten, müssen Sie dieses verwalten und regelmäßig rotieren.
Der hochgeladene Schlüssel muss ein öffentlicher RSA-Schlüssel sein, der in ein X.509 v3-Zertifikat eingebunden und base64-codiert ist. Sie können mit Tools wie OpenSSL einen Schlüssel und ein Zertifikat in diesem Format generieren. Mit dem folgenden Befehl wird beispielsweise ein 2.048-Bit-RSA-Schlüsselpaar generiert und der öffentliche Schlüssel in ein selbst signiertes Zertifikat eingebunden, das 365 Tage gültig ist:
openssl req -x509 -nodes -newkey rsa:2048 -days 365 \
-keyout /path/to/private_key.pem \
-out /path/to/public_key.pem \
-subj "/CN=unused"
Anschließend können Sie die Datei public_key.pem
als öffentlichen Schlüssel für ein Dienstkonto hochladen.
gcloud
Mit dem Befehl gcloud iam service-accounts keys upload
können Sie einen öffentlichen Schlüssel zum Signieren von Dienstkontoschlüsseln hochladen.
Befehl:
gcloud iam service-accounts keys upload /path/to/public_key.pem \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Die Ausgabe enthält eine eindeutige Kennzeichnung für den hochgeladenen Schlüssel:
Name: projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0
Um festzustellen, ob der vorherige Befehl erfolgreich ausgeführt wurde, geben Sie den Befehl gcloud iam service-accounts keys list
ein:
gcloud iam service-accounts keys list \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Die Ausgabe enthält die gleiche eindeutige Kennzeichnung, die nach dem Erstellen des Schlüssels zurückgegeben wurde:
KEY_ID | CREATED_AT | EXPIRES_AT |
c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0 | 2019-06-26T21:01:42.000Z | 2029-06-23T21:01:42.000Z |
REST
Mit der Methode projects.serviceAccounts.keys.upload
können Sie den öffentlichen Schlüssel aus einem vom Nutzer verwalteten Schlüsselpaar hochladen und ihn dem Dienstkonto hinzufügen.
Ersetzen Sie diese Werte in den folgenden Anweisungen:
project-id
: Ihre Google Cloud-Projekt-ID.sa-name
: Den Namen des Dienstkontos, mit dem der Schlüssel verknüpft werden soll.public-key-data
: Die Daten des öffentlichen Schlüssels für das Schlüsselpaar. Dieser Schlüssel muss ein öffentlicher RSA-Schlüssel sein, der in ein X.509 v3-Zertifikat eingebunden ist. Codieren Sie die Daten des öffentlichen Schlüssels mit base64, einschließlich der ersten Zeile,-----BEGIN CERTIFICATE-----
, und der letzten Zeile,-----END CERTIFICATE-----
.
HTTP-Methode und URL:
POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys:upload
JSON-Text anfordern:
{ "publicKeyData": "public-key-data" }
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Sie sollten in etwa folgende JSON-Antwort erhalten:
{ "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0", "validAfterTime": "2020-05-17T19:31:19Z", "validBeforeTime": "2021-05-17T19:31:19Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "USER_PROVIDED", "keyType": "USER_MANAGED" }
Dienstkontoschlüssel löschen
Sie können einen Dienstkontoschlüssel mit der Cloud Console, dem gcloud
-Tool, der Methode serviceAccount.keys.delete()
oder einer der Clientbibliotheken löschen.
Wenn Sie einen Schlüssel löschen, kann Ihre Anwendung nicht mehr mit diesem Schlüssel auf Google Cloud-Ressourcen zugreifen. Es empfiehlt sich daher, die Dienstkontoschlüssel regelmäßig zu rotieren. Sie können dazu zuerst einen neuen Schlüssel erstellen, dann die Anwendungen auf den neuen Schlüssel umstellen und anschließend den alten Schlüssel löschen. Verwenden Sie die Methoden serviceAccount.keys.create()
und serviceAccount.keys.delete()
zusammen, um die Rotation zu automatisieren.
Console
Rufen Sie in der Cloud Console die Seite Dienstkonten auf.
Klicken Sie auf Projekt auswählen, wählen Sie ein Projekt aus und klicken Sie auf Öffnen. In der Console werden alle Dienstkonten des Projekts und die entsprechenden Schlüssel aufgelistet.
Suchen Sie nach der Zeile des Dienstkontos, für das Sie einen Schlüssel erstellen möchten. Klicken Sie in dieser Zeile auf die Schaltfläche
und dann auf Bearbeiten.Klicken Sie in der Liste der Schlüssel bei jedem Schlüssel, den Sie löschen möchten, auf Löschen
.
gcloud
Mit dem Befehl gcloud iam service-accounts keys delete
können Sie Dienstkontoschlüssel löschen.
Befehl:
gcloud iam service-accounts keys delete key-id \ --iam-account sa-name@project-id.iam.gserviceaccount.com
Ausgabe:
Deleted key [8e6e3936d7024646f8ceb39792006c07f4a9760c] for service account [sa-name@project-id.iam.gserviceaccount.com]
REST
Mit der Methode projects.serviceAccounts.keys.delete
können Sie Dienstkontoschlüssel löschen.
Ersetzen Sie diese Werte in den folgenden Anweisungen:
project-id
: Ihre Google Cloud-Projekt-ID.sa-name
: Den Namen des Dienstkontos, dessen Schlüssel Sie löschen möchten.key-id
: Die ID des Schlüssels, den Sie löschen möchten.
HTTP-Methode und URL:
DELETE https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys/key-id
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Sie sollten in etwa folgende JSON-Antwort erhalten:
{ }
C#
Richten Sie für dieses Beispiel C# wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM C# API.
Go
Richten Sie für dieses Beispiel Go wie in der Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Go API.
Java
Richten Sie für dieses Beispiel Java wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Java API.
Python
Richten Sie für dieses Beispiel Python wie in der IAM-Kurzanleitung zur Verwendung von Clientbibliotheken beschrieben ein. Weitere Informationen finden Sie in der Referenzdokumentation zur IAM Python API.