Diese Seite wurde von der Cloud Translation API übersetzt.

Einsatz von OAuth 2.0 für Server-zu-Server-Anwendungen

Das Google OAuth 2.0-System unterstützt Server-zu-Server-Interaktionen, z. B. zwischen einer Webanwendung und einem Google-Dienst. Für dieses Szenario benötigen Sie ein Dienstkonto. Das ist ein Konto, das zu Ihrer Anwendung gehört, anstatt für einen einzelnen Endnutzer. Ihre Anwendung ruft Google APIs im Namen des Dienstkontos auf, sodass Nutzer nicht direkt beteiligt sind. Dieses Szenario wird manchmal als „Zweibeiniges OAuth“ oder „2LO“ bezeichnet. Der verwandte Begriff „dreibeiniges OAuth“ bezieht sich auf Szenarien, in denen Ihre Anwendung Google APIs im Namen von Endnutzern aufruft und in denen gelegentlich die Nutzereinwilligung erforderlich ist.

In der Regel verwendet eine Anwendung ein Dienstkonto, wenn die Anwendung Google APIs verwendet, um mit den eigenen Daten und nicht mit den Daten eines Nutzers zu arbeiten. Beispielsweise nutzt eine Anwendung, die Google Cloud Datastore für die Datenpersistenz verwendet, ein Dienstkonto zur Authentifizierung der Aufrufe an die Google Cloud Datastore API.

Google Workspace-Domainadministratoren können auch Dienstkonten domainweite Berechtigungen erteilen, um im Namen von Nutzern in der Domain auf Nutzerdaten zuzugreifen.

In diesem Dokument wird beschrieben, wie eine Anwendung den Server-zu-Server-OAuth 2.0-Vorgang mithilfe einer Google APIs-Clientbibliothek (empfohlen) oder mithilfe von HTTP abschließen kann.

Übersicht

Zur Unterstützung von Server-zu-Server-Interaktionen müssen Sie zuerst in der API Consoleein Dienstkonto für Ihr Projekt erstellen. Wenn Sie auf Nutzerdaten für Nutzer in Ihrem Google Workspace-Konto zugreifen möchten, delegieren Sie den domainweiten Zugriff auf das Dienstkonto.

Ihre Anwendung bereitet dann autorisierte API-Aufrufe vor. Dazu verwendet sie die Anmeldedaten des Dienstkontos, um ein Zugriffstoken vom OAuth 2.0-Authentifizierungsserver anzufordern.

Schließlich kann Ihre Anwendung das Zugriffstoken zum Aufrufen von Google APIs verwenden.

Dienstkonto erstellen

Die Anmeldedaten eines Dienstkontos enthalten eine generierte E-Mail-Adresse, die eindeutig ist und mindestens ein öffentliches/privates Schlüsselpaar ist. Wenn die domainweite Delegierung aktiviert ist, ist auch eine Client-ID Teil der Anmeldedaten des Dienstkontos.

Wenn Ihre Anwendung in Google App Engine ausgeführt wird, wird beim Erstellen eines Projekts automatisch ein Dienstkonto eingerichtet.

Wenn Ihre Anwendung in Google Compute Engine ausgeführt wird, wird auch beim Erstellen Ihres Projekts automatisch ein Dienstkonto eingerichtet. Sie müssen jedoch beim Erstellen einer Google Compute Engine-Instanz die Bereiche angeben, auf die Ihre Anwendung Zugriff benötigt. Weitere Informationen finden Sie unter Instanz für die Verwendung von Dienstkonten vorbereiten.

Wenn Ihre Anwendung nicht in Google App Engine oder Google Compute Engine ausgeführt wird, müssen Sie diese Anmeldedaten im Google API Consoleabrufen. So generieren Sie Dienstkonto-Anmeldedaten oder rufen die bereits generierten öffentlichen Anmeldedaten auf:

Erstellen Sie zunächst ein Dienstkonto:

