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 Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung OAuth 2.0 verwenden, um die Berechtigung der Nutzer zum Speichern von Dateien in Google Drive einzuholen.
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 der Nutzer die Anwendung verlassen hat.
Webserveranwendungen verwenden häufig auch Dienstkonten, um API-Anfragen zu autorisieren, insbesondere wenn Cloud APIs aufgerufen werden, um auf projektbasierte Daten statt auf nutzerspezifische Daten zuzugreifen. Webserveranwendungen können Dienstkonten in Verbindung mit der Nutzerautorisierung verwenden.
Clientbibliotheken
In den sprachspezifischen Beispielen auf dieser Seite werden die Google API-Clientbibliotheken 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 kann und wann die Anwendung eine Einwilligung neu 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 in den 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:
- Open the API Library in der Datei Google API Console.
- If prompted, select a project, or create a new one.
- API Library Listet alle verfügbaren APIs auf, gruppiert nach Produktfamilie und Beliebtheit. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie danach suchen oder sie in der zugehörigen Produktfamilie auf Alle ansehen klicken.
- Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie auf die Schaltfläche Aktivieren.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Anmeldedaten für die Autorisierung erstellen
Alle Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, benötigen Anmeldedaten für die Autorisierung, mit denen die Anwendung für den OAuth 2.0-Server von Google identifiziert wird. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann die Anmeldedaten verwenden, um auf APIs zuzugreifen, die Sie für dieses Projekt aktiviert haben.
- Go to the Credentials page.
- Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
- Wählen Sie den Anwendungstyp Webanwendung aus.
- Füllen Sie das Formular aus und klicken Sie auf Erstellen. Für Anwendungen, die Sprachen und Frameworks wie PHP, Java, Python, Ruby und .NET verwenden, müssen autorisierte Weiterleitungs-URIs angegeben werden. 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 sich auf den lokalen Computer beziehen, z. B.
http://localhost:8080
. Denken Sie daran, dass in allen Beispielen in diesem Dokumenthttp://localhost:8080
als Weiterleitungs-URI verwendet wird.Wir empfehlen dir, die Authentifizierungsendpunkte deiner App zu entwerfen, damit deine 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
Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können außerdem steuern, wie viel Zugriff sie auf Ihre Anwendung gewähren. Daher besteht möglicherweise eine gegenläufige 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 festlegen, für die Ihre App eine Zugriffsberechtigung benötigt.
Wir empfehlen außerdem, dass Ihre Anwendung den Zugriff auf Autorisierungsbereiche über einen schrittweisen Autorisierungsprozess anfordert, bei dem Ihre Anwendung den Zugriff auf Nutzerdaten im Kontext anfordert. Mit dieser Best Practice können Nutzer leichter nachvollziehen, warum Ihre Anwendung den erforderlichen Zugriff benötigt.
Das Dokument OAuth 2.0 API-Bereiche enthält eine vollständige Liste der Bereiche, mit denen Sie möglicherweise auf Google APIs zugreifen können.
Sprachspezifische Anforderungen
Für die Ausführung 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, lesen Sie auch 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 Tool Composer für das Abhängigkeitsmanagement
-
Die Google APIs-Clientbibliothek für PHP:
composer require google/apiclient:^2.10
Python
Zum Ausführen der 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
undgoogle-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
Zum Ausführen der Ruby-Codebeispiele in diesem Dokument benötigen Sie Folgendes:
- 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 Codebeispiele in Node.js in diesem Dokument benötigen Sie Folgendes:
- Der Wartungs-Langzeitsupport, der aktive Langzeitsupport oder der aktuelle Release von Node.js.
-
Der Node.js-Client von Google APIs:
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-Zugriffstokens abrufen
Die folgenden Schritte zeigen, wie deine App mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung des Nutzers zur Ausführung einer API-Anfrage im Namen des Nutzers einzuholen. 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:
- Die Anwendung identifiziert die erforderlichen Berechtigungen.
- Ihre Anwendung leitet den Nutzer zusammen mit der Liste der angeforderten Berechtigungen an Google weiter.
- Der Nutzer entscheidet, ob er der Anwendung die Berechtigungen erteilen soll.
- Ihre Anwendung erfährt, was der Nutzer entschieden hat.
- Wenn der Nutzer die angeforderten Berechtigungen gewährt 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 Sie den Google OAuth 2.0-Endpunkt direkt aufrufen, generieren Sie eine URL und legen die Parameter für diese URL fest.
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
Das folgende Code-Snippet erstellt ein Google\Client()
-Objekt, das die Parameter in der Autorisierungsanfrage definiert.
Dieses Objekt verwendet Informationen aus Ihrer Datei client_secret.json, um Ihre Anwendung zu identifizieren. Weitere Informationen zu dieser Datei finden Sie unter Anmeldedaten für die Autorisierung erstellen. Außerdem identifiziert das Objekt die Bereiche, für die Ihre Anwendung die Berechtigung zum Zugriff anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, die die Antwort vom Google OAuth 2.0-Server verarbeitet. Schließlich werden durch den Code die optionalen Parameter access_type
und include_granted_scopes
festgelegt.
Mit diesem Code wird beispielsweise der schreibgeschützte Offlinezugriff auf das Google Drive-Konto eines Nutzers angefordert:
$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 folgende Informationen:
Parameter | |||||||
---|---|---|---|---|---|---|---|
client_id |
Pflichtfeld
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert im API Console Credentials page. Rufen Sie in PHP die Funktion $client = new Google\Client(); $client->setAuthConfig('client_secret.json'); |
||||||
redirect_uri |
Pflichtfeld
Legt fest, wohin der API-Server den Nutzer weiterleitet, nachdem er den Autorisierungsvorgang abgeschlossen hat. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in Ihrem API Console- Credentials pagekonfiguriert haben. Wenn dieser Wert keinem autorisierten Weiterleitungs-URI für die angegebene Beachten Sie, dass das Rufen Sie die Funktion $client->setRedirectUri('https://oauth2.example.com/code'); |
||||||
scope |
Pflichtfeld
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Anhand dieser Werte wird der Zustimmungsbildschirm angezeigt, den Google dem Nutzer zeigt. Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können außerdem steuern, wie viel Zugriff sie auf Ihre Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. Rufen Sie die Funktion $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); Wir empfehlen, dass Ihre Anwendung nach Möglichkeit Zugriff auf Autorisierungsbereiche im Kontext anfordert. Wenn Sie den Zugriff auf Nutzerdaten im Kontext mithilfe der inkrementellen Autorisierung anfordern, können Nutzer leichter nachvollziehen, warum Ihre Anwendung den angeforderten Zugriff benötigt. |
||||||
access_type |
Empfohlen
Gibt an, ob Ihre Anwendung Zugriffstokens aktualisieren kann, wenn der Nutzer nicht im Browser vorhanden ist. Gültige Parameterwerte sind Legen Sie den Wert auf Rufen Sie die Funktion $client->setAccessType('offline'); |
||||||
state |
Empfohlen
Gibt einen beliebigen Stringwert an, mit dem Ihre Anwendung den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechterhält.
Der Server gibt den genauen Wert zurück, den du als Du kannst diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in deiner Anwendung zu leiten, Benachrichtigungen zu senden und die websiteübergreifende Fälschung von Anfragen zu minimieren. Da Ihr Rufen Sie die Funktion $client->setState($sample_passthrough_value); |
||||||
include_granted_scopes |
Optional
Ermöglicht Anwendungen, über die inkrementelle Autorisierung Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf Rufen Sie die Funktion $client->setIncludeGrantedScopes(true); |
||||||
login_hint |
Optional
Wenn die Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann er mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu wird entweder das E-Mail-Feld im Anmeldeformular vorausgefüllt oder die entsprechende Mehrfachanmeldung-Sitzung ausgewählt. Legen Sie als Parameterwert eine E-Mail-Adresse oder eine Rufen Sie die Funktion $client->setLoginHint('None'); |
||||||
prompt |
Optional
Eine durch Leerzeichen getrennte Liste mit Aufforderungen, bei denen der Nutzer die Groß-/Kleinschreibung beachten muss. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur bei der ersten Anfrage für Ihr Projekt aufgefordert. Weitere Informationen findest du unter Erneute Einwilligung einholen. Rufen Sie die Funktion $client->setApprovalPrompt('consent'); Folgende Werte sind möglich:
|
Python
Das folgende Code-Snippet verwendet das Modul google-auth-oauthlib.flow
, um die Autorisierungsanfrage zu erstellen.
Im Code wird ein Flow
-Objekt erstellt, das Ihre Anwendung anhand von 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 Berechtigung zum Zugriff 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.
Mit diesem Code wird beispielsweise der schreibgeschützte Offlinezugriff auf das Google Drive-Konto eines Nutzers angefordert:
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 folgende Informationen:
Parameter | |||||||
---|---|---|---|---|---|---|---|
client_id |
Pflichtfeld
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert im API Console Credentials page. Rufen Sie in Python die Methode flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) |
||||||
redirect_uri |
Pflichtfeld
Legt fest, wohin der API-Server den Nutzer weiterleitet, nachdem er den Autorisierungsvorgang abgeschlossen hat. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in Ihrem API Console- Credentials pagekonfiguriert haben. Wenn dieser Wert keinem autorisierten Weiterleitungs-URI für die angegebene Beachten Sie, dass das Wenn Sie diesen Wert in Python festlegen möchten, legen Sie das Attribut flow.redirect_uri = 'https://oauth2.example.com/code' |
||||||
scope |
Pflichtfeld
Eine Liste der Bereiche, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Anhand dieser Werte wird der Zustimmungsbildschirm angezeigt, den Google dem Nutzer zeigt. Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können außerdem steuern, wie viel Zugriff sie auf Ihre Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. Verwenden Sie in Python dieselbe Methode, mit der Sie 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 nach Möglichkeit Zugriff auf Autorisierungsbereiche im Kontext anfordert. Wenn Sie den Zugriff auf Nutzerdaten im Kontext mithilfe der inkrementellen Autorisierung anfordern, können Nutzer leichter nachvollziehen, warum Ihre Anwendung den angeforderten Zugriff benötigt. |
||||||
access_type |
Empfohlen
Gibt an, ob Ihre Anwendung Zugriffstokens aktualisieren kann, wenn der Nutzer nicht im Browser vorhanden ist. Gültige Parameterwerte sind Legen Sie den Wert auf Legen Sie in Python den Parameter authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
state |
Empfohlen
Gibt einen beliebigen Stringwert an, mit dem Ihre Anwendung den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechterhält.
Der Server gibt den genauen Wert zurück, den du als Du kannst diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in deiner Anwendung zu leiten, Benachrichtigungen zu senden und die websiteübergreifende Fälschung von Anfragen zu minimieren. Da Ihr Legen Sie in Python den Parameter authorization_url, state = flow.authorization_url( access_type='offline', state=sample_passthrough_value, include_granted_scopes='true') |
||||||
include_granted_scopes |
Optional
Ermöglicht Anwendungen, über die inkrementelle Autorisierung Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf Legen Sie in Python den Parameter authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
login_hint |
Optional
Wenn die Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann er mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu wird entweder das E-Mail-Feld im Anmeldeformular vorausgefüllt oder die entsprechende Mehrfachanmeldung-Sitzung ausgewählt. Legen Sie als Parameterwert eine E-Mail-Adresse oder eine Legen Sie in Python den Parameter authorization_url, state = flow.authorization_url( access_type='offline', login_hint='None', include_granted_scopes='true') |
||||||
prompt |
Optional
Eine durch Leerzeichen getrennte Liste mit Aufforderungen, bei denen der Nutzer die Groß-/Kleinschreibung beachten muss. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur bei der ersten Anfrage für Ihr Projekt aufgefordert. Weitere Informationen findest du unter Erneute Einwilligung einholen. Legen Sie in Python den Parameter authorization_url, state = flow.authorization_url( access_type='offline', prompt='consent', include_granted_scopes='true') Folgende Werte sind möglich:
|
Ruby
Verwenden Sie die von Ihnen erstellte client_secrets.json-Datei, 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.
Mit diesem Code wird beispielsweise der schreibgeschützte Offlinezugriff auf das Google Drive-Konto eines Nutzers angefordert:
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. URLs für die Autorisierungsanfrage zu generieren und Zugriffstokens auf HTTP-Anfragen anzuwenden.
Node.js
Das folgende Code-Snippet erstellt ein google.auth.OAuth2
-Objekt, das die Parameter in der Autorisierungsanfrage definiert.
Dieses Objekt verwendet Informationen aus Ihrer Datei client_secret.json, um Ihre Anwendung zu identifizieren. Wenn Sie von einem Nutzer die Berechtigung zum Abrufen eines Zugriffstokens anfordern möchten, leiten Sie ihn 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: 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 |
Pflichtfeld
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert im API Console Credentials page. |
||||||
redirect_uri |
Pflichtfeld
Legt fest, wohin der API-Server den Nutzer weiterleitet, nachdem er den Autorisierungsvorgang abgeschlossen hat. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in Ihrem API Console- Credentials pagekonfiguriert haben. Wenn dieser Wert keinem autorisierten Weiterleitungs-URI für die angegebene Beachten Sie, dass das |
||||||
response_type |
Pflichtfeld
Legt fest, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt. Legen Sie den Parameterwert für Webserveranwendungen auf |
||||||
scope |
Pflichtfeld
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Anhand dieser Werte wird der Zustimmungsbildschirm angezeigt, den Google dem Nutzer zeigt. Mit Bereichen kann Ihre Anwendung nur den Zugriff auf die erforderlichen Ressourcen anfordern und Nutzer können außerdem steuern, wie viel Zugriff sie auf Ihre 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 nach Möglichkeit Zugriff auf Autorisierungsbereiche im Kontext anfordert. Wenn Sie den Zugriff auf Nutzerdaten im Kontext mithilfe der inkrementellen Autorisierung anfordern, können Nutzer leichter nachvollziehen, warum Ihre Anwendung den angeforderten Zugriff benötigt. |
||||||
access_type |
Empfohlen
Gibt an, ob Ihre Anwendung Zugriffstokens aktualisieren kann, wenn der Nutzer nicht im Browser vorhanden ist. Gültige Parameterwerte sind Legen Sie den Wert auf |
||||||
state |
Empfohlen
Gibt einen beliebigen Stringwert an, mit dem Ihre Anwendung den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechterhält.
Der Server gibt den genauen Wert zurück, den du als Du kannst diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in deiner Anwendung zu leiten, Benachrichtigungen zu senden und die websiteübergreifende Fälschung von Anfragen zu minimieren. Da Ihr |
||||||
include_granted_scopes |
Optional
Ermöglicht Anwendungen, über die inkrementelle Autorisierung Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf |
||||||
login_hint |
Optional
Wenn die Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann er mit diesem Parameter einen Hinweis für den Google-Authentifizierungsserver bereitstellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen. Dazu wird entweder das E-Mail-Feld im Anmeldeformular vorausgefüllt oder die entsprechende Mehrfachanmeldung-Sitzung ausgewählt. Legen Sie als Parameterwert eine E-Mail-Adresse oder eine |
||||||
prompt |
Optional
Eine durch Leerzeichen getrennte Liste mit Aufforderungen, bei denen der Nutzer die Groß-/Kleinschreibung beachten muss. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur bei der ersten Anfrage für Ihr Projekt aufgefordert. Weitere Informationen findest du unter Erneute Einwilligung einholen. Folgende Werte sind möglich:
|
Schritt 2: Zum OAuth 2.0-Server von Google weiterleiten
Den Nutzer zum OAuth 2.0-Server von Google weiterleiten, um die Authentifizierung und die Autorisierung zu starten Dies ist in der Regel der Fall, wenn Ihre App zum ersten Mal auf die Daten des Nutzers zugreifen muss. Bei der inkrementellen Autorisierung findet dieser Schritt auch dann statt, wenn Ihre Anwendung zuerst auf zusätzliche Ressourcen zugreifen muss, auf die sie noch keine Zugriffsberechtigung hat.
PHP
- Generieren Sie eine URL, um den Zugriff über den OAuth 2.0-Server von Google anzufordern:
$auth_url = $client->createAuthUrl();
- Nutzer zu
$auth_url
weiterleiten:header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
Python
In diesem Beispiel wird gezeigt, wie Sie den Nutzer mithilfe des Flask-Webanwendungs-Frameworks an die Autorisierungs-URL weiterleiten:
return flask.redirect(authorization_url)
Ruby
- Generieren Sie eine URL, um den Zugriff über den OAuth 2.0-Server von Google anzufordern:
auth_uri = auth_client.authorization_uri.to_s
- Nutzer zu
auth_uri
weiterleiten.
Node.js
-
Verwende die generierte URL
authorizationUrl
aus der Methode Schritt 1generateAuthUrl
, um den Zugriff über den OAuth 2.0-Server von Google anzufordern. -
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 ein, damit die Anwendung auf die angeforderten Bereiche zugreifen kann. Die Antwort wird unter Verwendung der von Ihnen angegebenen Weiterleitungs-URL an Ihre Anwendung zurückgesendet.
Schritt 3: Nutzer werden von Google um Einwilligung gebeten
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, für die die Zugriffsberechtigung mit den Autorisierungsanmeldedaten des Nutzers angefordert wird, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche. Der Nutzer kann dann den Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche genehmigen oder die Anfrage ablehnen.
Deine App muss zu diesem Zeitpunkt nichts tun, da sie auf die Antwort des Google-OAuth 2.0-Servers wartet, der angibt, ob Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.
Fehler
Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe möglicherweise Fehlermeldungen für Nutzer angezeigt. Häufige 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 des Google Workspace-Administrators angefordert wurden. Weitere Informationen dazu, wie ein Administrator den Zugriff auf alle Bereiche oder sensible und eingeschränkte Bereiche einschränken kann, bis der Zugriff auf Ihre OAuth-Client-ID ausdrücklich gewährt wird, finden Sie im Google Workspace-Admin-Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten verwalten.
disallowed_useragent
Der Autorisierungsendpunkt wird in einem eingebetteten User-Agent angezeigt, der gemäß den OAuth 2.0-Richtlinien von Google nicht zulässig ist.
Android
Android-Entwickler erhalten diese Fehlermeldung möglicherweise, wenn sie Autorisierungsanfragen in android.webkit.WebView
öffnen.
Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in für Android oder die OpenID Foundation AppAuth for Android verwenden.
Dieser Fehler kann auftreten, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer den OAuth 2.0-Autorisierungsendpunkt von Google von deiner Website aufruft. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems erlauben, das sowohl Android App Links-Handler als auch die Standard-Browser-App enthält. Die Bibliothek Benutzerdefinierte Android-Tabs wird ebenfalls unterstützt.
iOS
iOS- und macOS-Entwickler können diesen Fehler sehen, wenn sie Autorisierungsanfragen in WKWebView
öffnen.
Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für iOS oder AppAuth für iOS von 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 den OAuth 2.0-Autorisierungsendpunkt von Google von deiner Website aufruft. Entwickler sollten das Öffnen allgemeiner Links im Standard-Link-Handler des Betriebssystems erlauben, das sowohl Universal Links-Handler als auch die Standard-Browser-App enthält. 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.
redirect_uri_mismatch
Die in der Autorisierungsanfrage übergebene redirect_uri
stimmt nicht mit einem autorisierten Weiterleitungs-URI für die OAuth-Client-ID überein. Prüfen Sie die autorisierten Weiterleitungs-URIs im Google API Console Credentials page.
Schritt 4: Antwort des OAuth 2.0-Servers 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, enthält die Antwort einen Autorisierungscode. Wenn der Nutzer die Anfrage nicht genehmigt, enthält die Antwort eine Fehlermeldung. Der Autorisierungscode oder die Fehlermeldung, die an den Webserver zurückgegeben wird, wird wie unten dargestellt im Abfragestring angezeigt:
Eine Fehlermeldung:
https://oauth2.example.com/auth?error=access_denied
Antwort mit Autorisierungscode:
https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
Beispiel einer OAuth 2.0-Serverantwort
Sie können diesen Ablauf testen, indem Sie auf die folgende Beispiel-URL klicken. Dadurch wird Lesezugriff auf Metadaten für Dateien in Google Drive angefordert:
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 du den OAuth 2.0-Vorgang abgeschlossen hast, solltest du zu http://localhost/oauth2callback
weitergeleitet. Wenn der lokale Computer keine Datei an diese Adresse sendet, wird wahrscheinlich der Fehler 404 NOT FOUND
ausgegeben. Der nächste Schritt enthält weitere Informationen zu den im URI zurückgegebenen Informationen, wenn der Nutzer zurück zu Ihrer Anwendung weitergeleitet 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
Verwende auf deiner Callback-Seite die Bibliothek google-auth
, um die Antwort des Autorisierungsservers zu überprü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 aus der API Console Credentials page. |
client_secret |
Der Clientschlüssel, der aus der API ConsoleCredentials pageabgerufen wird. |
code |
Der von der ursprünglichen Anfrage zurückgegebene Autorisierungscode. |
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 ConsoleCredentials 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 zurückgibt, das ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken enthält.
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 erhalten 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 gesetzt haben.
|
scope |
Die von access_token gewährten Zugriffsbereiche als Liste von durch Leerzeichen voneinander getrennten Strings, bei denen die Groß- und Kleinschreibung berücksichtigt wird. |
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" }
Google APIs aufrufen
PHP
Führen Sie die folgenden Schritte aus, um Google APIs mit dem Zugriffstoken aufzurufen:
- 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 MethodesetAccessToken
:$client->setAccessToken($access_token);
- 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);
- Senden Sie Anfragen an den API-Dienst über die Schnittstelle, die vom Dienstobjekt zur Verfügung gestellt wird.
So listen Sie beispielsweise die Dateien im authentifizierten Google Drive-Nutzer auf:
$files = $drive->files->listFiles(array())->getItems();
Python
Nachdem Sie ein Zugriffstoken abgerufen haben, kann Ihre Anwendung dieses Token verwenden, um API-Anfragen im Namen eines bestimmten Nutzerkontos oder Dienstkontos zu autorisieren. Mit den nutzerspezifischen Autorisierungsanmeldedaten können Sie ein Dienstobjekt für die API erstellen, die Sie aufrufen möchten. Dieses Objekt können Sie dann für autorisierte API-Anfragen verwenden.
- Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Zum Erstellen eines Dienstobjekts rufen Sie die Methode
build
dergoogleapiclient.discovery
-Bibliothek mit dem Namen und der Version der API und den Anmeldedaten des Nutzers auf. So rufen Sie beispielsweise Version 2 der Drive API auf:from googleapiclient.discovery import build drive = build('drive', 'v2', credentials=credentials)
- Senden Sie Anfragen an den API-Dienst über die Schnittstelle, die vom Dienstobjekt zur Verfügung gestellt wird.
So listen Sie beispielsweise die Dateien im authentifizierten Google Drive-Nutzer 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:
- 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
- Legen Sie die Anmeldedaten für den Dienst fest:
drive.authorization = auth_client
- Senden Sie Anfragen an den API-Dienst über die Schnittstelle, die vom Dienstobjekt zur Verfügung gestellt wird.
So listen Sie beispielsweise die Dateien im authentifizierten Google Drive-Nutzer auf:
files = drive.list_files
Die Autorisierung kann auch pro Methode bereitgestellt werden. Dazu wird einer Methode der Parameter options
übergeben:
files = drive.list_files(options: { authorization: auth_client })
Node.js
Nachdem Sie ein Zugriffstoken abgerufen und auf das Objekt OAuth2
festgelegt haben, rufen Sie Google APIs mit dem Objekt auf. Ihre Anwendung kann dieses Token verwenden, um API-Anfragen im Namen eines bestimmten Nutzerkontos oder Dienstkontos 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 damit im Namen eines bestimmten Nutzerkontos Aufrufe an eine Google API senden, sofern der oder die Bereiche, die für die API erforderlich sind, gewährt wurden. Füge dazu das Zugriffstoken in eine Anfrage an die API ein. Füge dazu den access_token
-Abfrageparameter oder den Authorization
-HTTP-Headerwert Bearer
hinzu. Wenn möglich, ist der HTTP-Header zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du eine Clientbibliothek verwenden, um deine Aufrufe an Google APIs einzurichten (z. B. beim Aufruf der Drive Files API).
Sie können alle Google APIs ausprobieren und sich ihre Bereiche im OAuth 2.0 Playground ansehen.
Beispiele für HTTP GET
Ein Aufruf des Endpunkts drive.files
(Drive Drive API) über den HTTP-Header Authorization: Bearer
könnte so aussehen. Sie müssen ein eigenes Zugriffstoken angeben:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Hier ist ein Aufruf an die gleiche 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
Alternativ können Sie die folgende Parameteroption für den Abfragestring verwenden:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Vollständiges Beispiel
Im folgenden Beispiel wird eine JSON-formatierte Liste von Dateien im Google Drive-Konto eines Nutzers ausgegeben, nachdem sich der Nutzer authentifiziert hat. Außerdem wird der Anwendung Zugriff auf die Drive-Metadaten des Nutzers erteilt.
PHP
So führen Sie das Beispiel aus:
- Füge in der Liste API Consoleder Weiterleitungs-URLs die URL des lokalen Computers hinzu. Füge beispielsweise
http://localhost:8080
hinzu. - Erstellen Sie ein neues Verzeichnis und ändern Sie es. Beispiel:
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- Installieren Sie die Google API-Clientbibliothek für PHP mit Composer:
composer require google/apiclient:^2.10
- Erstelle die Dateien
index.php
undoauth2callback.php
mit dem Inhalt unten. - 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, sollten vier Links angezeigt werden:
- 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 war, wird auf der Seite die API-Antwort angezeigt.
- Authentifizierungsvorgang direkt testen:Dieser Link verweist auf eine Seite, auf der der Nutzer über den Autorisierungsvorgang weitergeleitet werden soll. Die App fordert die Berechtigung zum Senden autorisierter API-Anfragen im Namen des Nutzers an.
- Aktuelle Anmeldedaten aufheben: Dieser Link verweist auf eine Seite, die die Berechtigungen, die der Nutzer der Anwendung bereits gewährt hat, entzieht.
- Flask-Anmeldedaten löschen: Mit diesem Link werden die in der Flask-Sitzung gespeicherten Autorisierungsanmeldedaten gelöscht. So siehst du, was passiert, wenn ein Nutzer, der deiner App bereits die Berechtigung erteilt hat, in einer neuen Sitzung eine API-Anfrage ausführt. Außerdem siehst du hier die API-Antwort, die deine App erhält, wenn ein Nutzer Berechtigungen für deine App widerrufen hätte und deine App noch immer versucht hat, eine Anfrage mit einem widerrufenen Zugriffstoken zu autorisieren.
# -*- 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:
-
Füge in der Liste API Consoledie URL des lokalen Computers der Liste der Weiterleitungs-URLs hinzu. Füge beispielsweise
http://localhost
hinzu. - Achten Sie darauf, dass ein Wartungs-Langzeitsupport, ein aktiver LTS-Dienst oder der aktuelle Release von Node.js installiert ist.
-
Erstellen Sie ein neues Verzeichnis und ändern Sie es. Beispiel:
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
Install the
Google API Client
Library
for Node.js using npm:
npm install googleapis
-
Erstelle die Dateien
main.js
mit folgendem Inhalt. -
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 Anfragen-Bibliothek verwendet, um den OAuth 2.0-Webfluss zu veranschaulichen. Für diesen Vorgang 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 dabei zu unterstützen, ihre Anwendungen zu schützen. Ihre Weiterleitungs-URIs müssen diese Regeln einhalten. Definitionen zu Domain, Host, Pfad, Abfrage, Schema und Nutzerinformationen finden Sie in RFC 3986, Abschnitt 3.
Validierungsregeln | |
---|---|
Schema |
Für Weiterleitungs-URIs muss das HTTPS-Schema verwendet werden, nicht nur HTTP. Localhost-URIs (einschließlich URIs für lokale IP-Adressen) sind von dieser Regel ausgenommen. |
Moderator:in |
Hosts dürfen keine unformatierten IP-Adressen sein. Localhost-IP-Adressen sind von dieser Regel ausgenommen. |
Domain |
“googleusercontent.com” sein.goo.gl enthalten, es sei denn, die Domain gehört der Anwendung. Wenn eine Anwendung, die eine Kurzdomain besitzt, eine Weiterleitung zu dieser Domain auswählt, muss dieser Weiterleitungs-URI 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 ein |
Suchanfrage |
Weiterleitungs-URIs dürfen keine offenen Weiterleitungen enthalten. |
Fragment |
Weiterleitungs-URIs dürfen keine Fragmentkomponente enthalten. |
Zeichen |
Weiterleitungs-URIs dürfen folgende Zeichen nicht enthalten:
|
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 empfiehlt sich, die Autorisierung für Ressourcen im richtigen Moment anzufordern. Zur Autorisierung 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 möglicherweise gegen ein Token ausgetauscht wird, das alle Bereiche enthält, die der Nutzer dem Projekt gewährt hat.
Beispielsweise benötigt eine App, mit der Nutzer Musiktitel probehören und Mixe erstellen können, bei der Anmeldung möglicherweise nur sehr wenige Ressourcen. Vielleicht reicht es nicht mehr, als der Name der Person, die sich anmeldet. Das Speichern eines abgeschlossenen Mixes würde jedoch Zugriff auf das eigene Google Drive erfordern. Die meisten Nutzer dürften es für natürlich halten, wenn sie nur dann Zugriff auf ihr Google Drive-Konto anfordern würden, wenn die App sie tatsächlich benötigt.
In diesem Fall fordert die Anwendung zum Zeitpunkt der Anmeldung eventuell die Bereiche openid
und profile
an, um eine grundlegende Anmeldung auszuführen. Später wird dann der Bereich https://www.googleapis.com/auth/drive.file
zum Zeitpunkt der ersten Anfrage angefordert, um einen Mix zu speichern.
Zum Implementieren der inkrementellen Autorisierung führen Sie den normalen Vorgang zum Anfordern eines Zugriffstokens aus. Die Autorisierungsanfrage muss jedoch zuvor gewährte Bereiche enthalten. Bei diesem Ansatz muss Ihre Anwendung nicht mehrere Zugriffstokens verwalten.
Die folgenden Regeln gelten für ein Zugriffstoken, das durch eine inkrementelle Autorisierung abgerufen wird:
- Das Token kann verwendet werden, um auf Ressourcen zuzugreifen, 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 abzurufen, 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 einen Desktop-Client einer Anwendung Zugriff auf einen Bereich gewährt und dieser Anwendung dann über einen mobilen Client einen anderen Bereich gewährt hat, würde die kombinierte Autorisierung beide Bereiche umfassen.
- 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 jeweils 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 Schlüsselwortargument 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)
Zugriffstokens laufen in regelmäßigen Abständen ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um seine Berechtigung zu bitten (auch wenn der Nutzer nicht anwesend ist), wenn Sie den Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.
- Wenn Sie eine Google API-Clientbibliothek verwenden, aktualisiert das Clientobjekt das Zugriffstoken nach Bedarf, solange Sie dieses Objekt für den Offlinezugriff konfigurieren.
- Wenn du keine Clientbibliothek verwendest, musst du den HTTP-Abfrageparameter
access_type
aufoffline
festlegen, wenn du den Nutzer zum Google OAuth 2.0-Server weiterleitet. 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 abzurufen.
Das Anfordern des Offlinezugriffs ist für jede Anwendung erforderlich, die ohne Google-Nutzer auf eine Google API zugreifen muss. Beispielsweise muss eine Anwendung, die zu bestimmten Zeiten Sicherungsdienste oder Aktionen ausführt, in der Lage sein, ihr Zugriffstoken zu aktualisieren, wenn der Nutzer nicht anwesend ist. Der Standardstil des Zugriffs lautet online
.
Serverseitige Webanwendungen, installierte Anwendungen und Geräte erhalten während des Autorisierungsprozesses Aktualisierungstokens. Aktualisierungstokens werden in clientseitigen JavaScript-Webanwendungen normalerweise nicht verwendet.
PHP
Wenn die Anwendung Offlinezugriff auf eine Google API benötigt, setze den Zugriffstyp des API-Clients auf offline
:
$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 Schlüsselwortargument access_type
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, setze den Zugriffstyp des API-Clients auf offline
:
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, setze den Zugriffstyp des API-Clients auf offline
:
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.
Zugriffstokens laufen ab. Diese Bibliothek verwendet automatisch ein Aktualisierungstoken, um ein neues Zugriffstoken abzurufen, wenn dieses bald abläuft. Mit dem Tokenereignis 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. Sie müssen access_type
beim Aufrufen der Methode generateAuthUrl
auf offline
setzen, um das Aktualisierungstoken zu erhalten. Wenn Sie Ihrer Anwendung bereits die erforderlichen Berechtigungen erteilt haben, ohne die entsprechenden Einschränkungen zum Empfangen eines Aktualisierungstokens festzulegen, müssen Sie die Anwendung noch einmal autorisieren, um ein neues Aktualisierungstoken zu erhalten.
Wenn Sie die 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 beim nächsten Aufruf der 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 von API Consoleabgerufene Clientschlüssel. |
grant_type |
Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Feldes auf refresh_token festgelegt werden. |
refresh_token |
Das vom Autorisierungscodeaustausch 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 den Zugriff nicht widerrufen 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 Kombination aus Client und Nutzer und ein weiteres Limit pro Nutzer und Client. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und weiterhin verwenden, solange sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits überschritten werden. In diesem Fall funktionieren ältere Aktualisierungstoken nicht mehr.
Token widerrufen
In manchen Fällen möchte ein Nutzer den Zugriff einer Anwendung widerrufen. Ein Nutzer kann den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument unter Website oder App-Zugriff auf Websites von Drittanbietern mit Zugriff auf dein Konto entfernen.
Es ist auch möglich, dass eine Anwendung den Zugriff auf sie programmatisch widerrufen kann. Der programmatische Widerruf ist wichtig, wenn 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 sichergestellt wird, dass die zuvor 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, stellen Sie eine Anfrage an https://oauth2.googleapis.com/revoke
, die das Token als Parameter enthält und den Content-Type
-Header 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, stellen 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 das Aktualisierungstoken auch widerrufen.
Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der Statuscode der Antwort 200
. Für 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 das Aktualisierungstoken auch widerrufen.
Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der Statuscode der Antwort 200
. Für 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
, die das Token als Parameter enthält:
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 das Aktualisierungstoken auch widerrufen.
Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200
. Für Fehlerbedingungen wird der HTTP-Statuscode 400
zusammen mit einem Fehlercode zurückgegeben.