Verwenden von OAuth 2.0 für Webserveranwendungen

In diesem Dokument wird erläutert, wie Webserveranwendungen Google API-Clientbibliotheken oder Google OAuth 2.0-Endpunkte verwenden, um die OAuth 2.0-Autorisierung für den Zugriff auf Google APIs zu implementieren.

Mit OAuth 2.0 können Nutzer bestimmte Daten für eine Anwendung freigeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung OAuth 2.0 verwenden, um die Berechtigung von Nutzern zum Speichern von Dateien in Google Drive zu erhalten.

Dieser OAuth 2.0-Vorgang ist speziell für die Nutzerautorisierung vorgesehen. Es wurde für Anwendungen entwickelt, die vertrauliche Informationen speichern und ihren Zustand beibehalten können. Eine ordnungsgemäß autorisierte Webserveranwendung kann auf eine API zugreifen, während der Nutzer mit der Anwendung interagiert oder nachdem er die Anwendung verlassen hat.

Webserveranwendungen verwenden häufig auch Dienstkonten, um API-Anfragen zu autorisieren, insbesondere wenn Cloud APIs aufgerufen wird, um auf projektbasierte und nicht auf nutzerspezifische Daten zuzugreifen. Webserveranwendungen können Dienstkonten in Verbindung mit der Nutzerautorisierung verwenden.

Clientbibliotheken

In den sprachspezifischen Beispielen auf dieser Seite wird die Google API-Clientbibliothek verwendet, um die OAuth 2.0-Autorisierung zu implementieren. Zum Ausführen der Codebeispiele müssen Sie zuerst die Clientbibliothek für Ihre Sprache installieren.

Wenn Sie eine Google API-Clientbibliothek verwenden, um den OAuth 2.0-Vorgang Ihrer Anwendung zu verarbeiten, führt die Clientbibliothek viele Aktionen aus, die die Anwendung andernfalls selbst ausführen müsste. Er bestimmt beispielsweise, wann die Anwendung gespeicherte Zugriffstokens verwenden oder aktualisieren darf und wann die Anwendung eine Einwilligung einholen muss. Die Clientbibliothek generiert auch korrekte Weiterleitungs-URLs und hilft bei der Implementierung von Weiterleitungs-Handlern, die Autorisierungscodes gegen Zugriffstokens austauschen.

Google API-Clientbibliotheken für serverseitige Anwendungen sind für die folgenden Sprachen verfügbar:

Voraussetzungen

Die APIs für Ihr Projekt aktivieren

Jede Anwendung, die Google APIs aufruft, muss diese APIs in der API Consoleaktivieren.

So aktivieren Sie eine API für Ihr Projekt:

  1. Open the API Library im Google API Console.
  2. If prompted, select a project, or create a new one.
  3. In der API Library sind alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie danach suchen oder sie in der entsprechenden Produktfamilie auf Alle ansehen klicken.
  4. Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie dann auf die Schaltfläche Aktivieren.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Anmeldedaten für die Autorisierung erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss Anmeldedaten für die Autorisierung der Anwendung für den OAuth 2.0-Server von Google haben. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

  1. Go to the Credentials page.
  2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
  3. Wählen Sie den Anwendungstyp Webanwendung aus.
  4. Füllen Sie das Formular aus und klicken Sie auf Erstellen. Anwendungen, die Sprachen und Frameworks wie PHP, Java, Python, Ruby und .NET verwenden, müssen autorisierte Weiterleitungs-URIs angeben. Die Weiterleitungs-URIs sind die Endpunkte, an die der OAuth 2.0-Server Antworten senden kann. Diese Endpunkte müssen den Validierungsregeln von Google entsprechen.

    Zum Testen können Sie URIs angeben, die auf den lokalen Computer verweisen, z. B. http://localhost:8080. Beachten Sie daher, dass in allen Beispielen in diesem Dokument http://localhost:8080 als Weiterleitungs-URI verwendet wird.

    Wir empfehlen, die Auth-Endpunkte Ihrer Anwendung so zu gestalten, dass Ihre Anwendung keine Autorisierungscodes für andere Ressourcen auf der Seite verfügbar macht.

Laden Sie nach dem Erstellen Ihrer Anmeldedaten die Datei client_secret.json aus API Consoleherunter. Speichern Sie die Datei an einem sicheren Ort, auf den nur Ihre Anwendung zugreifen kann.

Zugriffsbereiche identifizieren

Bereiche ermöglichen es Ihrer Anwendung, nur den erforderlichen Zugriff auf die Ressourcen anzufordern, während Nutzer auch steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht möglicherweise eine inverse Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, auf die Ihre App Zugriff benötigt.

Außerdem empfehlen wir, dass Ihre Anwendung über einen inkrementellen Autorisierungsprozess den Zugriff auf Autorisierungsbereiche anfordert, bei dem Ihre Anwendung den Zugriff auf Nutzerdaten im Kontext anfordert. Mit dieser Best Practice können Nutzer leichter nachvollziehen, warum Ihre Anwendung Zugriff benötigt.

Das Dokument OAuth 2.0 API-Bereiche enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.

Sprachspezifische Anforderungen

Zum Ausführen eines der Codebeispiele in diesem Dokument benötigen Sie ein Google-Konto, Zugriff auf das Internet und einen Webbrowser. Wenn Sie eine der API-Clientbibliotheken verwenden, gelten außerdem die folgenden sprachspezifischen Anforderungen.

PHP

Zum Ausführen der PHP-Codebeispiele in diesem Dokument benötigen Sie Folgendes:

  • PHP 5.6 oder höher mit installierter Befehlszeile und JSON-Erweiterung
  • Das Abhängigkeitsmanagement-Tool Composer
  • Die Google APIs-Clientbibliothek für PHP:

    composer require google/apiclient:^2.10

Python

Zum Ausführen der Python-Codebeispiele in diesem Dokument benötigen Sie Folgendes:

  • Python 2.6 oder höher
  • Das Paketverwaltungstool pip
  • Die Google APIs-Clientbibliothek für Python:
    pip install --upgrade google-api-python-client
  • google-auth, google-auth-oauthlib und google-auth-httplib2 für die Nutzerautorisierung.
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • Das Flask-Python-Framework für Webanwendungen.
    pip install --upgrade flask
  • Die HTTP-Bibliothek requests.
    pip install --upgrade requests

Ruby

Sie benötigen Folgendes, um die Ruby-Codebeispiele in diesem Dokument auszuführen:

  • Ruby 2.2.2 oder höher
  • Die Google APIs-Clientbibliothek für Ruby:

    gem install google-api-client
  • Das Sinatra Ruby-Webanwendungs-Framework.

    gem install sinatra

Node.js

Zum Ausführen der Node.js-Codebeispiele in diesem Dokument benötigen Sie Folgendes:

  • Der Wartungs-Langzeitsupport, der aktive Langzeitsupport oder der aktuelle Release von Node.js.
  • Der Google APIs-Node.js-Client:

    npm install googleapis

HTTP/REST

Sie müssen keine Bibliotheken installieren, um die OAuth 2.0-Endpunkte direkt aufrufen zu können.

OAuth 2.0-Zugriffstoken abrufen

Die folgenden Schritte zeigen, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung eines Nutzers einzuholen, eine API-Anfrage im Namen des Nutzers auszuführen. Ihre Anwendung muss diese Einwilligung haben, bevor sie eine Google API-Anfrage ausführen kann, die eine Nutzerautorisierung erfordert.

In der folgenden Liste sind diese Schritte zusammengefasst:

  1. Ihre Anwendung identifiziert die erforderlichen Berechtigungen.
  2. Ihre Anwendung leitet den Nutzer zusammen mit der Liste der angeforderten Berechtigungen an Google weiter.
  3. Der Nutzer entscheidet, ob er der Anwendung die Berechtigungen erteilt.
  4. Ihre Anwendung ermittelt, was der Nutzer entschieden hat.
  5. Wenn der Nutzer die angeforderten Berechtigungen erteilt hat, ruft die Anwendung Tokens ab, die für API-Anfragen im Namen des Nutzers erforderlich sind.

