Für die Verwendung von REST authentifizieren

Auf dieser Seite wird beschrieben, wie Sie sich authentifizieren, wenn Sie eine REST-Anfrage an eine Google API senden.

Weitere Informationen zur Authentifizierung bei der Verwendung von Google-Clientbibliotheken finden Sie unter Mit Clientbibliotheken authentifizieren.

Hinweise

Führen Sie die folgenden Schritte aus, um die Beispiele auf dieser Seite auszuführen:

1. Aktivieren Sie die Cloud Resource Manager and Identity and Access Management (IAM) APIs:

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

2. Installieren Sie die Google Cloud CLI und initialisieren Sie sie mit folgendem Befehl:

   gcloud init

   Dieser Schritt ist für die Verwendung des Metadatenservers nicht erforderlich.

Typen von Anmeldedaten

Sie können folgende Arten von Anmeldedaten verwenden, um einen REST-Aufruf zu authentifizieren:

• Ihre Anmeldedaten der gcloud CLI.

  Dieser Ansatz ist die einfachste und sicherste Methode zur Bereitstellung von Anmeldedaten für eine REST-Methode in einer lokalen Entwicklungsumgebung. Wenn Ihr Nutzerkonto die erforderlichen IAM-Berechtigungen (Identity and Access Management) für die Methode hat, die Sie aufrufen möchten, ist dies der bevorzugte Ansatz.

  Ihre gcloud-Anmeldedaten sind nicht identisch mit den Anmeldedaten, die Sie dem ADC über die gcloud CLI mitteilen. Weitere Informationen finden Sie unter Anmeldedaten für die gcloud CLI und ADC.

• Die Anmeldedaten, die den Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) bereitgestellt wurden.

  Diese Methode ist die bevorzugte Option zur Authentifizierung eines REST-Aufrufs in einer Produktionsumgebung, da ADC die Anmeldedaten von der Ressource findet, auf der Ihr Code ausgeführt wird (z. B. eine virtuelle Compute Engine-Maschine). Sie können ADC auch verwenden, um sich in einer lokalen Entwicklungsumgebung zu authentifizieren. In diesem Szenario erstellt die gcloud CLI eine Datei, die Ihre Anmeldedaten in Ihrem lokalen Dateisystem enthält.

• Die Anmeldedaten, die durch die Identitätsübernahme eines Dienstkontos bereitgestellt werden.

  Diese Methode erfordert eine umfassendere Einrichtung. Wenn Sie Ihre vorhandenen Anmeldedaten verwenden möchten, um kurzlebige Anmeldedaten für ein anderes Dienstkonto abzurufen, z. B. um lokal mit einem Dienstkonto zu testen oder temporäre erhöhte Berechtigungen anzufordern. Verwenden Sie diesen Ansatz.

• Die vom Metadatenserver zurückgegebenen Anmeldedaten.

  Diese Methode funktioniert nur in Umgebungen mit Zugriff auf einen Metadatenserver. Die vom Metadatenserver zurückgegebenen Anmeldedaten sind mit den Anmeldedaten identisch, die von den Standardanmeldedaten für Anwendungen mit dem angehängten Dienstkonto gefunden werden. Sie fordern jedoch explizit das Zugriffstoken vom Metadatenserver an und stellen es dann mit der REST-Anfrage bereit. Das Abfragen des Metadatenservers nach Anmeldedaten erfordert eine HTTP-GET-Anfrage. Diese Methode stützt sich nicht auf die Google Cloud CLI.

Anmeldedaten für die gcloud-Befehlszeile

Zum Ausführen des folgenden Beispiels benötigen Sie die Berechtigung resourcemanager.projects.get für das Projekt. Die Berechtigung resourcemanager.projects.get ist in verschiedenen Rollen enthalten, z. B. in der Browserrolle (roles/browser).

