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

. Weitere Informationen finden Sie unter Authentifizierung in der Dokumentation zur Google Cloud Platform.

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.

Bei einigen Google APIs können Sie autorisierte API-Aufrufe mit einem signierten JWT statt mit OAuth 2.0 ausführen. Dadurch sparen Sie eine Netzwerkanfrage. Weitere Informationen finden Sie unter Zusatz: Dienstkontoautorisierung ohne OAuth.

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

Empfehlung:Ihre Anwendung kann diese Aufgaben entweder über die Google API-Clientbibliothek für Ihre Sprache oder über die direkte Interaktion mit dem OAuth 2.0-System über HTTP ausführen. Die Mechanismen der Server-zu-Server-Authentifizierungsinteraktionen erfordern jedoch, dass Anwendungen JSON-Web-Tokens (JWTs) erstellen und kryptografisch signieren. Außerdem können leicht schwerwiegende Fehler gemacht werden, die die Sicherheit Ihrer Anwendung erheblich beeinträchtigen können.

Aus diesem Grund empfehlen wir dringend die Verwendung von Bibliotheken wie den Google APIs-Clientbibliotheken, die die Kryptografie von Ihrem Anwendungscode abstrahieren.

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:

1. Open the Service accounts page.
2. If prompted, select a project, or create a new one.
3. Click  Create service account.
4. Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
5. Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
6. Click Continue.
7. Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
8. Click Done.

Next, create a service account key:

1. Click the email address for the service account you created.
2. Click the Keys tab.
3. In the Add key drop-down list, select Create new key.
4. 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.

Hinweis:Private Schlüssel müssen sowohl in Entwicklungs- als auch in Produktionsumgebungen sicher gespeichert und verwaltet werden. Google speichert keine Kopie Ihrer privaten Schlüssel, sondern nur Ihre öffentlichen Schlüssel. Weitere Informationen finden Sie im Abschnitt Client-Anmeldedaten sicher in OAuth 2.0-Richtlinien verwalten.

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.

Hinweis: Wenn Sie eine Anwendung für Ihre Domain mit dem Google Workspace Marketplace installieren, werden der Anwendung während der Installation automatisch die erforderlichen Berechtigungen gewährt. Sie müssen die von der Anwendung verwendeten Dienstkonten nicht manuell autorisieren.

Hinweis: Sie können Dienstkonten in Anwendungen verwenden, die über eine Google Workspace-Domain ausgeführt werden. Dienstkonten sind jedoch keine Mitglieder Ihres Google Workspace-Kontos und unterliegen nicht den von Google Workspace-Administratoren festgelegten Domainrichtlinien. Beispielsweise gilt eine Richtlinie, die in der Admin-Konsole von Google Workspace festgelegt ist, um die Fähigkeit von Google Workspace-Endnutzern zu beschränken, Dokumente außerhalb der Domain freizugeben, nicht auf Dienstkonten.

Damit eine domainweite Autorität an ein Dienstkonto delegiert werden kann, muss ein Super Admin der Google Workspace-Domain die folgenden Schritte ausführen:

1. Gehen Sie in der Admin-Konsole Ihrer Google Workspace-Domain zu Hauptmenü > Sicherheit > Zugriff und Datenkontrolle > API-Steuerelemente.
2. Wählen Sie im Bereich Domainweite Delegierung die Option Domainweite Delegierung verwalten aus.
3. Klicken Sie auf Neu hinzufügen.
4. Geben Sie in das Feld Client-ID die Client-ID des Dienstkontos ein. Sie finden die Client-ID Ihres Dienstkontos in Service accounts page.
5. 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.
6. 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.

Hinweis: Nach dem Hinzufügen der Client-ID dauert es in der Regel einige Minuten, bis der Identitätswechsel gewährt wird. In einigen Fällen kann es jedoch bis zu 24 Stunden dauern, bis die Änderungen für alle Nutzer Ihres Google-Kontos wirksam werden.

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("[e-mail]");

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:

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

2. 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 vorhandenen ServiceAccountCredentials-Objekts. Beispiel:

   delegated_credentials = credentials.with_subject('[e-mail]')

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

HTTP/REST

Empfehlung:Obwohl Ihre Anwendung diese Aufgaben über die direkte Interaktion mit dem OAuth 2.0-System über HTTP ausführen kann, müssen Anwendungen für die Interaktion mit der Server-zu-Server-Authentifizierung in Anwendungen JSON-Web-Tokens (JWTs) erstellen und kryptografisch signieren. Außerdem können leicht schwerwiegende Fehler auftreten, die die Sicherheit Ihrer Anwendung gefährden können.

Aus diesem Grund empfehlen wir dringend die Verwendung von Bibliotheken wie den Google APIs-Clientbibliotheken, die die Kryptografie von Ihrem Anwendungscode abstrahieren.

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

1. Erstellen Sie ein JSON-Webtoken (JWT, ausgesprochen, „jot“), das einen Header, einen Anforderungssatz und eine Signatur enthält.
2. Fordern Sie ein Zugriffstoken vom Google OAuth 2.0-Autorisierungsserver an.
3. 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": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "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":"[e-mail]",
"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:

1. 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();

2. 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:

1. 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)

2. 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 sub autorisiert sein (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 sub autorisiert ist und ob alle Bereiche enthalten sind, die Sie im scope-Anspruch Ihres JWT anfordern. 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	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.	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 scope-Anforderung (Feld) des JWT ausgefüllt ist und vergleiche die darin enthaltenen Bereiche mit den dokumentierten Bereichen für die APIs, die du verwenden möchtest, um sicherzustellen, dass es keine Fehler oder Tippfehler gibt. Die Liste der Bereiche in der scope-Anforderung 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 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:

1. Erstellen Sie ein Dienstkonto wie oben beschrieben. Behalten Sie die JSON-Datei, die Sie beim Erstellen des Kontos erhalten.
2. 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": "[e-mail]",
     "sub": "[e-mail]",
     "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 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("[e-mail]")
        .withSubject("[e-mail]")
        .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': '[e-mail]',
           'sub': '[e-mail]',
           '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')

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