Schritt 1: Autorisierungsparameter festlegen

Im ersten Schritt erstellen Sie die Autorisierungsanfrage. Diese Anfrage legt Parameter fest, die Ihre Anwendung identifizieren und die Berechtigungen definieren, die der Nutzer für Ihre Anwendung erhält.

  • Wenn Sie eine Google-Clientbibliothek für die OAuth 2.0-Authentifizierung und -Autorisierung verwenden, erstellen und konfigurieren Sie ein Objekt, das diese Parameter definiert.
  • Wenn du den Google OAuth 2.0-Endpunkt direkt aufrufst, wird eine URL generiert und die Parameter für diese URL festgelegt.

Die folgenden Tabs definieren die unterstützten Autorisierungsparameter für Webserveranwendungen. In den sprachspezifischen Beispielen wird auch gezeigt, wie Sie mit einer Clientbibliothek oder Autorisierungsbibliothek ein Objekt konfigurieren, das diese Parameter festlegt.

PHP

Mit dem Code-Snippet unten wird ein Google\Client()-Objekt erstellt, mit dem die Parameter in der Autorisierungsanfrage definiert werden.

Dieses Objekt verwendet Informationen aus Ihrer Datei client_secret.json, um Ihre Anwendung zu identifizieren. Weitere Informationen zu dieser Datei finden Sie unter Anmeldedaten erstellen. Das Objekt identifiziert auch die Bereiche, für die Ihre Anwendung die Zugriffsberechtigung anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, der die Antwort vom OAuth 2.0-Server von Google verarbeitet. Schließlich werden durch den Code die optionalen Parameter access_type und include_granted_scopes festgelegt.

Dieser Code fordert beispielsweise schreibgeschützten Offlinezugriff auf Google Drive eines Nutzers an:

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" ensures that your application always receives a refresh token.
// If you are not using offline access, you can omit this.
$client->setApprovalPrompt('consent');
$client->setIncludeGrantedScopes(true);   // incremental auth

Die Anfrage enthält die folgenden Informationen:

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in API Console Credentials page.

Rufen Sie in PHP die Funktion setAuthConfig auf, um Anmeldedaten für die Autorisierung aus einer Datei client_secret.json zu laden.

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
redirect_uri Erforderlich

Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Autorisierungsvorgang abgeschlossen wurde. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den du in der API Console Credentials pagedeines Clients konfiguriert hast. Wenn dieser Wert nicht mit einem autorisierten Weiterleitungs-URI für den angegebenen client_id übereinstimmt, wird der Fehler redirect_uri_mismatch angezeigt.

Das http- oder das https-Schema, die Groß-/Kleinschreibung und der nachgestellte Schrägstrich („/“) müssen übereinstimmen.

Rufen Sie die Funktion setRedirectUri auf, um diesen Wert in PHP festzulegen. Du musst einen gültigen Weiterleitungs-URI für die angegebene client_id angeben.

$client->setRedirectUri('https://oauth2.example.com/code');
scope Erforderlich

Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte bilden die Grundlage für den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.

Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können auch steuern, welche Zugriffsrechte sie Ihrer Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

Rufen Sie die Funktion addScope auf, um diesen Wert in PHP festzulegen:

$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

Wir empfehlen, dass Ihre Anwendung wenn möglich Zugriff auf Autorisierungsbereiche anfordert. Wenn Sie den Zugriff auf Nutzerdaten kontextbezogen anfordern, können Sie mithilfe von inkrementeller Autorisierung besser nachvollziehen, warum Ihre Anwendung Zugriff benötigt.

access_type Empfohlen

Gibt an, ob Ihre Anwendung Zugriffstoken aktualisieren kann, wenn der Nutzer nicht im Browser vorhanden ist. Gültige Parameterwerte sind online, der Standardwert, und offline.

Legen Sie den Wert auf offline fest, wenn Ihre Anwendung Zugriffstoken aktualisieren muss, wenn der Nutzer nicht im Browser vorhanden ist. Dies ist die Methode zum Aktualisieren von Zugriffstoken, die weiter unten in diesem Dokument beschrieben wird. Mit diesem Wert wird der Google-Autorisierungsserver angewiesen, ein Aktualisierungs-Token und ein Zugriffstoken zurückzugeben, wenn Ihre Anwendung zum ersten Mal einen Autorisierungscode gegen Tokens eintauscht.

Rufen Sie die Funktion setAccessType auf, um diesen Wert in PHP festzulegen:

$client->setAccessType('offline');
state Empfohlen

Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten. Der Server gibt genau den Wert zurück, den Sie in der URL-Abfragekomponente (?) von redirect_uri als name=value-Paar senden, nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat.

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und eine websiteübergreifende Anfragefälschung zu verringern. Da Ihre redirect_uri erraten werden kann, können Sie mit einem state-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den Clientstatus erfasst, können Sie die Antwort validieren. Damit stellen Sie außerdem sicher, dass die Anfrage und die Antwort vom selben Browser stammen, um Sie vor Angriffen wie der websiteübergreifenden Anfragefälschung zu schützen. Ein Beispiel für das Erstellen und Bestätigen eines state-Tokens finden Sie in der Dokumentation zu OpenID Connect.

Rufen Sie die Funktion setState auf, um diesen Wert in PHP festzulegen:

$client->setState($sample_passthrough_value);
include_granted_scopes Optional

Ermöglicht Anwendungen, die inkrementelle Autorisierung zu verwenden, um den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf true festlegen und die Autorisierungsanfrage genehmigt wird, deckt das neue Zugriffstoken auch alle Bereiche ab, denen der Nutzer zuvor Zugriff auf die Anwendung gewährt hat. Beispiele finden Sie im Abschnitt Inkrementelle Autorisierung.

Rufen Sie die Funktion setIncludeGrantedScopes auf, um diesen Wert in PHP festzulegen:

$client->setIncludeGrantedScopes(true);
login_hint Optional

Wenn die Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu füllt er entweder das E-Mail-Feld im Anmeldeformular aus oder wählt die entsprechende Mehrfachanmeldung aus.

Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine sub-Kennung fest, die der Google-ID des Nutzers entspricht.

Rufen Sie die Funktion setLoginHint auf, um diesen Wert in PHP festzulegen:

$client->setLoginHint('None');
prompt Optional

Eine durch Leerzeichen getrennte Liste von Aufforderungen, bei denen der Nutzer eingeblendet wird. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur dann aufgefordert, wenn Ihr Projekt zum ersten Mal Zugriff anfordert. Weitere Informationen finden Sie unter Erneute Einwilligung einholen.

Rufen Sie die Funktion setApprovalPrompt auf, um diesen Wert in PHP festzulegen:

$client->setApprovalPrompt('consent');

Folgende Werte sind möglich:

none Keine Authentifizierungs- oder Einwilligungsbildschirme anzeigen. Darf nicht mit anderen Werten angegeben werden.
consent Nutzer um Einwilligung bitten
select_account Nutzer zur Auswahl eines Kontos auffordern

Python

Im folgenden Code-Snippet wird die Autorisierungsanfrage mit dem Modul google-auth-oauthlib.flow erstellt.

Der Code konstruiert ein Flow-Objekt, das die Anwendung anhand der Informationen aus der Datei client_secret.json identifiziert, die Sie nach dem Erstellen von Anmeldedaten für die Autorisierung heruntergeladen haben. Dieses Objekt identifiziert auch die Bereiche, für die Ihre Anwendung die Zugriffsberechtigung anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, die die Antwort vom OAuth 2.0-Server von Google verarbeitet. Schließlich werden durch den Code die optionalen Parameter access_type und include_granted_scopes festgelegt.