Öffnen Sie den Service accounts page.
If prompted, select a project, or create a new one.
Klicken Sie auf Dienstkonto erstellen .
Geben Sie unter Dienstkontodetails einen Namen, eine ID und eine Beschreibung für das Dienstkonto ein und klicken Sie dann auf Erstellen und fortfahren .
Optional: Wählen Sie unter Diesem Dienstkonto Zugriff auf Projekt gewähren die IAM-Rollen aus, die dem Dienstkonto gewährt werden sollen.
Klicken Sie auf Weiter .
Optional: Fügen Sie unter Benutzern Zugriff auf dieses Dienstkonto gewähren die Benutzer oder Gruppen hinzu, die das Dienstkonto verwenden und verwalten dürfen.
Klicken Sie auf Fertig .

Erstellen Sie als Nächstes einen Dienstkontoschlüssel:

Klicken Sie auf die E-Mail-Adresse für das von Ihnen erstellte Dienstkonto.
Klicken Sie auf die Registerkarte Schlüssel .
Wählen Sie in der Dropdown-Liste Schlüssel hinzufügen die Option Neuen Schlüssel erstellen aus.
Klicken Sie auf Erstellen .

Ihr neues öffentliches/privates Schlüsselpaar wird generiert und auf Ihren Computer heruntergeladen; es dient als einzige Kopie des privaten Schlüssels. Sie sind für die sichere Aufbewahrung verantwortlich. Wenn Sie dieses Schlüsselpaar verlieren, müssen Sie ein neues generieren.

Sie können jederzeit zu API Console zurückkehren, um die E-Mail-Adresse, Fingerabdrücke des öffentlichen Schlüssels und andere Informationen anzusehen oder zusätzliche öffentliche/private Schlüsselpaare zu generieren. Weitere Informationen zu Dienstkonto-Anmeldedaten in API Consolefinden Sie in der API Console-Hilfedatei unter Dienstkonten.

Notieren Sie sich die E-Mail-Adresse des Dienstkontos und speichern Sie die Datei mit dem privaten Schlüssel des Dienstkontos an einem Speicherort, auf den Ihre Anwendung Zugriff hat. Ihre Anwendung benötigt sie für autorisierte API-Aufrufe.

Domainweite Autorisierung an das Dienstkonto delegieren

Mit einem Google Workspace-Konto kann ein Workspace-Administrator der Organisation eine Anwendung autorisieren, im Namen von Nutzern in der Google Workspace-Domain auf Workspace-Nutzerdaten zuzugreifen. Beispiel: Wenn eine Anwendung die Google Calendar API verwendet, um den Kalendern aller Nutzer in einer Google Workspace-Domain Termine hinzuzufügen, verwendet sie ein Dienstkonto, um im Namen von Nutzern auf die Google Calendar API zuzugreifen. Die Autorisierung eines Dienstkontos für den Zugriff auf Daten im Namen von Nutzern in einer Domain wird manchmal als „delegierte domainweite Autorisierung“ an ein Dienstkonto bezeichnet.

Zum Übertragen einer domainweiten Autorisierung an ein Dienstkonto muss ein Super Admin der Google Workspace-Domain die folgenden Schritte ausführen:

Klicken Sie in der Admin-Konsole Ihrer Google Workspace-Domain auf Hauptmenü > Sicherheit > Zugriff und Datenkontrolle > API-Steuerung.
Wählen Sie im Bereich Domainweite Delegierung die Option Domainweite Delegierung verwalten aus.
Klicken Sie auf Neu hinzufügen.
Geben Sie in das Feld Client-ID die Client-ID des Dienstkontos ein. Die Client-ID Ihres Dienstkontos finden Sie in der Service accounts page.
Geben Sie in das Feld OAuth-Bereiche (kommagetrennt) die Liste der Bereiche ein, auf die Ihre Anwendung Zugriff erhalten soll. Wenn Ihre Anwendung beispielsweise domainweiten Vollzugriff auf die Google Drive API und die Google Calendar API benötigt, geben Sie https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar ein.
Klicken Sie auf Authorize (Autorisieren).