1. Verwenden Sie den Befehl gcloud auth print-access-token, um ein Zugriffstoken einzufügen, das aus Ihren Nutzeranmeldedaten generiert wurde.

   Im folgenden Beispiel werden Details zum angegebenen Projekt abgerufen. Sie können für jede REST-Anfrage das gleiche Muster verwenden.

   Ersetzen Sie diese Werte in den folgenden Anfragedaten:

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

   curl

   Führen Sie folgenden Befehl aus:

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   Führen Sie folgenden Befehl aus:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   Die Details für Ihr Projekt werden zurückgegeben.

Bei APIs, die ein Kontingentprojekt erfordern, müssen Sie explizit ein Projekt für die Anfrage festlegen. Weitere Informationen finden Sie auf dieser Seite unter Kontingentprojekt mit einer REST-Anfrage festlegen.

Standardanmeldedaten für Anwendungen

Zum Ausführen des folgenden Beispiels benötigt das Hauptkonto, das mit den Anmeldedaten verknüpft ist, die Sie für ADC angeben, die Berechtigung resourcemanager.projects.get für das Projekt. Die Berechtigung resourcemanager.projects.get ist in verschiedenen Rollen enthalten, z. B. in der Browserrolle (roles/browser).

1. Anmeldedaten für ADC bereitstellen

   Wenn Sie eine Google Cloud-Compute-Ressource ausführen, sollten Sie Ihre Nutzeranmeldedaten nicht in ADC angeben. Verwenden Sie stattdessen das angehängte Dienstkonto, um Anmeldedaten bereitzustellen. Weitere Informationen finden Sie unter Google Cloud-Dienste, die das Anhängen eines Dienstkontos unterstützen.

2. Verwenden Sie den Befehl gcloud auth application-default print-access-token, um das von ADC zurückgegebene Zugriffstoken in Ihre REST-Anfrage einzufügen.

   Im folgenden Beispiel werden Details zum angegebenen Projekt abgerufen. Sie können für jede REST-Anfrage das gleiche Muster verwenden.

   Ersetzen Sie diese Werte in den folgenden Anfragedaten:

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

   curl

   Führen Sie folgenden Befehl aus:

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   Führen Sie folgenden Befehl aus:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   Die Details für Ihr Projekt werden zurückgegeben.

   Wenn Ihre Anfrage eine Fehlermeldung zurückgibt, die angibt, dass Endnutzeranmeldedaten nicht von der API unterstützt werden, finden Sie weitere Informationen unter Kontingentprojekt mit einer REST-Anfrage festlegen.

Identität des Dienstkontos

Weitere Informationen finden Sie unter Identitätsübertragung für ein Dienstkonto verwenden.

1. Prüfen Sie die erforderlichen Berechtigungen.

   • Ihr Nutzerkonto muss die Berechtigung iam.serviceAccounts.getAccessToken für das übernommene Dienstkonto haben (auch als mit Berechtigungen versehenes Dienstkonto bezeichnet). Die Berechtigung iam.serviceAccounts.getAccessToken ist in der Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) enthalten. Sie benötigen diese Berechtigung auch, wenn Sie die Inhaberrolle (roles/owner) für das Projekt haben. Weitere Informationen finden Sie unter Erforderliche Berechtigungen festlegen.

   • Im folgenden Beispiel muss das Dienstkonto, dessen Identität Sie übernehmen, die Berechtigung resourcemanager.projects.get für das Projekt haben. Die Berechtigung resourcemanager.projects.get ist in verschiedenen Rollen enthalten, z. B. in der Browserrolle (roles/browser).

2. Identifizieren oder erstellen Sie das mit Berechtigungen versehene Dienstkonto – das Dienstkonto, dessen Identität Sie übernehmen möchten.

   Das mit Berechtigungen versehene Dienstkonto muss die erforderlichen Berechtigungen für den API-Methodenaufruf haben.