Dieser Code fordert beispielsweise schreibgeschützten Offlinezugriff auf Google Drive eines Nutzers an:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Die Anfrage enthält die folgenden Informationen:

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in API Console Credentials page.

Rufen Sie in Python die Methode from_client_secrets_file auf, um die Client-ID aus einer Datei client_secret.json abzurufen. Sie können auch die Methode from_client_config verwenden, bei der die Clientkonfiguration so übergeben wird, wie sie ursprünglich in einer Clientschlüsseldatei angezeigt wurde, ohne auf die Datei selbst zuzugreifen.

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])
redirect_uri Erforderlich

Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Autorisierungsvorgang abgeschlossen wurde. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den du in der API Console Credentials pagedeines Clients konfiguriert hast. Wenn dieser Wert nicht mit einem autorisierten Weiterleitungs-URI für den angegebenen client_id übereinstimmt, wird der Fehler redirect_uri_mismatch angezeigt.

Das http- oder das https-Schema, die Groß-/Kleinschreibung und der nachgestellte Schrägstrich („/“) müssen übereinstimmen.

Wenn Sie diesen Wert in Python festlegen möchten, legen Sie das Attribut redirect_uri des flow-Objekts fest:

flow.redirect_uri = 'https://oauth2.example.com/code'
scope Erforderlich

Eine Liste der Bereiche, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte bilden die Grundlage für den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.

Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können auch steuern, welche Zugriffsrechte sie Ihrer Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

Verwenden Sie in Python die Methode, mit der Sie client_id festlegen, um die Liste der Bereiche anzugeben.

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

Wir empfehlen, dass Ihre Anwendung wenn möglich Zugriff auf Autorisierungsbereiche anfordert. Wenn Sie den Zugriff auf Nutzerdaten kontextbezogen anfordern, können Sie mithilfe von inkrementeller Autorisierung besser nachvollziehen, warum Ihre Anwendung Zugriff benötigt.

access_type Empfohlen

Gibt an, ob Ihre Anwendung Zugriffstoken aktualisieren kann, wenn der Nutzer nicht im Browser vorhanden ist. Gültige Parameterwerte sind online, der Standardwert, und offline.

Legen Sie den Wert auf offline fest, wenn Ihre Anwendung Zugriffstoken aktualisieren muss, wenn der Nutzer nicht im Browser vorhanden ist. Dies ist die Methode zum Aktualisieren von Zugriffstoken, die weiter unten in diesem Dokument beschrieben wird. Mit diesem Wert wird der Google-Autorisierungsserver angewiesen, ein Aktualisierungs-Token und ein Zugriffstoken zurückzugeben, wenn Ihre Anwendung zum ersten Mal einen Autorisierungscode gegen Tokens eintauscht.

Legen Sie den Parameter access_type in Python fest. Geben Sie dazu access_type als Keyword-Argument an, wenn Sie die Methode flow.authorization_url aufrufen:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
state Empfohlen

Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten. Der Server gibt genau den Wert zurück, den Sie in der URL-Abfragekomponente (?) von redirect_uri als name=value-Paar senden, nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat.

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und eine websiteübergreifende Anfragefälschung zu verringern. Da Ihre redirect_uri erraten werden kann, können Sie mit einem state-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den Clientstatus erfasst, können Sie die Antwort validieren. Damit stellen Sie außerdem sicher, dass die Anfrage und die Antwort vom selben Browser stammen, um Sie vor Angriffen wie der websiteübergreifenden Anfragefälschung zu schützen. Ein Beispiel für das Erstellen und Bestätigen eines state-Tokens finden Sie in der Dokumentation zu OpenID Connect.

Legen Sie den Parameter state in Python fest. Geben Sie dazu state als Keyword-Argument an, wenn Sie die Methode flow.authorization_url aufrufen:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    state=sample_passthrough_value,
    include_granted_scopes='true')
include_granted_scopes Optional

Ermöglicht Anwendungen, die inkrementelle Autorisierung zu verwenden, um den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf true festlegen und die Autorisierungsanfrage genehmigt wird, deckt das neue Zugriffstoken auch alle Bereiche ab, denen der Nutzer zuvor Zugriff auf die Anwendung gewährt hat. Beispiele finden Sie im Abschnitt Inkrementelle Autorisierung.

Legen Sie den Parameter include_granted_scopes in Python fest. Geben Sie dazu include_granted_scopes als Keyword-Argument an, wenn Sie die Methode flow.authorization_url aufrufen:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
login_hint Optional

Wenn die Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu füllt er entweder das E-Mail-Feld im Anmeldeformular aus oder wählt die entsprechende Mehrfachanmeldung aus.

Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine sub-Kennung fest, die der Google-ID des Nutzers entspricht.

Legen Sie den Parameter login_hint in Python fest. Geben Sie dazu login_hint als Keyword-Argument an, wenn Sie die Methode flow.authorization_url aufrufen:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    login_hint='None',
    include_granted_scopes='true')
prompt Optional

Eine durch Leerzeichen getrennte Liste von Aufforderungen, bei denen der Nutzer eingeblendet wird. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur dann aufgefordert, wenn Ihr Projekt zum ersten Mal Zugriff anfordert. Weitere Informationen finden Sie unter Erneute Einwilligung einholen.

Legen Sie den Parameter prompt in Python fest. Geben Sie dazu prompt als Keyword-Argument an, wenn Sie die Methode flow.authorization_url aufrufen:

authorization_url, state = flow.authorization_url(
      access_type='offline',
      prompt='consent',
      include_granted_scopes='true')

Folgende Werte sind möglich:

none Keine Authentifizierungs- oder Einwilligungsbildschirme anzeigen. Darf nicht mit anderen Werten angegeben werden.
consent Nutzer um Einwilligung bitten
select_account Nutzer zur Auswahl eines Kontos auffordern

Ruby

Verwenden Sie die von Ihnen erstellte Datei client_secrets.json, um ein Clientobjekt in Ihrer Anwendung zu konfigurieren. Wenn Sie ein Clientobjekt konfigurieren, geben Sie die Bereiche an, auf die Ihre Anwendung zugreifen muss, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, die die Antwort vom OAuth 2.0-Server verarbeitet.

Dieser Code fordert beispielsweise schreibgeschützten Offlinezugriff auf Google Drive eines Nutzers an:

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'

client_secrets = Google::APIClient::ClientSecrets.load
auth_client = client_secrets.to_authorization
auth_client.update!(
  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
  :redirect_uri => 'http://www.example.com/oauth2callback',
  :additional_parameters => {
    "access_type" => "offline",         # offline access
    "include_granted_scopes" => "true"  # incremental auth
  }
)

Ihre Anwendung verwendet das Clientobjekt, um OAuth 2.0-Vorgänge auszuführen, z. B. Autorisierungs-URLs zu generieren und Zugriffstoken auf HTTP-Anfragen anzuwenden.

Node.js

Mit dem Code-Snippet unten wird ein google.auth.OAuth2-Objekt erstellt, mit dem die Parameter in der Autorisierungsanfrage definiert werden.

Dieses Objekt verwendet Informationen aus Ihrer client_secret.json-Datei, um Ihre Anwendung zu identifizieren. Wenn Sie Nutzer um die Berechtigung zum Abrufen eines Zugriffstokens bitten möchten, leiten Sie den Nutzer auf eine Einwilligungsseite weiter. So erstellen Sie die URL einer Einwilligungsseite:

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

Wichtiger Hinweis: Der refresh_token wird nur bei der ersten Autorisierung zurückgegeben. Weitere Informationen

HTTP/REST

Der OAuth 2.0-Endpunkt von Google befindet sich unter https://accounts.google.com/o/oauth2/v2/auth. Auf diesen Endpunkt kann nur über HTTPS zugegriffen werden. Einfache HTTP-Verbindungen werden abgelehnt.

Der Google-Autorisierungsserver unterstützt die folgenden Abfragestringparameter für Webserveranwendungen:

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in API Console Credentials page.