Ihre Anwendung ist jetzt autorisiert, API-Aufrufe als Nutzer in Ihrer Workspace-Domain zu tätigen, um Nutzer zu imitieren. Wenn Sie sich auf die Durchführung dieser delegierten API-Aufrufe vorbereiten, geben Sie den Nutzer explizit an, der imitiert werden soll.

Delegierten API-Aufruf vorbereiten

Java

Nachdem Sie die E-Mail-Adresse und den privaten Schlüssel des Clients von API Consoleabgerufen haben, verwenden Sie die Google APIs-Clientbibliothek für Java, um ein GoogleCredential-Objekt aus den Anmeldedaten des Dienstkontos und den Bereichen zu erstellen, auf die Ihre Anwendung zugreifen muss. Beispiel:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Wenn Sie eine Anwendung auf der Google Cloud Platform entwickeln, können Sie stattdessen die Standardanmeldedaten für Anwendungen verwenden. Das vereinfacht den Vorgang.

Domainweite Befugnis delegieren

Wenn Sie domainweiten Zugriff auf das Dienstkonto delegiert haben und die Identität eines Nutzerkontos übernehmen möchten, geben Sie die E-Mail-Adresse des Nutzerkontos mit der Methode createDelegated des Objekts GoogleCredential an. Beispiel:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

Im Code oben wird das Objekt GoogleCredential verwendet, um die Methode createDelegated() aufzurufen. Das Argument für die Methode createDelegated() muss ein Nutzer sein, der zu Ihrem Workspace-Konto gehört. Der Code, mit dem die Anfrage gesendet wird, verwendet diese Anmeldedaten, um Google APIs mithilfe Ihres Dienstkontos aufzurufen.

Python

Nachdem Sie die Client-E-Mail-Adresse und den privaten Schlüssel von API Consoleabgerufen haben, führen Sie die Google APIs-Clientbibliothek für Python aus, um die folgenden Schritte auszuführen:

Erstellen Sie ein Credentials-Objekt aus den Anmeldedaten des Dienstkontos und den Bereichen, auf die Ihre Anwendung zugreifen muss. Beispiel:
```
from google.oauth2 import service_account

SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
SERVICE_ACCOUNT_FILE = '/path/to/service.json'

credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE, scopes=SCOPES)
```
Wenn Sie eine Anwendung auf der Google Cloud Platform entwickeln, können Sie stattdessen die Standardanmeldedaten für Anwendungen verwenden. Das vereinfacht den Vorgang.
Domainweite Befugnis delegieren
Wenn Sie domainweiten Zugriff auf das Dienstkonto delegiert haben und die Identität eines Nutzerkontos übernehmen möchten, verwenden Sie die Methode with_subject eines vorhandenen ServiceAccountCredentials-Objekts. Beispiel:
```
delegated_credentials = credentials.with_subject('user@example.org')
```

Verwenden Sie das Objekt „Anmeldedaten“, um Google APIs in Ihrer Anwendung aufzurufen.

HTTP/REST

Nachdem Sie die Client-ID und den privaten Schlüssel von API Consoleabgerufen haben, muss Ihre Anwendung die folgenden Schritte ausführen:

Erstellen Sie ein JSON Web Token (JWT, ausgesprochen, „jot“), das einen Header, einen Anspruchssatz und eine Signatur enthält.
Fordern Sie ein Zugriffstoken vom Google OAuth 2.0-Autorisierungsserver an.
Verarbeiten Sie die vom Autorisierungsserver zurückgegebene JSON-Antwort.

In den folgenden Abschnitten wird beschrieben, wie Sie diese Schritte ausführen.

Wenn die Antwort ein Zugriffstoken enthält, können Sie eine Google API aufrufen. Wenn die Antwort kein Zugriffstoken enthält, ist das JWT und die Tokenanfrage möglicherweise nicht korrekt formatiert oder das Dienstkonto hat nicht die Berechtigung, auf die angeforderten Bereiche zuzugreifen.

