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 vorhandenenServiceAccountCredentials
-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.

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 autorisiertenCredentials
-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_token
Abfrageparameter oder einen Authorization
HTTP-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 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 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 |
|
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 Die Liste der Bereiche im Anspruch |
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 Feldprivate_key_id
der JSON-Datei Ihres Dienstkontos. - Geben Sie in den Feldern
iss
undsub
die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert im Feldclient_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 Feldexp
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