redirect_uri Erforderlich

Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Autorisierungsvorgang abgeschlossen wurde. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den du in der API Console Credentials pagedeines Clients konfiguriert hast. Wenn dieser Wert nicht mit einem autorisierten Weiterleitungs-URI für den angegebenen client_id übereinstimmt, wird der Fehler redirect_uri_mismatch angezeigt.

Das http- oder das https-Schema, die Groß-/Kleinschreibung und der nachgestellte Schrägstrich („/“) müssen übereinstimmen.

response_type Erforderlich

Legt fest, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt.

Legen Sie den Parameterwert für Webserveranwendungen auf code fest.

scope Erforderlich

Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte bilden die Grundlage für den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.

Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können auch steuern, welche Zugriffsrechte sie Ihrer Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

Wir empfehlen, dass Ihre Anwendung wenn möglich Zugriff auf Autorisierungsbereiche anfordert. Wenn Sie den Zugriff auf Nutzerdaten kontextbezogen anfordern, können Sie mithilfe von inkrementeller Autorisierung besser nachvollziehen, warum Ihre Anwendung Zugriff benötigt.

access_type Empfohlen

Gibt an, ob Ihre Anwendung Zugriffstoken aktualisieren kann, wenn der Nutzer nicht im Browser vorhanden ist. Gültige Parameterwerte sind online, der Standardwert, und offline.

Legen Sie den Wert auf offline fest, wenn Ihre Anwendung Zugriffstoken aktualisieren muss, wenn der Nutzer nicht im Browser vorhanden ist. Dies ist die Methode zum Aktualisieren von Zugriffstoken, die weiter unten in diesem Dokument beschrieben wird. Mit diesem Wert wird der Google-Autorisierungsserver angewiesen, ein Aktualisierungs-Token und ein Zugriffstoken zurückzugeben, wenn Ihre Anwendung zum ersten Mal einen Autorisierungscode gegen Tokens eintauscht.

state Empfohlen

Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten. Der Server gibt genau den Wert zurück, den Sie in der URL-Abfragekomponente (?) von redirect_uri als name=value-Paar senden, nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat.

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und eine websiteübergreifende Anfragefälschung zu verringern. Da Ihre redirect_uri erraten werden kann, können Sie mit einem state-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den Clientstatus erfasst, können Sie die Antwort validieren. Damit stellen Sie außerdem sicher, dass die Anfrage und die Antwort vom selben Browser stammen, um Sie vor Angriffen wie der websiteübergreifenden Anfragefälschung zu schützen. Ein Beispiel für das Erstellen und Bestätigen eines state-Tokens finden Sie in der Dokumentation zu OpenID Connect.

include_granted_scopes Optional

Ermöglicht Anwendungen, die inkrementelle Autorisierung zu verwenden, um den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf true festlegen und die Autorisierungsanfrage genehmigt wird, deckt das neue Zugriffstoken auch alle Bereiche ab, denen der Nutzer zuvor Zugriff auf die Anwendung gewährt hat. Beispiele finden Sie im Abschnitt Inkrementelle Autorisierung.

login_hint Optional

Wenn die Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu füllt er entweder das E-Mail-Feld im Anmeldeformular aus oder wählt die entsprechende Mehrfachanmeldung aus.

Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine sub-Kennung fest, die der Google-ID des Nutzers entspricht.

prompt Optional

Eine durch Leerzeichen getrennte Liste von Aufforderungen, bei denen der Nutzer eingeblendet wird. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur dann aufgefordert, wenn Ihr Projekt zum ersten Mal Zugriff anfordert. Weitere Informationen finden Sie unter Erneute Einwilligung einholen.

Folgende Werte sind möglich:

none Keine Authentifizierungs- oder Einwilligungsbildschirme anzeigen. Darf nicht mit anderen Werten angegeben werden.
consent Nutzer um Einwilligung bitten
select_account Nutzer zur Auswahl eines Kontos auffordern

Schritt 2: Weiterleitung zum OAuth 2.0-Server von Google

Leite den Nutzer zum OAuth 2.0-Server von Google weiter, um den Authentifizierungs- und Autorisierungsprozess zu starten. Das ist in der Regel der Fall, wenn Ihre Anwendung zum ersten Mal auf die Daten des Nutzers zugreifen muss. Im Fall der inkrementellen Autorisierung wird dieser Schritt auch ausgeführt, wenn Ihre Anwendung zuerst auf zusätzliche Ressourcen zugreifen muss, auf die sie noch nicht zugreifen darf.

PHP

  1. Generieren Sie eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:
    $auth_url = $client->createAuthUrl();
  2. Nutzer zu $auth_url weiterleiten:
    header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

In diesem Beispiel wird gezeigt, wie der Nutzer mithilfe des Flask-Frameworks für die Autorisierung zur Autorisierungs-URL weitergeleitet wird:

return flask.redirect(authorization_url)

Ruby

  1. Generieren Sie eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:
    auth_uri = auth_client.authorization_uri.to_s
  2. Nutzer zu auth_uri weiterleiten.

Node.js

  1. Verwenden Sie die generierte URL authorizationUrl aus der Methode Schritt 1 generateAuthUrl, um Zugriff vom OAuth 2.0-Server von Google anzufordern.
  2. Nutzer zu authorizationUrl weiterleiten.
    res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Nachdem Sie die Anfrage-URL erstellt haben, leiten Sie den Nutzer dorthin weiter.

Der OAuth 2.0-Server von Google authentifiziert den Nutzer und holt die Zustimmung des Nutzers für Ihre Anwendung ein, um auf die angeforderten Bereiche zuzugreifen. Die Antwort wird über die angegebene Weiterleitungs-URL an die Anwendung zurückgesendet.

Schritt 3: Google fordert den Nutzer zur Einwilligung auf

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewähren soll. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, auf die mit den Autorisierungsanmeldedaten des Nutzers eine Zugriffsberechtigung angefordert wird, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche. Der Nutzer kann dann zustimmen, um Zugriff auf einen oder mehrere Bereiche zu gewähren, die von Ihrer Anwendung angefordert werden, oder die Anfrage abzulehnen.

Ihre Anwendung muss zu diesem Zeitpunkt nichts tun, da sie auf die Antwort des OAuth 2.0-Servers von Google wartet, der angibt, ob ein Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.

Fehler

Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google können anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe Fehlermeldungen für Nutzer anzeigen. Die häufigsten Fehlercodes und Lösungsvorschläge sind unten aufgeführt.

admin_policy_enforced

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.

disallowed_useragent

Der Autorisierungsendpunkt wird in einem eingebetteten User-Agent angezeigt, der gemäß den OAuth 2.0-Richtlinien von Google unzulässig ist.

Android

Diese Fehlermeldung kann unter Android-Entwicklern angezeigt werden, wenn Autorisierungsanfragen in android.webkit.WebView geöffnet werden. Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in für Android oder AppAuth für Android der OpenID Foundation verwenden.

Webentwickler können diesen Fehler erhalten, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google wechselt. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems zulassen, der sowohl Handler für Android-App-Links als auch die Standard-Browser-App enthält. Die Bibliothek Benutzerdefinierte Android-Tabs ist ebenfalls eine unterstützte Option.

iOS

iOS- und macOS-Entwickler erhalten möglicherweise diesen Fehler, wenn Autorisierungsanfragen in WKWebView geöffnet werden. Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für iOS oder AppAuth für iOS der OpenID Foundation verwenden.

Dieser Fehler kann auftreten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google wechselt. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems zulassen, das sowohl Handler für universelle Links als auch die Standard-Browser-App umfasst. Die Bibliothek SFSafariViewController wird ebenfalls unterstützt.

org_internal

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. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel OAuth-Zustimmungsbildschirm einrichten.

invalid_client

Der OAuth-Clientschlüssel ist falsch. Überprüfen Sie die OAuth-Client-Konfiguration, einschließlich der Client-ID und des Secrets, die für diese Anfrage verwendet werden.