Wenn das Zugriffstoken abläuft, generiert Ihre Anwendung ein weiteres JWT, signiert es und fordert ein weiteres Zugriffstoken an.

Ihre Serveranwendung verwendet ein JWT, um ein Token vom Google Authorization Server anzufordern und dann das Token, um einen Google API-Endpunkt aufzurufen. Kein Endnutzer.

Im Rest dieses Abschnitts werden die Schritte zum Erstellen eines JWT, zum Signieren des JWT, zum Erstellen der Zugriffstokenanfrage und zum Verarbeiten der Antwort beschrieben.

JWT erstellen

Ein JWT besteht aus drei Teilen: einem Header, einem Anspruchssatz und einer Signatur. Der Header und der Anspruchssatz sind JSON-Objekte. Diese JSON-Objekte werden in UTF-8-Byte serialisiert und dann mit der Base64-URL-Codierung codiert. Diese Codierung bietet Ausfallsicherheit bei Codierungsänderungen aufgrund wiederholter Codierungsvorgänge. Der Header, der Anspruchssatz und die Signatur werden mit einem Punkt (.) verkettet.

Ein JWT setzt sich so zusammen:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

Der Basisstring für die Signatur ist:

{Base64url encoded header}.{Base64url encoded claim set}

JWT-Header bilden

Der Header besteht aus drei Feldern, die den Signaturalgorithmus, das Format der Assertion und die [Schlüssel-ID des Dienstkontoschlüssels](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) angeben, mit dem das JWT signiert wurde. Algorithmus und Format sind obligatorisch und jedes Feld hat nur einen Wert. Durch die Einführung zusätzlicher Algorithmen und Formate ändert sich der Header entsprechend. Die Schlüssel-ID ist optional. Wenn eine falsche Schlüssel-ID angegeben wird, versucht die GCP alle mit dem Dienstkonto verknüpften Schlüssel, das Token zu prüfen und es zu ablehnen, wenn kein gültiger Schlüssel gefunden wird. Google behält sich das Recht vor, Tokens mit falschen Schlüssel-IDs in Zukunft abzulehnen.

Dienstkonten basieren auf dem RSA-SHA-256-Algorithmus und dem JWT-Tokenformat. Die JSON-Darstellung des Headers sieht dann so aus:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

Die Base64url-Darstellung sieht so aus:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

JWT-Anforderungssatz bilden

Der JWT-Anforderungssatz enthält Informationen zum JWT, einschließlich der angeforderten Berechtigungen (Umfang), dem Ziel des Tokens, dem Aussteller, dem Zeitpunkt der Ausstellung und der Lebensdauer des Tokens. Die meisten Felder sind Pflichtfelder. Wie der JWT-Header ist der JWT-Anforderungssatz ein JSON-Objekt und wird bei der Berechnung der Signatur verwendet.

Erforderliche Ansprüche

Die erforderlichen Anforderungen im JWT-Anforderungssatz sind unten aufgeführt. Sie können in beliebiger Reihenfolge im Anspruchssatz erscheinen.

Name	Beschreibung
`iss`	Die E-Mail-Adresse des Dienstkontos.
`scope`	Eine durch Leerzeichen getrennte Liste der Berechtigungen, die die Anwendung anfordert.
`aud`	Eine Beschreibung des vorgesehenen Ziels der Assertion. Wenn Sie eine Zugriffstokenanfrage senden, ist dieser Wert immer `https://oauth2.googleapis.com/token`.
`exp`	Die Ablaufzeit der Assertion, angegeben in Sekunden seit 00:00:00 UTC, 1. Januar 1970. Dieser Wert darf maximal eine Stunde nach der Ausstellungszeit liegen.
`iat`	Der Zeitpunkt, an dem die Assertion ausgestellt wird, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 Uhr (UTC).

Hier ist die JSON-Darstellung der erforderlichen Felder in einem JWT-Anforderungssatz:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Zusätzliche Ansprüche

