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. Dies ist ein Konto, das zu Ihrer Anwendung und nicht zu einem bestimmten Endnutzer gehört. 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 Begriff „dreibeiniges OAuth“ bezieht sich auf Szenarien, in denen Ihre Anwendung Google APIs im Namen von Endnutzern aufruft und manchmal die Nutzereinwilligung erforderlich ist.
Normalerweise verwendet eine Anwendung ein Dienstkonto, wenn die Anwendung Google APIs verwendet, um mit den eigenen Daten statt mit den Daten eines Nutzers zu arbeiten. Beispiel: Eine Anwendung, die Google Cloud Datastore für die Datenpersistenz verwendet, verwendet ein Dienstkonto, um ihre Aufrufe an die Google Cloud Datastore API zu authentifizieren.
Google Workspace-Domainadministratoren können auch Dienstkonten domainweit autorisieren, 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 mit HTTP abschließen kann.
Übersicht
Erstellen Sie zuerst ein Dienstkonto für Ihr Projekt in , um Server-zu-Server-Interaktionen zu unterstützen. Wenn Sie auf Nutzerdaten für Nutzer in Ihrem Google Workspace-Konto zugreifen möchten, delegieren Sie den domainweiten Zugriff auf das Dienstkonto.
Anschließend bereitet die Anwendung die autorisierten API-Aufrufe vor. Dazu werden die Anmeldedaten des Dienstkontos verwendet, 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 umfassen eine generierte E-Mail-Adresse, die eindeutig ist und mindestens ein Paar aus öffentlichem und privatem Schlüssel enthält. Wenn die domainweite Delegierung aktiviert ist, ist eine Client-ID ebenfalls Teil der Anmeldedaten des Dienstkontos.
Wenn Ihre Anwendung in Google App Engine ausgeführt wird, wird beim Erstellen Ihres Projekts automatisch ein Dienstkonto eingerichtet.
Wenn Ihre Anwendung in Google Compute Engine ausgeführt wird, wird beim Erstellen Ihres Projekts auch automatisch ein Dienstkonto eingerichtet. Sie müssen jedoch beim Erstellen einer Google Compute Engine-Instanz die Bereiche angeben, auf die Ihre Anwendung zugreifen muss. 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 abrufen. So generieren Sie Anmeldedaten für Dienstkonten oder rufen die öffentlichen, bereits generierten Anmeldedaten ab:
First, create a service account:
- Open the Service accounts page.
- If prompted, select a project, or create a new one.
- Click Create service account.
- Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
- Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
- Click Continue.
- Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
- Click Done.
Next, create a service account key:
- Click the email address for the service account you created.
- Click the Keys tab.
- In the Add key drop-down list, select Create new key.
- Click Create.
Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.
Sie können jederzeit zum API Console zurückkehren, um die E-Mail-Adresse, Fingerabdrücke des öffentlichen Schlüssels und andere Informationen anzusehen oder zusätzliche Paare aus öffentlichen und privaten Schlüsseln zu generieren. Weitere Informationen zu Dienstkonto-Anmeldedaten in API Consolefinden Sie unter Dienstkonten in der API ConsoleHilfedatei.
Notieren Sie sich die E-Mail-Adresse des Dienstkontos und speichern Sie die Datei mit dem privaten Schlüssel des Dienstkontos an einem Ort, auf den Ihre Anwendung zugreifen kann. Ihre Anwendung benötigt sie, um autorisierte API-Aufrufe auszuführen.
Domainweite Bevollmächtigung an das Dienstkonto delegieren
Wenn Sie ein Google Workspace-Konto haben, kann ein Administrator der Organisation eine Anwendung autorisieren, im Namen von Nutzern in der Google Workspace-Domain auf Nutzerdaten zuzugreifen. Beispiel: Eine Anwendung, die die Google Calendar API zum Hinzufügen von Terminen zu den Kalendern aller Nutzer in einer Google Workspace-Domain verwendet, würde ein Dienstkonto verwenden, um im Namen der Nutzer auf die Google Calendar API zuzugreifen. Das Autorisieren eines Dienstkontos für den Zugriff auf Daten im Namen von Nutzern in einer Domain wird manchmal als „Übertragen domainweiter Befugnisse“ an ein Dienstkonto bezeichnet.
Damit eine domainweite Autorität an ein Dienstkonto delegiert werden kann, muss ein Super Admin der Google Workspace-Domain die folgenden Schritte ausführen:
- Gehen Sie in der Admin-Konsole Ihrer Google Workspace-Domain zu Hauptmenü > Sicherheit > Zugriff und Datenkontrolle > API-Steuerelemente.
- 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. Sie finden die Client-ID Ihres Dienstkontos in Service accounts page.
- Geben Sie im 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 nun befugt, API-Aufrufe als Nutzer in Ihrer Domain auszuführen (um Nutzer zu imitieren). Wenn Sie sich auf autorisierte API-Aufrufe vorbereiten, geben Sie den Namen des Nutzers an.
Autorisierten API-Aufruf vorbereiten
Java
Nachdem Sie die Client-E-Mail-Adresse und den privaten Schlüssel 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 der Anwendung verwenden, was den Prozess vereinfachen kann.
Domainweite Befugnis
Wenn Sie den 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("user@example.com");
Verwenden Sie das Objekt GoogleCredential
, um Google APIs in Ihrer Anwendung aufzurufen.
Python
Nachdem Sie die Client-E-Mail-Adresse und den privaten Schlüssel von API Consoleabgerufen haben, verwenden Sie die Google APIs-Clientbibliothek für Python, 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 der Anwendung verwenden, was den Prozess vereinfachen kann.
- Domainweite Befugnis
Wenn Sie den domainweiten Zugriff auf das Dienstkonto delegiert haben und die Identität eines Nutzerkontos imitieren 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-Webtoken (JWT, ausgesprochen, „jot“), das einen Header, einen Anforderungssatz 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 damit eine Google API aufrufen. Wenn die Antwort kein Zugriffstoken enthält, ist das JWT und die Tokenanfrage möglicherweise nicht korrekt gebildet oder das Dienstkonto hat möglicherweise keine Berechtigung für den Zugriff auf die angeforderten Bereiche.
Wenn das Zugriffstoken abläuft, generiert Ihre Anwendung ein weiteres JWT, signiert es und fordert ein weiteres Zugriffstoken an.