invalid_grant

Wenn Sie ein Zugriffstoken aktualisieren oder die inkrementelle Autorisierung verwenden, ist das Token möglicherweise abgelaufen oder ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um Zustimmung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin auftritt, prüfen Sie, ob Ihre Anwendung korrekt konfiguriert wurde und ob Sie die richtigen Tokens und Parameter in Ihrer Anfrage verwenden. Andernfalls wurde das Nutzerkonto möglicherweise gelöscht oder deaktiviert.

redirect_uri_mismatch

Der in der Autorisierungsanfrage übergebene redirect_uri stimmt nicht mit einem autorisierten Weiterleitungs-URI für die OAuth-Client-ID überein. Prüfen Sie autorisierte Weiterleitungs-URIs in Google API Console Credentials page.

Der Parameter redirect_uri kann sich auf den OAuth-Out-of-Band-Vorgang (OOB) beziehen, der verworfen wurde und nicht mehr unterstützt wird. Informationen zum Einbinden der Integration finden Sie im Migrationsleitfaden.

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Der OAuth 2.0-Server antwortet auf die Zugriffsanfrage Ihrer Anwendung mithilfe der in der Anfrage angegebenen URL.

Wenn der Nutzer die Zugriffsanfrage genehmigt, wird in der Antwort ein Autorisierungscode angezeigt. Wenn der Nutzer die Anfrage nicht genehmigt, enthält die Antwort eine Fehlermeldung. Der Autorisierungscode oder die Fehlermeldung, die an den Webserver zurückgegeben werden, wird wie im folgenden Beispiel im Abfragestring angezeigt:

Fehlerantwort:

https://oauth2.example.com/auth?error=access_denied

Antwort eines Autorisierungscodes:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Beispiel für eine OAuth 2.0-Serverantwort

Sie können diesen Ablauf testen, indem Sie auf die folgende Beispiel-URL klicken. Diese URL fordert Lesezugriff auf Metadaten für Dateien in Ihrem Google Drive an:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Nach Abschluss des OAuth 2.0-Vorgangs sollten Sie zu http://localhost/oauth2callback weitergeleitet werden. Wenn der lokale Computer keine Datei an diese Adresse sendet, wird wahrscheinlich der Fehler 404 NOT FOUND zurückgegeben. Der nächste Schritt enthält weitere Details zu den Informationen im URI, wenn der Nutzer zu Ihrer Anwendung zurückgeleitet wird.

Schritt 5: Autorisierungscode für Aktualisierungs- und Zugriffstokens austauschen

Nachdem der Webserver den Autorisierungscode erhalten hat, kann er den Autorisierungscode gegen ein Zugriffstoken austauschen.

PHP

Verwenden Sie die Methode authenticate, um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen:

$client->authenticate($_GET['code']);

Sie können das Zugriffstoken mit der Methode getAccessToken abrufen:

$access_token = $client->getAccessToken();

Python

Verwenden Sie auf der Callback-Seite die Bibliothek google-auth, um die Antwort des Autorisierungsservers zu prüfen. Verwenden Sie dann die Methode flow.fetch_token, um den Autorisierungscode in dieser Antwort gegen ein Zugriffstoken auszutauschen:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

Verwenden Sie die Methode fetch_access_token!, um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen:

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

Verwenden Sie die Methode getToken, um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

Um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen, rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen die folgenden Parameter fest:

Felder
client_id Die Client-ID, die von API Console Credentials pageerhalten wurde.
client_secret Der Clientschlüssel, der von API Console Credentials pageerhalten wurde.
code Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde.
grant_type Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf authorization_code festgelegt werden.
redirect_uri Einer der Weiterleitungs-URIs, die für Ihr Projekt in der API Console Credentials page für die angegebene client_id aufgeführt sind.

Das folgende Snippet zeigt eine Beispielanfrage:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Google antwortet auf diese Anfrage, indem es ein JSON-Objekt mit einem kurzlebigen Zugriffstoken und einem Aktualisierungstoken zurückgibt. Das Aktualisierungstoken wird nur zurückgegeben, wenn Ihre Anwendung den Parameter access_type in der ersten Anfrage an den Autorisierungsserver von Google auf offline gesetzt hat.

Die Antwort umfasst die folgenden Felder:

Felder
access_token Das Token, das Ihre Anwendung zum Autorisieren einer Google API-Anfrage sendet.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
refresh_token Ein Token, mit dem Sie ein neues Zugriffstoken abrufen können. Aktualisierungstokens sind gültig, bis der Nutzer den Zugriff widerruft. Dieses Feld ist in dieser Antwort nur dann vorhanden, wenn Sie den Parameter access_type in der ersten Anfrage an den Autorisierungsserver von Google auf offline setzen.
scope Der von access_token gewährte Zugriffsbereich, ausgedrückt als Liste von Strings, bei denen die Leerzeichen durch Leerzeichen getrennt sind.
token_type Der Typ des zurückgegebenen Tokens. Derzeit ist der Wert dieses Felds immer auf Bearer festgelegt.

Das folgende Snippet zeigt eine Beispielantwort:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Fehler

Beim Austausch des Autorisierungscodes für ein Zugriffstoken kann anstelle der erwarteten Antwort der folgende Fehler auftreten. Die häufigsten Fehlercodes und Lösungsvorschläge sind unten aufgeführt.

invalid_grant

Der angegebene Autorisierungscode ist ungültig oder hat das falsche Format. Fordern Sie einen neuen Code an, indem Sie den OAuth-Prozess neu starten, um den Nutzer noch einmal zur Zustimmung zu bitten.

Google APIs aufrufen

PHP

Führen Sie die folgenden Schritte aus, um Google APIs mit dem Zugriffstoken aufzurufen:

  1. Wenn Sie ein Zugriffstoken auf ein neues Google\Client-Objekt anwenden müssen – z. B. wenn Sie das Zugriffstoken in einer Nutzersitzung gespeichert haben –, verwenden Sie die Methode setAccessToken:
    $client->setAccessToken($access_token);
  2. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Zum Erstellen eines Dienstobjekts geben Sie dem Konstruktor für die API, die Sie aufrufen möchten, ein autorisiertes Google\Client-Objekt an. So rufen Sie beispielsweise die Drive API auf:
    $drive = new Google\Service\Drive($client);
  3. Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle stellen So listen Sie beispielsweise die Dateien im Google Drive-Konto des authentifizierten Nutzers auf:
    $files = $drive->files->listFiles(array())->getItems();

Python

Nachdem Sie ein Zugriffstoken erhalten haben, kann Ihre Anwendung dieses Token verwenden, um API-Anfragen im Namen eines bestimmten Nutzerkontos oder Dienstkontos zu autorisieren. Verwenden Sie die nutzerspezifischen Autorisierungsanmeldedaten, um ein Dienstobjekt für die API zu erstellen, die Sie aufrufen möchten. Danach können Sie dieses Objekt verwenden, um autorisierte API-Anfragen zu stellen.

  1. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Zum Erstellen eines Dienstobjekts rufen Sie die Methode build der googleapiclient.discovery-Bibliothek mit dem Namen und der Version der API und den Nutzeranmeldedaten auf. Beispiel: So rufen Sie Version 2 der Drive API auf:
    from googleapiclient.discovery import build
    
    drive = build('drive', 'v2', credentials=credentials)
  2. Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle stellen So listen Sie beispielsweise die Dateien im Google Drive-Konto des authentifizierten Nutzers auf:
    files = drive.files().list().execute()

Ruby

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

  1. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. So rufen Sie beispielsweise Version 2 der Drive API auf:
    drive = Google::Apis::DriveV2::DriveService.new
  2. Legen Sie die Anmeldedaten für den Dienst fest:
    drive.authorization = auth_client
  3. Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle stellen So listen Sie beispielsweise die Dateien im Google Drive des authentifizierten Nutzers auf:
    files = drive.list_files