In einigen Unternehmensfällen kann eine Anwendung die domainweite Delegierung nutzen, um im Namen eines bestimmten Nutzers in einer Organisation zu handeln. Die Berechtigung zum Ausführen dieser Art von Identitätswechsel muss gewährt werden, bevor eine App die Identität eines Nutzers übernehmen kann. Sie wird normalerweise von einem Super Admin verwaltet. Weitere Informationen finden Sie unter API-Zugriff mit domainweiter Delegierung steuern.

Wenn Sie ein Zugriffstoken anfordern, das einer Anwendung delegierten Zugriff auf eine Ressource gewährt, geben Sie die E-Mail-Adresse des Nutzers im Wert für das JWT an, der als Wert im Feld sub festgelegt ist.

Name	Beschreibung
`sub`	Die E-Mail-Adresse des Nutzers, für den die Anwendung den delegierten Zugriff anfordert.

Wenn eine Anwendung nicht berechtigt ist, die Identität eines Nutzers zu übernehmen, ist die Antwort auf eine Zugriffstokenanfrage mit dem Feld sub ein Fehler.

Unten sehen Sie ein Beispiel für einen JWT-Anforderungssatz, der das Feld sub enthält:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

JWT-Anforderungssatz codieren

Wie beim JWT-Header sollte der JWT-Anforderungssatz in UTF-8 und Base64url-safe codiert sein. Hier ein Beispiel für eine JSON-Darstellung eines JWT-Anforderungssatzes:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Signatur berechnen

Die JSON-Websignatur (JWS) ist die Spezifikation, die als Mechanismus beim Generieren der Signatur für das JWT führt. Die Eingabe für die Signatur ist das Byte-Array des folgenden Inhalts:

{Base64url encoded header}.{Base64url encoded claim set}

Der Signaturalgorithmus im JWT-Header muss beim Berechnen der Signatur verwendet werden. Der einzige Signaturalgorithmus, der vom Google OAuth 2.0-Autorisierungsserver unterstützt wird, ist RSA, der den SHA-256-Hash-Algorithmus verwendet. Dies wird im Feld alg des JWT-Headers als RS256 ausgedrückt.

Signieren Sie die UTF-8-Darstellung der Eingabe mit SHA256withRSA (auch RSASSA-PKCS1-V1_5-SIGN mit der SHA-256-Hash-Funktion) mit dem privaten Schlüssel aus Google API Console. Die Ausgabe ist ein Bytearray.

Die Signatur muss dann Base64url-codiert sein. Header, Anspruchssatz und Signatur werden mit einem Punkt (.) verkettet. Das Ergebnis ist das JWT. Folgende Angaben sind zur Verdeutlichung erforderlich:

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Hier ein Beispiel für ein JWT vor der Base64url-Codierung:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Unten siehst du ein Beispiel für ein JWT, das signiert wurde und für die Übertragung bereit ist:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Zugriffstokenanfrage senden

Nachdem das signierte JWT generiert wurde, kann eine Anwendung es verwenden, um ein Zugriffstoken anzufordern. Diese Zugriffstokenanfrage ist eine HTTPS-POST-Anfrage und der Text ist URL-codiert. Die URL sieht so aus:

https://oauth2.googleapis.com/token

Die folgenden Parameter sind in der HTTPS-POST-Anfrage erforderlich:

Name	Beschreibung
`grant_type`	Verwenden Sie den folgenden String und geben Sie bei Bedarf die URL-Codierung an: `urn:ietf:params:oauth:grant-type:jwt-bearer`
`assertion`	Das JWT, einschließlich der Signatur.

Unten sehen Sie einen RAW-Dump der HTTPS-POST-Anfrage, die in einer Zugriffstokenanfrage verwendet wird:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Unten sehen Sie dieselbe Anfrage mit curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Umgang mit der Antwort

Wenn das JWT und die Zugriffstoken-Anfrage korrekt formatiert sind und das Dienstkonto die Berechtigung zum Ausführen des Vorgangs hat, enthält die JSON-Antwort des Autorisierungsservers ein Zugriffstoken. Hier sehen Sie eine Beispielantwort:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Zugriffstokens können während des durch den Wert für expires_in angegebenen Zeitraums wiederverwendet werden.