3. Verwenden Sie den Befehl gcloud auth print-access-token mit dem Flag --impersonate-service-account, um ein Zugriffstoken für das mit Berechtigungen versehene Dienstkonto in Ihre REST-Anfrage einufügen.

   Im folgenden Beispiel werden Details zum angegebenen Projekt abgerufen. Sie können für jede REST-Anfrage das gleiche Muster verwenden.

   Zum Ausführen dieses Beispiels benötigt das Dienstkonto, dessen Identität Sie übernehmen, die Berechtigung resourcemanager.projects.get. Die Berechtigung resourcemanager.projects.get ist in verschiedenen Rollen enthalten, z. B. in der Browserrolle (roles/browser).

   Ersetzen Sie die folgenden Werte:

   • PRIV_SA: Die E-Mail-Adresse des mit Berechtigungen versehenen Dienstkontos. Beispiel: [e-mail].

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

Metadatenserver

Um ein Zugriffstoken vom Metadatenserver abzurufen, müssen Sie den REST-Aufruf mit einem der Dienste ausführen, die Zugriff auf einen Metadatenserver haben:

• Compute Engine
• App Engine-Standardumgebung
• Flexible App Engine-Umgebung
• Cloud Functions
• Cloud Run
• Google Kubernetes Engine

Verwenden Sie ein Befehlszeilentool wie curl, um ein Zugriffstoken abzurufen, und fügen Sie es dann in Ihre REST-Anfrage ein.

1. Fragen Sie den Metadatenserver nach einem Zugriffstoken ab:

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   Die Anfrage gibt eine Antwort in etwa wie im folgenden Beispiel zurück:

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. Fügen Sie das Zugriffstoken in Ihre REST-Anfrage ein und ersetzen Sie Folgendes:

   • ACCESS_TOKEN: Das im vorherigen Schritt zurückgegebene Zugriffstoken.
   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

Kontingentprojekt mit REST-Anfrage festlegen

Wenn Sie einige APIs mit Nutzeranmeldedaten aufrufen möchten, müssen Sie außerdem das Projekt festlegen, das für die Nutzung abgerechnet und für das Tracking von Kontingenten verwendet wird. Wenn Ihr API-Aufruf eine Fehlermeldung zurückgibt, die besagt, dass die Nutzeranmeldedaten nicht unterstützt werden oder das Kontingentprojekt nicht festgelegt ist, müssen Sie das Kontingentprojekt für die Anfrage explizit festlegen. Fügen Sie der Anfrage den Header x-goog-user-project hinzu, um das Kontingentprojekt festzulegen.

Weitere Informationen dazu, wann dieses Problem auftreten kann, finden Sie unter Nutzeranmeldedaten funktionieren nicht.

Sie benötigen die IAM-Berechtigung serviceusage.services.use für ein Projekt, um es als Abrechnungsprojekt festlegen zu können. Die Berechtigung serviceusage.services.use ist in der IAM-Rolle "Service Usage-Nutzer" enthalten. Wenn Sie die Berechtigung serviceusage.services.use für ein Projekt nicht haben, wenden Sie sich an Ihren Sicherheitsadministrator oder einen Projektinhaber, der Ihnen die Rolle "Service Usage-Nutzer" im Projekt zuweisen kann.

Im folgenden Beispiel wird die Cloud Translation API verwendet, um das Wort "hello" ins Spanische zu übersetzen. Die Cloud Translation API ist eine API, für die ein Kontingentprojekt angegeben werden muss. Erstellen Sie zum Ausführen des Beispiels eine Datei mit dem Namen request.json mit dem Inhalt des Anfragetexts.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

• PROJECT_ID: Die ID oder der Name des Google Cloud-Projekts, das als Abrechnungsprojekt verwendet werden soll.

JSON-Text der Anfrage:

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

Die Übersetzungsanfrage ist erfolgreich. Sie können den Befehl ohne den Header x-goog-user-project ausführen, um zu sehen, was passiert, wenn Sie das Abrechnungsprojekt nicht angeben.

Nächste Schritte

• Authentifizierung bei Google
• Authentifizierung mit Clientbibliotheken.
• Anmeldedaten für die gcloud-Befehlszeile und ADC-Anmeldedaten.
• Weitere Informationen zu den auf dem Metadatenserver gespeicherten Daten.