Die Autorisierung kann auch pro Methode erfolgen, indem der Parameter options an eine Methode übergeben wird:

files = drive.list_files(options: { authorization: auth_client })

Node.js

Nachdem Sie ein Zugriffstoken abgerufen und das Objekt OAuth2 festgelegt haben, rufen Sie Google APIs mit dem Objekt auf. Ihre Anwendung kann dieses Token verwenden, um API-Anfragen für ein bestimmtes Nutzerkonto oder Dienstkonto zu autorisieren. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten.

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie mit dem Token im Namen eines Nutzerkontos eine Google API aufrufen, wenn der Zugriffsbereich, der für die API erforderlich ist, 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

Vollständiges Beispiel

Im folgenden Beispiel wird eine Liste von Dateien im JSON-Format im Google Drive-Konto eines Nutzers ausgegeben, nachdem er sich authentifiziert hat. Außerdem erhält die Anwendung die Berechtigung, auf die Drive-Metadaten des Nutzers zuzugreifen.

PHP

So führen Sie das Beispiel aus:

  1. Fügen Sie in API Consoledie URL des lokalen Computers der Liste der Weiterleitungs-URLs hinzu. Fügen Sie beispielsweise http://localhost:8080 hinzu.
  2. Erstellen Sie ein neues Verzeichnis und ändern Sie es. Beispiel:
    mkdir ~/php-oauth2-example
    cd ~/php-oauth2-example
  3. Installieren Sie die Google API-Clientbibliothek für PHP mit Composer:
    composer require google/apiclient:^2.10
  4. Erstellen Sie die Dateien index.php und oauth2callback.php mit dem folgenden Inhalt.
  5. Führen Sie das Beispiel mit einem Webserver aus, der für die Bereitstellung von PHP konfiguriert ist. Wenn Sie PHP 5.6 oder höher verwenden, können Sie den integrierten Test-Webserver von PHP verwenden:
    php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google\Service\Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

In diesem Beispiel wird das Flask-Framework verwendet. Er führt eine Webanwendung unter http://localhost:8080 aus, mit der Sie den OAuth 2.0-Vorgang testen können. Wenn Sie diese URL aufrufen, sehen Sie vier Links:

  • API-Anfrage testen:Dieser Link verweist auf eine Seite, auf der eine API-Beispielanfrage ausgeführt wird. Bei Bedarf wird der Autorisierungsvorgang gestartet. Wenn der Vorgang erfolgreich ist, wird auf der Seite die API-Antwort angezeigt.
  • Authentifizierungsablauf direkt testen:Dieser Link verweist auf eine Seite, über die der Nutzer über den Autorisierungsvorgang weitergeleitet wird. Die App fordert die Berechtigung zum Senden autorisierter API-Anfragen im Namen des Nutzers an.
  • Aktuelle Anmeldedaten widerrufen:Dieser Link verweist auf eine Seite, auf der Berechtigungen, die der Nutzer der Anwendung bereits gewährt hat, widerrufen werden.
  • Anmeldedaten für Flask löschen:Über diesen Link werden die in der Flask-Sitzung gespeicherten Autorisierungsanmeldedaten gelöscht. So können Sie sehen, was passieren würde, wenn ein Nutzer, der Ihrer App bereits die Berechtigung erteilt hat, in einer neuen Sitzung eine API-Anfrage ausführen möchte. Außerdem können Sie in der API-Antwort sehen, welche Antwort Ihre App erhalten würde, wenn ein Nutzer Ihrer App Berechtigungen entzogen hätte und die Anfrage weiterhin mit einem widerrufenen Zugriffstoken autorisiert werden müsste.
# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

In diesem Beispiel wird das Sinatra-Framework verwendet.

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'
require 'json'
require 'sinatra'

enable :sessions
set :session_secret, 'setme'

get '/' do
  unless session.has_key?(:credentials)
    redirect to('/oauth2callback')
  end
  client_opts = JSON.parse(session[:credentials])
  auth_client = Signet::OAuth2::Client.new(client_opts)
  drive = Google::Apis::DriveV2::DriveService.new
  files = drive.list_files(options: { authorization: auth_client })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  client_secrets = Google::APIClient::ClientSecrets.load
  auth_client = client_secrets.to_authorization
  auth_client.update!(
    :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
    :redirect_uri => url('/oauth2callback'))
  if request['code'] == nil
    auth_uri = auth_client.authorization_uri.to_s
    redirect to(auth_uri)
  else
    auth_client.code = request['code']
    auth_client.fetch_access_token!
    auth_client.client_secret = nil
    session[:credentials] = auth_client.to_json
    redirect to('/')
  end
end

Node.js

So führen Sie das Beispiel aus:

  1. Fügen Sie in API Consoledie URL des lokalen Computers der Liste der Weiterleitungs-URLs hinzu. Fügen Sie beispielsweise http://localhost hinzu.
  2. Achten Sie darauf, dass ein Wartungs-Langzeitsupport, ein aktiver LTS-Wert oder der aktuelle Release von Node.js installiert ist.
  3. Erstellen Sie ein neues Verzeichnis und ändern Sie es. Beispiel:
    mkdir ~/nodejs-oauth2-example
    cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm:
    npm install googleapis
  5. Erstellen Sie die Dateien main.js mit dem Inhalt unten.
  6. Führen Sie das Beispiel aus:
    node .\main.js

Haupt-JS

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

In diesem Python-Beispiel wird das Flask-Framework und die Requests-Bibliothek verwendet, um den OAuth 2.0-Webflow zu veranschaulichen. Für diesen Ablauf empfehlen wir die Verwendung der Google API-Clientbibliothek für Python. Im Beispiel auf dem Tab „Python“ wird die Clientbibliothek verwendet.

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Weiterleitungs-URI-Validierungsregeln

Google wendet die folgenden Validierungsregeln auf Weiterleitungs-URIs an, um Entwickler beim Schutz ihrer Anwendungen zu unterstützen. Ihre Weiterleitungs-URIs müssen diesen Regeln entsprechen. Weitere Informationen zur Definition von Domain, Host, Pfad, Abfrage, Schema und Nutzerinformationen finden Sie unten in RFC 3986, Abschnitt 3.

Validierungsregeln
Schema

Weiterleitungs-URIs müssen das HTTPS-Schema verwenden, nicht HTTP. Localhost-URIs (einschließlich URIs von localhost-IP-Adressen) sind von dieser Regel ausgenommen.

Organisator

Hosts dürfen keine unformatierten IP-Adressen sein. Localhost-IP-Adressen sind von dieser Regel ausgenommen.