Google APIs aufrufen

Java

Verwenden Sie das Objekt GoogleCredential, um Google APIs aufzurufen. Führen Sie dazu die folgenden Schritte aus:

Erstellen Sie mit der GoogleCredential ein Dienstobjekt für die API, die Sie aufrufen möchten. Beispiel:
```
SQLAdmin sqladmin =
    new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
```
Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle senden So rufen Sie beispielsweise die Instanzen von Cloud SQL-Datenbanken im Projekt „ spannend-example-123“ auf:
```
SQLAdmin.Instances.List instances =
    sqladmin.instances().list("exciting-example-123").execute();
```

Python

Verwenden Sie das autorisierte Objekt Credentials, um Google APIs aufzurufen. Führen Sie dazu die folgenden Schritte aus:

Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Zum Erstellen eines Dienstobjekts rufen Sie die Funktion build mit dem Namen und der Version der API und dem autorisierten Credentials-Objekt auf. So rufen Sie beispielsweise Version 1beta3 der Cloud SQL Administration API auf:
```
import googleapiclient.discovery

sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
```
Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle senden So rufen Sie beispielsweise die Instanzen von Cloud SQL-Datenbanken im Projekt „ spannend-example-123“ auf:
```
response = sqladmin.instances().list(project='exciting-example-123').execute()
```

HTTP/REST

Nachdem Ihre Anwendung ein Zugriffstoken abgerufen hat, können Sie damit im Namen eines bestimmten Dienstkontos oder Nutzerkontos Aufrufe an eine Google API senden, sofern die von der API benötigten Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_tokenAbfrageparameter oder einen AuthorizationHTTP-HeaderwertBearer angeben. Der HTTP-Header sollte nach Möglichkeit bevorzugt werden, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du eine Clientbibliothek verwenden, um Aufrufe an Google APIs einzurichten, z. B. beim Aufruf der Drive Files API.

Sie können alle Google APIs ausprobieren und sich ihre Bereiche im OAuth 2.0 Playground ansehen.

Beispiele für HTTP GET