Im weiteren Verlauf dieses Abschnitts wird beschrieben, wie Sie ein JWT erstellen, das JWT signieren, die Zugriffstokenanfrage formulieren und die Antwort verarbeiten.
JWT erstellen
Ein JWT besteht aus drei Teilen: einem Header, einem Anforderungssatz und einer Signatur. Der Header und der Anforderungssatz 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. Header, Anforderungssatz und 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 lautet so:
{Base64url encoded header}.{Base64url encoded claim set}
JWT-Header bilden
Der Header besteht aus zwei Feldern, die den Signaturalgorithmus und das Format der Assertion angeben. Beide Felder sind obligatorisch und jedes Feld hat nur einen Wert. Wenn zusätzliche Algorithmen und Formate eingeführt werden, ändert sich dieser Header entsprechend.
Dienstkonten basieren auf dem RSA-SHA-256-Algorithmus und dem JWT-Token-Format. Daher sieht die JSON-Darstellung des Headers so aus:
{"alg":"RS256","typ":"JWT"}
Die Base64url-Darstellung hierfür sieht so aus:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
JWT-Anforderungssatz erstellen
Der JWT-Anforderungssatz enthält Informationen zum JWT, einschließlich der angeforderten Berechtigungen (Bereiche), des Ziels des Tokens, des Ausstellers, des Zeitpunkts 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 der Reihenfolge im Anspruchssatz vorkommen.
Name | Beschreibung |
---|---|
iss |
Die E-Mail-Adresse des Dienstkontos. |
scope |
Eine durch Leerzeichen getrennte Liste der Berechtigungen, die die Anwendung anfordert. |
aud |
Beschreibung des beabsichtigten Ziels der Assertion. Bei einer Zugriffstokenanfrage lautet dieser Wert immer https://oauth2.googleapis.com/token . |
exp |
Die Ablaufzeit der Assertion, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 UTC. Der Wert darf maximal eine Stunde nach der Ausstellungszeit liegen. |
iat |
Der Zeitpunkt, an dem die Assertion ausgegeben wurde, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 UTC. |
Die JSON-Darstellung der Pflichtfelder in einem JWT-Anforderungssatz sieht so aus:
{ "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. Berechtigung zum Ausführen dieser Art des Identitätswechsels muss gewährt werden, bevor eine Anwendung die Identität eines Nutzers imitieren kann. Dies ist normalerweise von einem Super Admin der Fall. Weitere Informationen finden Sie unter API-Zugriff mit domainweiter Delegierung steuern.
Wenn Sie ein Zugriffstoken abrufen möchten, mit dem einer Anwendung delegierter Zugriff auf eine Ressource gewährt wird, fügen Sie die E-Mail-Adresse des Nutzers in den JWT-Anforderungssatz als Wert des Felds sub
ein.
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, wird für die Antwort auf eine Zugriffstokenanfrage mit dem Feld sub
ein Fehler ausgegeben.
Im Folgenden finden 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 der JWT-Header sollte der JWT-Anforderungssatz in UTF-8 und Base64url-sicher 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 den Mechanismus zum Generieren der Signatur für das JWT steuert. 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 Authorization Server unterstützt wird, ist RSA, verwendet den SHA-256-Hashing-Algorithmus. Im JWT-Header wird dies im Feld alg
als RS256
ausgedrückt.
Signieren Sie die UTF-8-Darstellung der Eingabe mit SHA256withRSA (auch bekannt als RSASSA-PKCS1-V1_5-SIGN mit der SHA-256-Hash-Funktion) mit dem privaten Schlüssel aus Google API Console. Die Ausgabe ist ein Byte-Array.
Die Signatur muss dann base64url-codiert sein. Header, Anforderungssatz und Signatur werden mit einem Punkt (.
) verkettet. Das Ergebnis ist das JWT. Es sollte so aussehen (Zeilenumbruch):
{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]
Hier ein Beispiel für ein JWT, das signiert und bereit für die Übertragung ist:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ
Anfrage für ein Zugriffstoken stellen
Nachdem das signierte JWT generiert wurde, kann es von einer Anwendung verwendet werden, 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-Anfrage POST
erforderlich:
Name | Beschreibung |
---|---|
grant_type |
Verwenden Sie den folgenden String, falls erforderlich URL-codiert: urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion |
Das JWT, einschließlich Signatur. |
Hier ist ein 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
Hier ist 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
Antwort verarbeiten
Wenn die JWT- und Zugriffstokenanfrage ordnungsgemäß formuliert ist und das Dienstkonto die Berechtigung zum Ausführen des Vorgangs hat, enthält die JSON-Antwort des Autorisierungsservers ein Zugriffstoken. Hier eine Beispielantwort:
{ "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M", "scope": "https://www.googleapis.com/auth/prediction" "token_type": "Bearer", "expires_in": 3600 }
Zugriffstoken können während des durch den Wert expires_in
angegebenen Dauerzeitraums 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 ein Dienstobjekt für die API, die Sie mit dem Objekt
GoogleCredential
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 stellen
So listen 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
Führen Sie die folgenden Schritte aus, um mit dem autorisierten Credentials
-Objekt Google APIs aufzurufen:
- 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 stellen
So listen 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 erhalten hat, können Sie das Token verwenden, um im Namen eines bestimmten Dienstkontos oder Nutzerkontos Aufrufe an eine Google API zu senden, wenn der von der API benötigte Zugriffsbereich(e) gewährt wurde. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token
-Abfrageparameter oder einen Authorization
-HTTP-Header-Bearer
-Wert einbinden. Wenn möglich, ist der HTTP-Header zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie 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 ihre Bereiche im OAuth 2.0 Playground ansehen.
Beispiele für HTTP GET
Ein Aufruf des Endpunkts
drive.files
(Drive File 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 derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter 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. Hier ein Beispiel, bei dem die HTTP-Header-Option (bevorzugt) verwendet wird:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Oder die Option für den Abfragestringparameter:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Ablauf von Zugriffstoken
Zugriffstoken, die vom Google OAuth 2.0 Authorization Server ausgestellt werden, 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. |
Das Dienstkonto muss in der Admin-Konsole auf der Seite
Domainweite Delegierung für den Nutzer im Feld Normalerweise dauert es einige Minuten, bis die Autorisierung für alle Nutzer in Ihrem Google-Konto wirksam wird, kann es bis zu 24 Stunden dauern. |
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 auf der Seite Domainweite Delegierung in der Admin-Konsole den Client und fügen Sie ihn mit der numerischen ID wieder hinzu. |
access_denied |
(beliebiger Wert) | Wenn Sie die domainweite Delegierung verwenden, sind ein oder mehrere angeforderte Bereiche in der Admin-Konsole nicht autorisiert. |
Prüfen Sie, ob das Dienstkonto auf der Seite
Domainweite Delegierung der Admin-Konsole für den Nutzer im Feld Normalerweise dauert es einige Minuten, bis die Autorisierung für alle Nutzer in Ihrem Google-Konto wirksam wird, kann es bis zu 24 Stunden dauern. |
admin_policy_enforced |
(beliebiger Wert) | Das Google-Konto kann einen oder mehrere Bereiche nicht autorisieren, die aufgrund der Richtlinien seines Google Workspace-Administrators angefordert wurden. |
Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten verwalten finden Sie weitere Informationen dazu, wie Administratoren den Zugriff auf alle oder sensible und eingeschränkte Bereiche einschränken können, bis der OAuth-Client-ID explizit Zugriff 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-Token muss gültig sein und die richtigen Anforderungen enthalten. Prüfe, ob der OAuth-Client und das Dienstkonto richtig konfiguriert sind und du die richtige E-Mail-Adresse verwendest. Prüfen Sie, 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 sub -Anspruch (Feld) korrekt ist. |
invalid_grant |
|
Normalerweise bedeutet das, dass die lokale Systemzeit falsch ist. Es kann auch passieren, wenn der Wert von exp mehr als 65 Minuten in der Zukunft vom Wert iat liegt oder der Wert von exp kleiner als der Wert von iat ist. |
Prüfen Sie, ob die Uhrzeit auf dem System korrekt ist, auf dem das JWT generiert wird. Synchronisieren Sie gegebenenfalls Ihre Zeit mit Google NTP. |
invalid_grant |
Invalid JWT Signature. |
Die JWT-Assertion wird mit einem privaten Schlüssel signiert, der nicht mit dem Dienstkonto verknüpft ist, das von der Client-E-Mail-Adresse identifiziert wurde, oder der verwendete Schlüssel wurde gelöscht, deaktiviert oder abgelaufen. Es ist auch möglich, dass die JWT-Assertion falsch codiert ist – sie muss Base64-codiert sein und keine Zeilenumbrüche oder Padding-Zeichen 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, damit das JWT korrekt generiert wird. |
invalid_scope |
Invalid OAuth scope or ID token audience provided. |
Es wurden keine Bereiche angefordert (leere Liste der Bereiche) oder einer der angeforderten Bereiche ist nicht vorhanden (d.h. ist ungültig). |
Achte darauf, dass die Die Liste der Bereiche in der |
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 mit der Schlüssel-ID, die zum Signieren der Assertion verwendet 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 beschränkt. |
Verwenden Sie ein Dienstkonto der Organisation zur Authentifizierung. Bestätigen Sie die Nutzertypkonfiguration für Ihre OAuth-Anwendung. |
Ergänzung: Dienstkontoautorisierung ohne OAuth
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 vermeiden, dass Sie vor dem API-Aufruf eine Netzwerkanfrage an den Autorisierungsserver von Google stellen müssen.
Wenn für die API, die Sie aufrufen möchten, im GitHub-Repository für Google APIs eine Dienstdefinition vorhanden ist, können Sie autorisierte API-Aufrufe mit einem JWT anstelle eines Zugriffstokens ausführen. Anleitung:
- Erstellen Sie ein Dienstkonto wie oben beschrieben. Behalten Sie die JSON-Datei, die Sie beim Erstellen des Kontos erhalten.
- Erstellen Sie mit einer beliebigen Standard-JWT-Bibliothek wie 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 Zeit genau 3.600 Sekunden später an, wenn das JWT abläuft.
Signieren Sie das JWT mit RSA-256 mit dem privaten Schlüssel aus der JSON-Datei Ihres Dienstkontos.
Beispiel:
Java
google-api-java-client und java-jwt verwenden:
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 auf und verwenden Sie das signierte JWT als Inhabertoken:
GET /v1/projects/abc/databases/123/indexes HTTP/1.1 Authorization: Bearer SIGNED_JWT Host: firestore.googleapis.com