Domain
  • Host-TLDs (Top-Level-Domains) müssen zur öffentlichen Suffixliste gehören.
  • Hostdomains dürfen nicht “googleusercontent.com” sein.
  • Weiterleitungs-URIs dürfen keine Kurz-URL-Domains (z.B. goo.gl) enthalten, es sei denn, die App ist Inhaber der Domain. Wenn eine Anwendung mit einer kürzeren Domain die Weiterleitung zu dieser Domain auswählt, muss der Weiterleitungs-URI außerdem entweder “/google-callback/” im Pfad enthalten oder mit “/google-callback” enden.
  • Nutzerinformationen

    Weiterleitungs-URIs dürfen die Unterkomponente „userinfo“ nicht enthalten.

    Pfad

    Weiterleitungs-URIs dürfen keinen Pfaddurchlauf (auch als Verzeichnis-Backtracking bezeichnet) enthalten, der durch “/..” oder “\..” oder seine URL-Codierung dargestellt wird.

    Suchanfrage

    Weiterleitungs-URIs dürfen keine offenen Weiterleitungen enthalten.

    Fragment

    Weiterleitungs-URIs dürfen die Fragmentkomponente nicht enthalten.

    Zeichen Weiterleitungs-URIs dürfen folgende Zeichen nicht enthalten:
    • Platzhalterzeichen ('*')
    • Nicht druckbare ASCII-Zeichen
    • Ungültige Prozentcodierungen (alle Prozentcodierungen, die nicht der URL-Codierungsform eines Prozentzeichens gefolgt von zwei Hexadezimalziffern folgen)
    • Nullzeichen (ein codiertes NULL-Zeichen, z.B. %00, %C0%80)

    Inkrementelle Autorisierung

    Im OAuth 2.0-Protokoll fordert Ihre Anwendung die Autorisierung für den Zugriff auf Ressourcen an, die durch Bereiche identifiziert werden. Es gilt als Best Practice, die Autorisierung von Ressourcen zum richtigen Zeitpunkt anzufordern. Zur Aktivierung dieser Vorgehensweise unterstützt der Autorisierungsserver von Google die inkrementelle Autorisierung. Mit diesem Feature können Sie Bereiche nach Bedarf anfordern. Wenn der Nutzer die Berechtigung für den neuen Bereich erteilt, wird ein Autorisierungscode zurückgegeben, der gegen ein Token ausgetauscht werden kann, das den Nutzer dem Projekt zugewiesen hat.

    Beispielsweise benötigt eine App, mit der Nutzer Musiktracks testen und Mixe erstellen können, möglicherweise nur sehr wenige Ressourcen bei der Anmeldung, möglicherweise nicht mehr als den Namen der angemeldeten Person. Das Speichern eines abgeschlossenen Mixes würde jedoch Zugriff auf das Google Drive-Konto des Nutzers erfordern. Die meisten Menschen finden es normal, wenn sie nur dann Zugriff auf Google Drive erhalten, wenn die App sie tatsächlich benötigt.

    In diesem Fall fordert die Anwendung zum Zeitpunkt der Anmeldung möglicherweise die Bereiche openid und profile an, um eine grundlegende Anmeldung durchzuführen. Später wird dann der Bereich https://www.googleapis.com/auth/drive.file zum Zeitpunkt der ersten Anfrage angefordert, um eine Kombination zu speichern.

    Zum Implementieren der inkrementellen Autorisierung schließen Sie den normalen Ablauf für das Anfordern eines Zugriffstokens ab. Die Autorisierungsanfrage muss jedoch zuvor gewährte Bereiche enthalten. Bei diesem Ansatz muss Ihre Anwendung nicht mehrere Zugriffstoken verwalten müssen.

    Die folgenden Regeln gelten für ein Zugriffstoken, das über eine inkrementelle Autorisierung abgerufen wird:

    • Mit dem Token können Sie auf Ressourcen zugreifen, die einem der Bereiche entsprechen, die in die neue kombinierte Autorisierung aufgenommen wurden.
    • Wenn Sie das Aktualisierungstoken für die kombinierte Autorisierung verwenden, um ein Zugriffstoken zu erhalten, stellt das Zugriffstoken die kombinierte Autorisierung dar und kann für jeden der in der Antwort enthaltenen scope-Werte verwendet werden.
    • Die kombinierte Autorisierung umfasst alle Bereiche, die der Nutzer dem API-Projekt gewährt hat, auch wenn die Berechtigungen von verschiedenen Clients angefordert wurden. Wenn ein Nutzer beispielsweise über den Desktop-Client einer Anwendung Zugriff auf einen Bereich gewährt und dieser Anwendung dann über einen mobilen Client einen anderen Bereich gewährt, umfasst die kombinierte Autorisierung beide Bereiche.
    • Wenn Sie ein Token widerrufen, das eine kombinierte Autorisierung darstellt, wird der Zugriff auf alle Bereiche dieser Autorisierung im Namen des zugehörigen Nutzers gleichzeitig widerrufen.

    Für die sprachspezifischen Codebeispiele in Schritt 1: Autorisierungsparameter festlegen und die Beispiel-HTTP-/REST-Weiterleitungs-URL in Schritt 2: Weiterleitung an den OAuth 2.0-Server von Google wird die inkrementelle Autorisierung verwendet. Die Codebeispiele unten zeigen auch den Code, den Sie hinzufügen müssen, um die inkrementelle Autorisierung zu verwenden.

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

    Legen Sie in Python das Argument include_granted_scopes auf true fest, damit eine Autorisierungsanfrage zuvor gewährte Bereiche enthält. Es ist sehr möglich, dass include_granted_scopes nicht das einzige Schlüsselwortargument ist, das Sie festgelegt haben, wie im Beispiel unten gezeigt.

    authorization_url, state = flow.authorization_url(
        # Enable offline access so that you can refresh an access token without
        # re-prompting the user for permission. Recommended for web server apps.
        access_type='offline',
        # Enable incremental authorization. Recommended as a best practice.
        include_granted_scopes='true')

    Ruby

    auth_client.update!(
      :additional_parameters => {"include_granted_scopes" => "true"}
    )

    Node.js

    const authorizationUrl = oauth2Client.generateAuthUrl({
      // 'online' (default) or 'offline' (gets refresh_token)
      access_type: 'offline',
      /** Pass in the scopes array defined above.
        * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
      scope: scopes,
      // Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes: true
    });
    

    HTTP/REST

    GET https://accounts.google.com/o/oauth2/v2/auth?
      client_id=your_client_id&
      response_type=code&
      state=state_parameter_passthrough_value&
      scope=https%3A//www.googleapis.com/auth/drive.file&
      redirect_uri=https%3A//oauth2.example.com/code&
      prompt=consent&
      include_granted_scopes=true

    Zugriffstoken aktualisieren (Offlinezugriff)

    Zugriffstoken laufen in regelmäßigen Abständen ab und werden zu ungültigen Anmeldedaten für eine ähnliche API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um seine Berechtigung zu bitten (auch wenn er nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

    • Wenn Sie eine Google API-Clientbibliothek verwenden, aktualisiert das Clientobjekt das Zugriffstoken bei Bedarf, sofern Sie dieses Objekt für den Offlinezugriff konfigurieren.
    • Wenn Sie keine Clientbibliothek verwenden, müssen Sie den access_type-HTTP-Abfrageparameter auf offline setzen, wenn Sie den Nutzer zum OAuth 2.0-Server von Google weiterleiten. In diesem Fall gibt der Autorisierungsserver von Google ein Aktualisierungstoken zurück, wenn Sie einen Autorisierungscode gegen ein Zugriffstoken austauschen. Wenn das Zugriffstoken abläuft (oder zu einem beliebigen anderen Zeitpunkt), können Sie ein Aktualisierungstoken verwenden, um ein neues Zugriffstoken zu erhalten.

    Das Anfordern des Offlinezugriffs ist für alle Anwendungen erforderlich, die auf eine Google API zugreifen müssen, wenn der Nutzer nicht anwesend ist. Beispiel: Eine Anwendung, die Sicherungsdienste ausführt oder Aktionen zu vorab festgelegten Zeiten ausführt, muss in der Lage sein, ihr Zugriffstoken zu aktualisieren, wenn der Nutzer nicht anwesend ist. Der Standardzugriffsstil lautet online.

    Serverseitige Webanwendungen, installierte Anwendungen und Geräte erhalten während der Autorisierung Aktualisierungstokens. Aktualisierungstokens werden normalerweise nicht in clientseitigen JavaScript-Webanwendungen verwendet.

    PHP

    Wenn die Anwendung Offlinezugriff auf eine Google API benötigt, legen Sie den Zugriffstyp des API-Clients auf offline fest:

    $client->setAccessType("offline");

    Nachdem ein Nutzer Offlinezugriff auf die angeforderten Bereiche gewährt hat, können Sie weiterhin den API-Client verwenden, um im Namen des Nutzers auf Google APIs zuzugreifen, wenn der Nutzer offline ist. Das Clientobjekt aktualisiert das Zugriffstoken nach Bedarf.

    Python

    Legen Sie in Python das access_type-Schlüsselwortargument auf offline fest, damit Sie das Zugriffstoken aktualisieren können, ohne den Nutzer noch einmal um die Berechtigung bitten zu müssen. Es ist sehr möglich, dass access_type nicht das einzige Schlüsselwortargument ist, das Sie festgelegt haben, wie im Beispiel unten gezeigt.

    authorization_url, state = flow.authorization_url(
        # Enable offline access so that you can refresh an access token without
        # re-prompting the user for permission. Recommended for web server apps.
        access_type='offline',
        # Enable incremental authorization. Recommended as a best practice.
        include_granted_scopes='true')

    Nachdem ein Nutzer Offlinezugriff auf die angeforderten Bereiche gewährt hat, können Sie weiterhin den API-Client verwenden, um im Namen des Nutzers auf Google APIs zuzugreifen, wenn der Nutzer offline ist. Das Clientobjekt aktualisiert das Zugriffstoken nach Bedarf.

    Ruby

    Wenn die Anwendung Offlinezugriff auf eine Google API benötigt, legen Sie den Zugriffstyp des API-Clients auf offline fest:

    auth_client.update!(
      :additional_parameters => {"access_type" => "offline"}
    )

    Nachdem ein Nutzer Offlinezugriff auf die angeforderten Bereiche gewährt hat, können Sie weiterhin den API-Client verwenden, um im Namen des Nutzers auf Google APIs zuzugreifen, wenn der Nutzer offline ist. Das Clientobjekt aktualisiert das Zugriffstoken nach Bedarf.

    Node.js

    Wenn die Anwendung Offlinezugriff auf eine Google API benötigt, legen Sie den Zugriffstyp des API-Clients auf offline fest:

    const authorizationUrl = oauth2Client.generateAuthUrl({
      // 'online' (default) or 'offline' (gets refresh_token)
      access_type: 'offline',
      /** Pass in the scopes array defined above.
        * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
      scope: scopes,
      // Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes: true
    });
    

    Nachdem ein Nutzer Offlinezugriff auf die angeforderten Bereiche gewährt hat, können Sie weiterhin den API-Client verwenden, um im Namen des Nutzers auf Google APIs zuzugreifen, wenn der Nutzer offline ist. Das Clientobjekt aktualisiert das Zugriffstoken nach Bedarf.

    Zugriffstoken laufen ab. Diese Bibliothek verwendet automatisch ein Aktualisierungstoken, um ein neues Zugriffstoken abzurufen, wenn dieses bald abläuft. Mit dem Token-Ereignis können Sie ganz einfach sicherstellen, dass Sie immer die neuesten Tokens speichern:

    oauth2Client.on('tokens', (tokens) => {
      if (tokens.refresh_token) {
        // store the refresh_token in your secure persistent database
        console.log(tokens.refresh_token);
      }
      console.log(tokens.access_token);
    });

    Dieses Tokenereignis tritt nur bei der ersten Autorisierung auf und Sie müssen Ihre access_type auf offline setzen, wenn Sie die Methode generateAuthUrl aufrufen, um das Aktualisierungstoken zu erhalten. Wenn Sie Ihrer Anwendung die erforderlichen Berechtigungen gewährt haben, ohne die entsprechenden Einschränkungen für den Empfang eines Aktualisierungstokens festzulegen, müssen Sie die Anwendung noch einmal autorisieren, um ein neues Aktualisierungstoken zu erhalten.

    Wenn Sie refresh_token später festlegen möchten, können Sie die Methode setCredentials verwenden:

    oauth2Client.setCredentials({
      refresh_token: `STORED_REFRESH_TOKEN`
    });
    

    Sobald der Client ein Aktualisierungstoken hat, werden Zugriffstokens im nächsten Aufruf an die API automatisch abgerufen und aktualisiert.

    HTTP/REST

    Zum Aktualisieren eines Zugriffstokens sendet die Anwendung eine HTTPS-POST-Anfrage an den Google-Autorisierungsserver (https://oauth2.googleapis.com/token), der die folgenden Parameter enthält:

    Felder
    client_id Die von API Consoleabgerufene Client-ID.
    client_secret Der Clientschlüssel, der von API Consoleabgerufen wird.
    grant_type Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf refresh_token festgelegt werden.
    refresh_token Das vom Autorisierungscode-Austausch zurückgegebene Aktualisierungstoken.

    Das folgende Snippet zeigt eine Beispielanfrage:

    POST /token HTTP/1.1
    Host: oauth2.googleapis.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=your_client_id&
    client_secret=your_client_secret&
    refresh_token=refresh_token&
    grant_type=refresh_token

    Solange der Nutzer der Anwendung keinen Zugriff entzogen hat, gibt der Tokenserver ein JSON-Objekt zurück, das ein neues Zugriffstoken enthält. Das folgende Snippet zeigt eine Beispielantwort:

    {
      "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
      "expires_in": 3920,
      "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
      "token_type": "Bearer"
    }

    Beachten Sie, dass die Anzahl der ausgestellten Aktualisierungstokens begrenzt ist: ein Limit pro Client/Nutzer-Kombination und ein anderes pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

    Token widerrufen

    In manchen Fällen möchte ein Nutzer den Zugriff auf eine Anwendung widerrufen. Ein Nutzer kann den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument unter Websites oder Apps mit Zugriff auf dein Konto entfernen.

    Eine Anwendung kann auch den Zugriff, der ihr gewährt wurde, programmatisch widerrufen. Der programmatische Widerruf ist in Fällen wichtig, in denen ein Nutzer sich abmeldet, eine Anwendung entfernt oder die für eine Anwendung erforderlichen API-Ressourcen sich erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage umfassen, mit der die zuvor für die Anwendung gewährten Berechtigungen entfernt werden.

    PHP

    Rufen Sie revokeToken() auf, um ein Token programmatisch zu widerrufen:

    $client->revokeToken();

    Python

    Wenn Sie ein Token programmatisch widerrufen möchten, senden Sie eine Anfrage an https://oauth2.googleapis.com/revoke, die das Token als Parameter enthält und den Header Content-Type festlegt:

    requests.post('https://oauth2.googleapis.com/revoke',
        params={'token': credentials.token},
        headers = {'content-type': 'application/x-www-form-urlencoded'})

    Ruby

    Wenn Sie ein Token programmatisch widerrufen möchten, senden Sie eine HTTP-Anfrage an den Endpunkt oauth2.revoke:

    uri = URI('https://oauth2.googleapis.com/revoke')
    response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)
    

    Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken hat, wird dieses ebenfalls widerrufen.

    Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der Statuscode der Antwort 200. Bei Fehlerbedingungen wird der Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.

    Node.js

    Wenn Sie ein Token programmatisch widerrufen möchten, stellen Sie eine HTTPS-POST-Anfrage an den Endpunkt /revoke:

    const https = require('https');
    
    // Build the string for the POST request
    let postData = "token=" + userCredential.access_token;
    
    // Options for POST request to Google's OAuth 2.0 server to revoke a token
    let postOptions = {
      host: 'oauth2.googleapis.com',
      port: '443',
      path: '/revoke',
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData)
      }
    };
    
    // Set up the request
    const postReq = https.request(postOptions, function (res) {
      res.setEncoding('utf8');
      res.on('data', d => {
        console.log('Response: ' + d);
      });
    });
    
    postReq.on('error', error => {
      console.log(error)
    });
    
    // Post the request with data
    postReq.write(postData);
    postReq.end();
    

    Der Tokenparameter kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken hat, wird dieses ebenfalls widerrufen.

    Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der Statuscode der Antwort 200. Bei Fehlerbedingungen wird der Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.

    HTTP/REST

    Wenn Sie ein Token programmatisch widerrufen möchten, sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und fügt das Token als Parameter ein:

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
            https://oauth2.googleapis.com/revoke?token={token}

    Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken hat, wird dieses ebenfalls widerrufen.

    Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird der HTTP-Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.