Ein Aufruf des Endpunkts drive.files (Drive Files API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen ein eigenes Zugriffstoken angeben:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf an dieselbe API für den authentifizierten Nutzer mithilfe des Abfragestringparameters access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Beispiele für `curl`

Sie können diese Befehle mit der curl-Befehlszeile testen. In diesem Beispiel wird die HTTP-Header-Option (bevorzugt) verwendet:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternativ können Sie den Parameter des Abfragestrings verwenden:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Ablauf von Zugriffstokens

Zugriffstokens, die vom Google OAuth 2.0 Authorization Server ausgestellt wurden, laufen nach der vom expires_in-Wert angegebenen Dauer ab. Wenn ein Zugriffstoken abläuft, sollte die Anwendung ein weiteres JWT generieren, signieren und ein neues Zugriffstoken anfordern.

JWT-Fehlercodes

Feld `error`	Feld `error_description`	Bedeutung	Lösung
`unauthorized_client`	`Unauthorized client or scope in request.`	Wenn Sie versuchen, die domainweite Delegierung zu verwenden, ist das Dienstkonto in der Admin-Konsole der Nutzerdomain nicht autorisiert.	Sorgen Sie dafür, dass das Dienstkonto auf der Seite Domainweite Delegierung der Admin-Konsole für den Nutzer im Feld `sub` autorisiert ist. In der Regel kann es einige Minuten dauern, bis die Autorisierung für alle Nutzer in Ihrem Google-Konto wirksam wird.
`unauthorized_client`	`Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.`	Ein Dienstkonto wurde mit der Client-E-Mail-Adresse anstelle der Client-ID (numerisch) in der Admin-Konsole autorisiert.	Entfernen Sie in der Admin-Konsole auf der Seite Domainweite Delegierung den Client und fügen Sie ihn mit der numerischen ID wieder hinzu.
`access_denied`	(beliebiger Wert)	Wenn Sie die domainweite Delegierung verwenden, ist mindestens ein angeforderter Bereich in der Admin-Konsole nicht autorisiert.	Das Dienstkonto muss auf der Seite Domainweite Delegierung der Admin-Konsole für den Nutzer im Feld `sub` (Feld) autorisiert sein. Außerdem muss es alle Bereiche umfassen, die Sie im `scope`-Anspruch Ihres JWT anfordern. In der Regel kann es einige Minuten dauern, bis die Autorisierung für alle Nutzer in Ihrem Google-Konto wirksam wird.
`admin_policy_enforced`	(beliebiger Wert)	Das Google-Konto kann einen oder mehrere angeforderte Bereiche aufgrund der Richtlinien des Google Workspace-Administrators nicht autorisieren.	Im Hilfeartikel Google Workspace-Daten von Drittanbieter- und internen Apps steuern erfahren Sie, wie ein Administrator den Zugriff auf alle oder vertrauliche sowie eingeschränkte Bereiche einschränken kann, bis der Zugriff auf Ihre OAuth-Client-ID explizit gewährt wird.
`invalid_client`	(beliebiger Wert)	Der OAuth-Client oder das JWT-Token ist ungültig oder falsch konfiguriert. Weitere Informationen finden Sie in der Fehlerbeschreibung.	Das JWT muss gültig sein und korrekte Anforderungen enthalten. Prüfen Sie, ob der OAuth-Client und das Dienstkonto richtig konfiguriert sind und Sie die richtige E-Mail-Adresse verwenden. Prüfe, ob das JWT-Token korrekt ist und für die Client-ID in der Anfrage ausgestellt wurde.
`invalid_grant`	`Not a valid email.`	Der Nutzer ist nicht vorhanden.	Prüfe, ob die E-Mail-Adresse im Feld „`sub`“ korrekt ist.
`invalid_grant`	`Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.`	In der Regel bedeutet dies, dass die lokale Systemzeit nicht korrekt ist. Es kann auch passieren, wenn der `exp`-Wert mehr als 65 Minuten in der Zukunft vom `iat`-Wert liegt oder der `exp`-Wert niedriger als der `iat`-Wert ist.	Achte darauf, dass die Uhr auf dem System, auf dem das JWT generiert wird, korrekt ist. Falls nötig, synchronisieren Sie Ihre Zeit mit Google NTP.
`invalid_grant`	`Invalid JWT Signature.`	Die JWT-Assertion wird mit einem privaten Schlüssel signiert, der nicht mit dem durch die Client-E-Mail-Adresse identifizierten Dienstkonto verknüpft ist oder der verwendete Schlüssel gelöscht, deaktiviert oder abgelaufen ist. Es ist auch möglich, dass die JWT-Assertion falsch codiert ist. Sie muss Base64-codiert sein und keine Zeilenumbrüche oder Leerzeichen enthalten.	Decodieren Sie den JWT-Anforderungssatz und prüfen Sie, ob der Schlüssel, der die Assertion signiert hat, mit dem Dienstkonto verknüpft ist. Verwenden Sie eine von Google bereitgestellte OAuth-Bibliothek, um zu prüfen, ob das JWT korrekt generiert wird.
`invalid_scope`	`Invalid OAuth scope or ID token audience provided.`	Es wurden keine Bereiche angefordert (leere Liste von Bereichen) oder einer der angeforderten Bereiche existiert nicht (d.h. ist ungültig).	Achte darauf, dass die `scope`-Anforderung (Feld) des JWT ausgefüllt ist. Vergleiche die Bereiche, die es enthält, mit den dokumentierten Bereichen der APIs, die du verwenden möchtest, um Fehler und Tippfehler auszuschließen. Die Liste der Bereiche im Anspruch `scope` muss durch Leerzeichen und nicht durch Kommas getrennt werden.
`disabled_client`	`The OAuth client was disabled.`	Der Schlüssel, der zum Signieren der JWT-Assertion verwendet wird, ist deaktiviert.	Rufen Sie Google API Consoleauf und aktivieren Sie unter IAM und Verwaltung > Dienstkonten das Dienstkonto, das die „Schlüssel-ID“ enthält, mit der die Assertion signiert wird.
`org_internal`	`This client is restricted to users within its organization.`	Die OAuth-Client-ID in der Anfrage ist Teil eines Projekts, das den Zugriff auf Google-Konten in einer bestimmten Google Cloud-Organisation einschränkt.	Verwenden Sie dazu ein Dienstkonto der Organisation. Bestätigen Sie die Nutzertypkonfiguration für Ihre OAuth-Anwendung.

Zusatz: Autorisierung ohne Dienstkonto

Bei einigen Google APIs können Sie autorisierte API-Aufrufe mit einem signierten JWT direkt als Inhabertoken anstelle eines OAuth 2.0-Zugriffstokens ausführen. Wenn dies möglich ist, können Sie verhindern, dass eine Netzwerkanfrage an den Autorisierungsserver von Google gesendet wird, bevor Sie einen API-Aufruf ausführen.

Wenn für die API, die Sie aufrufen möchten, im GitHub-Repository von Google APIs eine Dienstdefinition angegeben ist, können Sie autorisierte API-Aufrufe mit einem JWT anstelle eines Zugriffstokens ausführen. Anleitung:

Erstellen Sie wie oben beschrieben ein Dienstkonto. Behalten Sie die JSON-Datei, die Sie beim Erstellen des Kontos erhalten.

Erstellen Sie mit einer beliebigen JWT-Standardbibliothek, z. B. unter jwt.io, ein JWT mit einem Header und einer Nutzlast wie im folgenden Beispiel:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "abcdef1234567890"
}
.
{
  "iss": "123456-compute@developer.gserviceaccount.com",
  "sub": "123456-compute@developer.gserviceaccount.com",
  "aud": "https://firestore.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600
}

Geben Sie im Feld kid im Header die private Schlüssel-ID Ihres Dienstkontos an. Sie finden diesen Wert im Feld private_key_id der JSON-Datei Ihres Dienstkontos.
Geben Sie in den Feldern iss und sub die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert im Feld client_email der JSON-Datei Ihres Dienstkontos.
Geben Sie im Feld aud den API-Endpunkt an. Beispiel: https://SERVICE.googleapis.com/.
Geben Sie für das Feld iat die aktuelle Unix-Zeit und für das Feld exp die Uhrzeit genau 3600 Sekunden später an, wenn das JWT abläuft.

Signieren Sie das JWT mit RSA-256 mit dem privaten Schlüssel aus Ihrer JSON-Dienstkontodatei.

Beispiel:

Java

Mit google-api-java-client und java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Mit PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

Rufen Sie die API mit dem signierten JWT als Inhabertoken auf:

GET /v1/projects/abc/databases/123/indexes HTTP/1.1
Authorization: Bearer SIGNED_JWT
Host: firestore.googleapis.com

Einsatz von OAuth 2.0 für Server-zu-Server-Anwendungen

Übersicht

Dienstkonto erstellen

Domainweite Autorisierung an das Dienstkonto delegieren

Delegierten API-Aufruf vorbereiten

Java

Domainweite Befugnis delegieren

Python

HTTP/REST

JWT erstellen

JWT-Header bilden

JWT-Anforderungssatz bilden

Erforderliche Ansprüche

Zusätzliche Ansprüche

JWT-Anforderungssatz codieren

Signatur berechnen

Zugriffstokenanfrage senden

Umgang mit der Antwort

Google APIs aufrufen

Java

Python

HTTP/REST

Beispiele für HTTP GET

Beispiele für curl

Ablauf von Zugriffstokens

JWT-Fehlercodes

Zusatz: Autorisierung ohne Dienstkonto

Java

Python

Beispiele für `curl`