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.
OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung mithilfe von OAuth 2.0 die Berechtigung von Nutzern zum Speichern von Dateien in Google Drive einholen.
Dieser OAuth 2.0-Vorgang bezieht sich speziell auf die Nutzerautorisierung. Es wurde für Anwendungen entwickelt, die vertrauliche Informationen speichern und den Status aufrechterhalten können. Eine ordnungsgemäß autorisierte Webserveranwendung kann auf eine API zugreifen, während der Nutzer mit der Anwendung interagiert oder die Anwendung verlassen hat.
Webserveranwendungen verwenden häufig auch Dienstkonten zum Autorisieren von API-Anfragen, insbesondere wenn Cloud APIs für den Zugriff auf projektbasierte und nicht auf nutzerspezifische Daten aufgerufen werden. Webserveranwendungen können Dienstkonten in Verbindung mit der Nutzerautorisierung verwenden.
Clientbibliotheken
In den sprachspezifischen Beispielen auf dieser Seite werden 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 verarbeiten müsste. Beispielsweise wird festgelegt, wann die Anwendung gespeicherte Zugriffstokens verwenden oder aktualisieren kann und wann die Anwendung die 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 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 API Consoleaktivieren.
So aktivieren Sie eine API für Ihr Projekt:
- Open the API Library in Google API Console.
- If prompted, select a project, or create a new one.
- In API Library sind alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert aufgeführt. Wenn die gewünschte API nicht in der Liste aufgeführt ist, suchen Sie sie oder klicken Sie in der zugehörigen Produktfamilie auf Alle ansehen.
- 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
Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss über Autorisierungsanmeldedaten verfügen, die die Anwendung beim OAuth 2.0-Server von Google identifizieren. 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.
- 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.
Zu Testzwecken können Sie URIs angeben, die sich auf den lokalen Computer beziehen, z. B.
http://localhost:8080
. Beachten Sie deshalb, dass in allen Beispielen in diesem Dokumenthttp://localhost:8080
als Weiterleitungs-URI verwendet wird.Wir empfehlen, die Authentifizierungsendpunkte Ihrer Anwendung so zu entwerfen, dass Ihre Anwendung keine Autorisierungscodes für andere Ressourcen auf der Seite freigibt.
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
Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann es eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit des Einholens der Nutzereinwilligung geben.
Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, für die Ihre App eine Zugriffsberechtigung benötigt.
Wir empfehlen außerdem, dass Ihre Anwendung den Zugriff auf Autorisierungsbereiche über einen inkrementellen Autorisierungsprozess anfordert, bei dem Ihre Anwendung den Zugriff auf Nutzerdaten im Kontext anfordert. Mit dieser Best Practice können Nutzer besser nachvollziehen, warum Ihre Anwendung den angeforderten 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
Wenn Sie die Codebeispiele in diesem Dokument ausführen möchten, benötigen Sie ein Google-Konto, eine Internetverbindung und einen Webbrowser. Wenn Sie eine der API-Clientbibliotheken verwenden, beachten Sie auch die sprachspezifischen Anforderungen unten.
PHP
Sie benötigen Folgendes, um die PHP-Codebeispiele in diesem Dokument auszuführen:
- PHP 5.6 oder höher mit installierter Befehlszeile und JSON-Erweiterung
- Composer-Tool zur Abhängigkeitsverwaltung
-
Die Google APIs-Clientbibliothek für PHP:
composer require google/apiclient:^2.10
Python
Sie benötigen Folgendes, um die Python-Codebeispiele in diesem Dokument auszuführen:
- 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-Framework für Python-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.6 oder höher
-
Google-Authentifizierungsbibliothek für Ruby:
gem install googleauth
-
Das Sinatra Ruby-Framework für Webanwendungen
gem install sinatra
Node.js
Sie benötigen Folgendes, um die Node.js-Codebeispiele in diesem Dokument auszuführen:
- Der Wartungs-LTS, der aktive LTS oder der aktuelle Release von Node.js.
-
Der Node.js-Client für 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 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.
Die folgende Liste fasst diese Schritte kurz zusammen:
- Ihre Anwendung identifiziert die benötigten Berechtigungen.
- Ihre Anwendung leitet den Nutzer zusammen mit der Liste der angeforderten Berechtigungen zu Google weiter.
- Der Nutzer entscheidet, ob er Ihrer Anwendung die Berechtigungen erteilt.
- Ihre Anwendung ermittelt, was der Nutzer entschieden hat.
- Wenn der Nutzer die angeforderten Berechtigungen erteilt hat, ruft Ihre 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 Ihrer Anwendung gewähren soll.
- Wenn Sie eine Google-Clientbibliothek für die Authentifizierung und Autorisierung mit OAuth 2.0 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.
Auf den folgenden Registerkarten werden die unterstützten Autorisierungsparameter für Webserveranwendungen definiert. Die sprachspezifischen Beispiele zeigen auch, wie mit einer Clientbibliothek oder Autorisierungsbibliothek ein Objekt konfiguriert wird, das diese Parameter festlegt.
PHP
Mit dem folgenden Code-Snippet wird ein Google\Client()
-Objekt erstellt, das die Parameter in der Autorisierungsanfrage definiert.
Dieses Objekt verwendet Informationen aus der Datei client_secret.json, um Ihre Anwendung zu identifizieren. Weitere Informationen zu dieser Datei finden Sie unter Anmeldedaten für die Autorisierung erstellen. Das Objekt identifiziert auch die Bereiche, für die Ihre Anwendung Zugriffsberechtigungen anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, der die Antwort des OAuth 2.0-Servers von Google verarbeitet. Schließlich legt der Code die optionalen Parameter access_type
und include_granted_scopes
fest.
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" will prompt the user for consent $client->setPrompt('consent'); $client->setIncludeGrantedScopes(true); // incremental auth
In der Anfrage werden die folgenden Informationen angegeben:
Parameter | |||||||
---|---|---|---|---|---|---|---|
client_id |
Erforderlich
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API Console Credentials page. Rufen Sie in PHP die Funktion $client = new Google\Client(); $client->setAuthConfig('client_secret.json'); |
||||||
redirect_uri |
Erforderlich
Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Nutzer den Autorisierungsvorgang abgeschlossen hat. 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 mit keinem autorisierten Weiterleitungs-URI für die angegebene Das Schema Rufen Sie die Funktion $client->setRedirectUri('https://oauth2.example.com/code'); |
||||||
scope |
Erforderlich
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs auf Ihre Anwendung steuern. 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 den Zugriff auf Autorisierungsbereiche nach Möglichkeit im Kontext anfordert. Wenn Sie über eine inkrementelle Autorisierung Zugriff auf Nutzerdaten im Kontext 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 anwesend ist. Gültige Parameterwerte sind Legen Sie den Wert auf Rufen Sie die Funktion $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 beizubehalten.
Der Server gibt genau den Wert zurück, den Sie als Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung weiterzuleiten, Nonces zu senden und die websiteübergreifende Anfragefälschung zu mindern. Da Ihr Rufen Sie die Funktion $client->setState($sample_passthrough_value); |
||||||
include_granted_scopes |
Optional
Ermöglicht Anwendungen, mithilfe der inkrementellen Autorisierung Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf Rufen Sie die Funktion $client->setIncludeGrantedScopes(true); |
||||||
enable_granular_consent |
Optional
Die Standardeinstellung ist |
||||||
login_hint |
Optional
Wenn Ihre Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann dieser Parameter verwendet werden, um dem Google-Authentifizierungsserver einen Hinweis bereitzustellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Mehrfachanmeldungssitzung auswählt. Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine Rufen Sie die Funktion $client->setLoginHint('None'); |
||||||
prompt |
Optional
Eine Liste von Aufforderungen, die dem Nutzer präsentiert werden sollen. Dabei wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur bei der ersten Zugriffsanfrage durch Ihr Projekt dazu aufgefordert. Weitere Informationen finden Sie unter Erneute Einwilligung einholen. Rufen Sie die Funktion $client->setPrompt('consent'); Folgende Werte sind möglich:
|
Python
Im folgenden Code-Snippet wird das Modul google-auth-oauthlib.flow
zum Erstellen der Autorisierungsanfrage verwendet.
Der Code erstellt ein Flow
-Objekt, das Ihre Anwendung anhand von Informationen aus der Datei client_secret.json identifiziert, die Sie nach dem Erstellen der Anmeldedaten für die Autorisierung heruntergeladen haben. Dieses Objekt identifiziert auch die Bereiche, für die Ihre Anwendung Zugriffsberechtigungen anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, der die Antwort des OAuth 2.0-Servers von Google verarbeitet. Schließlich legt der Code die optionalen Parameter access_type
und include_granted_scopes
fest.
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')
In der Anfrage werden die folgenden Informationen angegeben:
Parameter | |||||||
---|---|---|---|---|---|---|---|
client_id |
Erforderlich
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der 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 |
Erforderlich
Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Nutzer den Autorisierungsvorgang abgeschlossen hat. 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 mit keinem autorisierten Weiterleitungs-URI für die angegebene Das Schema Wenn Sie diesen Wert in Python festlegen möchten, legen Sie das Attribut flow.redirect_uri = 'https://oauth2.example.com/code' |
||||||
scope |
Erforderlich
Eine Liste von Bereichen zur Identifizierung der Ressourcen, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs auf Ihre Anwendung steuern. 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 den Zugriff auf Autorisierungsbereiche nach Möglichkeit im Kontext anfordert. Wenn Sie über eine inkrementelle Autorisierung Zugriff auf Nutzerdaten im Kontext 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 anwesend 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, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers beizubehalten.
Der Server gibt genau den Wert zurück, den Sie als Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung weiterzuleiten, Nonces zu senden und die websiteübergreifende Anfragefälschung zu mindern. 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, mithilfe der inkrementellen 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') |
||||||
enable_granular_consent |
Optional
Die Standardeinstellung ist |
||||||
login_hint |
Optional
Wenn Ihre Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann dieser Parameter verwendet werden, um dem Google-Authentifizierungsserver einen Hinweis bereitzustellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Mehrfachanmeldungssitzung auswählt. Legen Sie den Parameterwert auf 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 Liste von Aufforderungen, die dem Nutzer präsentiert werden sollen. Dabei wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur bei der ersten Zugriffsanfrage durch Ihr Projekt dazu aufgefordert. Weitere Informationen finden Sie 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 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, der die Antwort des OAuth 2.0-Servers verarbeitet.
Dieser Code fordert beispielsweise schreibgeschützten Offlinezugriff auf Google Drive eines Nutzers an:
require 'google/apis/drive_v3' require "googleauth" require 'googleauth/stores/redis_token_store' client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json') scope = 'https://www.googleapis.com/auth/drive.metadata.readonly' token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope, token_store, '/oauth2callback')Your application uses the client object to perform OAuth 2.0 operations, such as generating authorization request URLs and applying access tokens to HTTP requests.
Node.js
The code snippet below creates a google.auth.OAuth2
object, which defines the
parameters in the authorization request.
That object uses information from your client_secret.json file to identify your application. To ask for permissions from a user to retrieve an access token, you redirect them to a consent page. To create a consent page URL:
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 |
Erforderlich
Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API Console Credentials page. |
||||||
redirect_uri |
Erforderlich
Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Nutzer den Autorisierungsvorgang abgeschlossen hat. 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 mit keinem autorisierten Weiterleitungs-URI für die angegebene Das Schema |
||||||
response_type |
Erforderlich
Bestimmt, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt. Legen Sie den Parameterwert für Webserveranwendungen auf |
||||||
scope |
Erforderlich
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs auf Ihre Anwendung steuern. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. Wir empfehlen, dass Ihre Anwendung den Zugriff auf Autorisierungsbereiche nach Möglichkeit im Kontext anfordert. Wenn Sie über eine inkrementelle Autorisierung Zugriff auf Nutzerdaten im Kontext 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 anwesend ist. Gültige Parameterwerte sind Legen Sie den Wert auf |
||||||
state |
Empfohlen
Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers beizubehalten.
Der Server gibt genau den Wert zurück, den Sie als Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung weiterzuleiten, Nonces zu senden und die websiteübergreifende Anfragefälschung zu mindern. Da Ihr |
||||||
include_granted_scopes |
Optional
Ermöglicht Anwendungen, mithilfe der inkrementellen Autorisierung Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf |
||||||
enable_granular_consent |
Optional
Die Standardeinstellung ist |
||||||
login_hint |
Optional
Wenn Ihre Anwendung weiß, welcher Nutzer zu authentifizieren versucht, kann dieser Parameter verwendet werden, um dem Google-Authentifizierungsserver einen Hinweis bereitzustellen. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Mehrfachanmeldungssitzung auswählt. Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine |
||||||
prompt |
Optional
Eine Liste von Aufforderungen, die dem Nutzer präsentiert werden sollen. Dabei wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur bei der ersten Zugriffsanfrage durch Ihr Projekt dazu aufgefordert. Weitere Informationen finden Sie unter Erneute Einwilligung einholen. Folgende Werte sind möglich:
|
Schritt 2: Zum OAuth 2.0-Server von Google weiterleiten
Leite den Nutzer zum OAuth 2.0-Server von Google weiter, um den Authentifizierungs- und Autorisierungsprozess zu initiieren. In der Regel geschieht dies, wenn Ihre Anwendung zuerst auf die Daten des Nutzers zugreifen muss. Im Fall einer inkrementellen Autorisierung erfolgt dieser Schritt auch, wenn Ihre Anwendung zuerst auf zusätzliche Ressourcen zugreifen muss, für die sie noch keine Zugriffsberechtigung hat.
PHP
- Generiere eine URL, um Zugriff vom 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 der Nutzer mithilfe des Flask-Frameworks für Webanwendungen zur Autorisierungs-URL weitergeleitet wird:
return flask.redirect(authorization_url)
Ruby
- Generiere eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:
auth_uri = authorizer.get_authorization_url(login_hint: user_id, request: request)
- Leite den Nutzer zu
auth_uri
weiter.
Node.js
-
Verwenden Sie die Methode
authorizationUrl
, die in Schritt 1 aus Schritt 1generateAuthUrl
generiert wurde, um den Zugriff vom OAuth 2.0-Server von Google anzufordern. -
Leite den Nutzer zu
authorizationUrl
weiter.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 erhält die Einwilligung des Nutzers für den Zugriff Ihrer Anwendung auf die angeforderten Bereiche. Die Antwort wird unter Verwendung der von Ihnen angegebenen Weiterleitungs-URL an Ihre 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ährt. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, für die die Berechtigung für den Zugriff mit den Autorisierungsanmeldedaten des Nutzers angefordert wird. Außerdem wird eine Zusammenfassung der Zugriffsbereiche angezeigt, die gewährt werden sollen. Der Nutzer kann dann zustimmen, Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.
Ihre Anwendung muss in dieser Phase nichts weiter tun, da sie auf die Antwort des OAuth 2.0-Servers von Google wartet, die angibt, ob der Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.
Fehler
Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden möglicherweise Fehlermeldungen für Nutzer anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe angezeigt. Häufige Fehlercodes und Lösungsvorschläge sind unten aufgeführt.
admin_policy_enforced
Das Google-Konto kann einen oder mehrere angeforderte Bereiche aufgrund der Richtlinien des jeweiligen Google Workspace-Administrators nicht autorisieren. Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten steuern finden Sie weitere Informationen dazu, wie ein Administrator den Zugriff auf alle oder vertrauliche und eingeschränkte Bereiche einschränken kann, bis der OAuth-Client-ID 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
Android-Entwickler können diese Fehlermeldung sehen, wenn sie Autorisierungsanfragen in android.webkit.WebView
öffnen.
Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in for Android oder AppAuth for Android der OpenID Foundation verwenden.
Dieser Fehler kann bei Webentwicklern auftreten, 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 navigiert. Entwickler sollten zulassen, dass allgemeine Links im standardmäßigen Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Android-App-Links-Handler oder die Standard-Browser-App. Die Bibliothek Benutzerdefinierte Tabs ist ebenfalls eine unterstützte Option.
iOS
Dieser Fehler kann beim Öffnen von Autorisierungsanfragen in WKWebView
für iOS- und macOS-Entwickler auftreten.
Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in for iOS oder AppAuth for iOS der OpenID Foundation verwenden.
Bei Webentwicklern kann dieser Fehler auftreten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von Ihrer Website zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten zulassen, dass allgemeine Links im standardmäßigen Link-Handler des Betriebssystems geöffnet werden, der sowohl Universal-Links-Handler oder die Standard-Browser-App umfasst. Die Bibliothek SFSafariViewController
ist ebenfalls eine unterstützte Option.
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 einschränkt. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel „OAuth-Zustimmungsbildschirm einrichten“ im Abschnitt Nutzertyp.
invalid_client
Der OAuth-Clientschlüssel ist falsch. Prüfen Sie die OAuth-Clientkonfiguration, einschließlich der Client-ID und des Secrets, die für diese Anfrage verwendet werden.
invalid_grant
Beim Aktualisieren eines Zugriffstokens oder beim Verwenden einer inkrementellen Autorisierung ist das Token möglicherweise abgelaufen oder ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um seine Zustimmung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin angezeigt wird, prüfen Sie, ob Ihre Anwendung richtig konfiguriert wurde und Sie in Ihrer Anfrage die richtigen Tokens und Parameter 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 die autorisierten Weiterleitungs-URIs in der 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 Aktualisieren deiner Integration findest du in der Migrationsanleitung.
invalid_request
Es gab ein Problem mit Ihrer Anfrage. Dafür kann es mehrere Gründe geben:
- Die Anfrage war nicht richtig formatiert
- In der Anfrage fehlten erforderliche Parameter
- In der Anfrage wird eine Autorisierungsmethode verwendet, die von Google nicht unterstützt wird. Prüfen, ob die OAuth-Einbindung eine empfohlene Integrationsmethode verwendet
Schritt 4: OAuth 2.0-Serverantwort verarbeiten
Der OAuth 2.0-Server antwortet auf die Zugriffsanfrage deiner Anwendung mit 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 im Abfragestring wie unten dargestellt angezeigt:
Eine Fehlerantwort:
https://oauth2.example.com/auth?error=access_denied
Eine Autorisierungscodeantwort:
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. Dadurch wird Lesezugriff zum Ansehen von 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
Nach Abschluss des OAuth 2.0-Vorgangs sollten Sie zu http://localhost/oauth2callback
weitergeleitet werden. Es wird wahrscheinlich der Fehler 404 NOT FOUND
zurückgegeben, es sei denn, Ihr lokaler Computer stellt eine Datei unter dieser Adresse bereit. Der nächste Schritt enthält weitere Details zu den im URI zurückgegebenen Informationen, wenn der Nutzer zu Ihrer Anwendung zurückgeleitet wird.
Schritt 5: Autorisierungscode gegen 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 auf der Callback-Seite die Bibliothek googleauth
, um die Antwort des Autorisierungsservers zu prüfen. Verwenden Sie die Methode authorizer.handle_auth_callback_deferred
, um den Autorisierungscode zu speichern und zu der URL zurückzukehren, die die Autorisierung ursprünglich angefordert hat. Dadurch wird der Codeaustausch verzögert, indem die Ergebnisse vorübergehend in der Nutzersitzung gespeichert werden.
target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url
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
Wenn Sie einen Autorisierungscode gegen ein Zugriffstoken austauschen möchten, rufen Sie den Endpunkt https://oauth2.googleapis.com/token
auf und legen Sie die folgenden Parameter fest:
Felder | |
---|---|
client_id |
Die aus dem API Console Credentials pageabgerufene Client-ID. |
client_secret |
Der aus dem API Console Credentials pageabgerufene Clientschlüssel. |
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 Felds auf authorization_code festgelegt werden. |
redirect_uri |
Einer der Weiterleitungs-URIs, die für Ihr Projekt in API Console
Credentials page für den angegebenen 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 mit der Rückgabe eines JSON-Objekts, 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 abrufen können. Aktualisierungstokens sind gültig, bis der Nutzer den Zugriff widerruft.
Auch dieses Feld ist nur in dieser Antwort vorhanden, wenn Sie den Parameter access_type in der ersten Anfrage an den Autorisierungsserver von Google auf offline gesetzt haben.
|
scope |
Die durch access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten Strings unter Beachtung der Groß- und Kleinschreibung. |
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 durch ein Zugriffstoken kann anstelle der erwarteten Antwort der folgende Fehler auftreten. Häufige 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. Starten Sie dazu den OAuth-Prozess neu, um den Nutzer noch einmal zur Einwilligung aufzufordern.
Google APIs aufrufen
PHP
Verwenden Sie das Zugriffstoken, um Google APIs aufzurufen. Führen Sie dazu die folgenden Schritte aus:
- 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 stellen Sie dem Konstruktor der gewünschten API ein autorisiertes
Google\Client
-Objekt bereit. 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 bereitgestellt wird.
So listen Sie beispielsweise die Dateien im Google Drive 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 Anmeldedaten für die Autorisierung, um ein Dienstobjekt für die aufzurufende API zu erstellen. Verwenden Sie dieses Objekt dann für autorisierte API-Anfragen.
- 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 sowie den Nutzeranmeldedaten auf: So rufen Sie beispielsweise Version 3 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 bereitgestellt wird.
So listen Sie beispielsweise die Dateien im Google Drive des authentifizierten Nutzers auf:
files = drive.files().list().execute()
Ruby
Nachdem Sie ein Zugriffstoken erhalten haben, kann Ihre Anwendung dieses Token verwenden, um im Namen eines bestimmten Nutzerkontos oder Dienstkontos API-Anfragen zu stellen. Verwenden Sie die nutzerspezifischen Anmeldedaten für die Autorisierung, um ein Dienstobjekt für die aufzurufende API zu erstellen. Verwenden Sie dieses Objekt dann für autorisierte API-Anfragen.
- Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten.
So rufen Sie beispielsweise Version 3 der Drive API auf:
drive = Google::Apis::DriveV3::DriveService.new
- Legen Sie die Anmeldedaten für den Dienst fest:
drive.authorization = credentials
- Senden Sie Anfragen an den API-Dienst über die Schnittstelle, die vom Dienstobjekt bereitgestellt wird.
So listen Sie beispielsweise die Dateien im Google Drive-Konto des authentifizierten Nutzers auf:
files = drive.list_files
Alternativ kann die Autorisierung für jede einzelne Methode erfolgen. Dazu wird einer Methode der Parameter options
bereitgestellt:
files = drive.list_files(options: { authorization: credentials })
Node.js
Nachdem du ein Zugriffstoken abgerufen und auf das Objekt OAuth2
festgelegt hast, kannst du damit Google APIs aufrufen. 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 abgerufen hat, können Sie mit dem Token im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein. Dazu fügen Sie entweder einen access_token
-Abfrageparameter oder den Bearer
-Wert eines Authorization
-HTTP-Headers ein. Der HTTP-Header ist nach Möglichkeit zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie Aufrufe an Google APIs mithilfe einer Clientbibliothek einrichten, z. B. beim Aufrufen der Drive Files API.
Du kannst alle Google APIs testen und ihre Bereiche im OAuth 2.0 Playground ansehen.
HTTP GET-Beispiele
Ein Aufruf an den Endpunkt
drive.files
(die Drive Files API) mit dem HTTP-Header Authorization: Bearer
könnte so aussehen. Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:
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
-Befehlszeilenanwendung testen. Im folgenden Beispiel wird die HTTP-Header-Option (bevorzugt) verwendet:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Alternativ können Sie die Parameteroption des Abfragestrings verwenden:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Vollständiges Beispiel
Im folgenden Beispiel wird im Google Drive-Konto eines Nutzers eine Liste im JSON-Format ausgegeben, nachdem sich der Nutzer authentifiziert und der Zugriff der Anwendung auf die Drive-Metadaten des Nutzers eingewilligt hat.
PHP
So führen Sie das Beispiel aus:
- Fügen Sie in der API Consoledie URL des lokalen Computers der Liste der Weiterleitungs-URLs hinzu, z. B.
http://localhost:8080
. - Erstellen Sie ein neues Verzeichnis und wechseln Sie dorthin. 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
- Erstellen Sie die Dateien
index.php
undoauth2callback.php
mit dem folgenden Inhalt. - 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
php -S localhost:8080 ~/php-oauth2-example
verwenden.
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 Sie vier Links sehen:
- API-Anfrage testen:Dieser Link verweist auf eine Seite, auf der versucht wird, eine Beispiel-API-Anfrage auszuführen. Bei Bedarf wird der Autorisierungsvorgang gestartet. Bei Erfolg wird auf der Seite die API-Antwort angezeigt.
- Autorisierungsablauf direkt testen:Dieser Link verweist auf eine Seite, auf der versucht wird, den Nutzer durch den Autorisierungsablauf zu leiten. Die Anwendung 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 erteilt hat, widerrufen wird.
- Anmeldedaten für Flask löschen:Über diesen Link werden Autorisierungsanmeldedaten gelöscht, die in der Flask-Sitzung gespeichert sind. So können Sie sehen, was passieren würde, wenn ein Nutzer, der Ihrer App bereits die Berechtigung erteilt hat, versucht, eine API-Anfrage in einer neuen Sitzung auszuführen. Außerdem können Sie die API-Antwort sehen, die Ihre Anwendung erhält, wenn ein Nutzer Berechtigungen widerrufen würde, die Ihrer Anwendung gewährt worden wären, und Ihre Anwendung versucht, 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_v3' require 'sinatra' require 'googleauth' require 'googleauth/stores/redis_token_store' configure do enable :sessions set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json') set :scope, Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope, settings.token_store, '/oauth2callback') end get '/' do user_id = settings.client_id.id credentials = settings.authorizer.get_credentials(user_id, request) if credentials.nil? redirect settings.authorizer.get_authorization_url(login_hint: user_id, request: request) end drive = Google::Apis::DriveV3::DriveService.new files = drive.list_files(options: { authorization: credentials }) "<pre>#{JSON.pretty_generate(files.to_h)}</pre>" end get '/oauth2callback' do target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url end
Node.js
So führen Sie das Beispiel aus:
-
Fügen Sie in der API Consoledie URL des lokalen Computers der Liste der Weiterleitungs-URLs hinzu, z. B.
http://localhost
. - Achten Sie darauf, dass ein Wartungs-LTS, ein aktives LTS oder ein aktueller Node.js-Release installiert ist.
-
Erstellen Sie ein neues Verzeichnis und wechseln Sie dorthin. Beispiel:
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
Install the
Google API Client
Library
for Node.js using npm:
npm install googleapis
-
Erstellen Sie die Dateien
main.js
mit dem folgenden Inhalt. -
Führen Sie das Beispiel aus:
node .\main.js
Main.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 werden das Flask-Framework und die Bibliothek Requests verwendet, um den OAuth 2.0-Webfluss zu demonstrieren. Wir empfehlen die Verwendung der Google API-Clientbibliothek für Python für diesen Ablauf. 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()
Validierungsregeln für Weiterleitungs-URIs
Google wendet bei Weiterleitungs-URIs die folgenden Validierungsregeln an, um Entwicklern zu helfen, ihre Anwendungen zu schützen. Ihre Weiterleitungs-URIs müssen diesen Regeln entsprechen. Unter RFC 3986, Abschnitt 3 finden Sie die unten erwähnte Definition von Domain, Host, Pfad, Abfrage, Schema und Nutzerinformationen.
Validierungsregeln | |
---|---|
Schema |
Weiterleitungs-URIs müssen das HTTPS-Schema verwenden, nicht einfaches HTTP. Localhost-URIs (einschließlich URIs mit localhost-IP-Adressen) sind von dieser Regel ausgenommen. |
Organisator |
Hosts können keine unbearbeiteten IP-Adressen sein. Localhost-IP-Adressen sind von dieser Regel ausgenommen. |
Domain |
“googleusercontent.com” sein.goo.gl ) enthalten, es sei denn, die Anwendung ist Inhaber der Domain. Wenn eine Anwendung, die Inhaber einer Shortener-Domain ist, sich für die Weiterleitung zu dieser Domain entscheidet, muss dieser 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 Verzeichnis-Backtracking genannt) enthalten, der durch ein |
Abfrage |
Weiterleitungs-URIs dürfen keine offenen Weiterleitungen enthalten. |
Fragment |
Weiterleitungs-URIs dürfen die Fragmentkomponente nicht enthalten. |
Zeichen |
Weiterleitungs-URIs dürfen nicht die folgenden Zeichen 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 gilt als Best Practice, die Autorisierung für Ressourcen dann anzufordern, wenn Sie sie benötigen. Um diese Vorgehensweise zu ermöglichen, 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 gewährt, wird ein Autorisierungscode zurückgegeben, der gegen ein Token ausgetauscht werden kann, das alle Bereiche enthält, die der Nutzer dem Projekt gewährt hat.
Beispiel: Eine App, mit der Nutzer Musiktitel verwenden und Mixe erstellen können, benötigt bei der Anmeldung möglicherweise nur sehr wenige Ressourcen – unter Umständen nur den Namen der Person, die sich anmeldet. Zum Speichern eines fertigen Mixes wäre jedoch Zugriff auf Google Drive erforderlich. Die meisten Nutzer würden es ganz normal finden, wenn sie nur dann Zugriff auf ihr Google Drive erhalten würden, als die App es tatsächlich benötigt.
In diesem Fall fordert die Anwendung bei der Anmeldung möglicherweise die Bereiche openid
und profile
an, um eine einfache Anmeldung durchzuführen. Später fordert die Anwendung dann bei der ersten Anfrage den Bereich https://www.googleapis.com/auth/drive.file
an, um eine Kombination zu speichern.
Wenn Sie die inkrementelle Autorisierung implementieren möchten, führen Sie den normalen Vorgang zum Anfordern eines Zugriffstokens aus, achten Sie aber darauf, dass die Autorisierungsanfrage zuvor gewährte Bereiche enthält. So vermeiden Sie, dass Ihre Anwendung mehrere Zugriffstokens verwalten muss.
Die folgenden Regeln gelten für ein Zugriffstoken, das durch eine inkrementelle Autorisierung abgerufen wird:
- Mit dem Token kann auf Ressourcen zugegriffen werden, die den Bereichen entsprechen, die in der neuen kombinierten Autorisierung zusammengefasst sind.
- Wenn Sie mit dem Aktualisierungstoken für die kombinierte Autorisierung ein Zugriffstoken abrufen, stellt das Zugriffstoken die kombinierte Autorisierung dar und kann für jeden der
scope
-Werte in der Antwort 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 Desktopclient einer Anwendung Zugriff auf einen Bereich gewährt und dann derselben Anwendung über einen mobilen Client einen anderen Bereich zuweist, 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.
Die sprachspezifischen Codebeispiele in Schritt 1: Autorisierungsparameter festlegen und die Beispiel-HTTP/REST-Weiterleitungs-URL in Schritt 2: An den OAuth 2.0-Server von Google weiterleiten verwenden alle die inkrementelle Autorisierung. 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 durchaus möglich, dass include_granted_scopes
nicht das einzige Schlüsselwortargument ist, das Sie festgelegt haben (siehe Beispiel unten).
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 regelmäßig ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne dass der Nutzer um eine Berechtigung gebeten wird (auch wenn der Nutzer 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 nach Bedarf, solange Sie dieses Objekt für den Offlinezugriff konfigurieren.
- Wenn Sie keine Clientbibliothek verwenden, müssen Sie den HTTP-Abfrageparameter
access_type
aufoffline
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 anderen Zeitpunkt), können Sie ein Aktualisierungstoken verwenden, um ein neues Zugriffstoken abzurufen.
Das Anfordern des Offlinezugriffs ist eine Voraussetzung für jede Anwendung, die auf eine Google API zugreifen muss, wenn der Nutzer nicht anwesend ist. Beispielsweise muss eine Anwendung, die Sicherungsdienste oder Aktionen zu vorab festgelegten Zeiten ausführt, ihr Zugriffstoken aktualisieren können, 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 Webanwendungen (JavaScript) verwendet.
PHP
Wenn Ihre 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, kannst du den API-Client weiterhin 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 die Berechtigung beim Nutzer noch einmal einholen zu müssen. Es ist durchaus 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, kannst du den API-Client weiterhin verwenden, um im Namen des Nutzers auf Google APIs zuzugreifen, wenn der Nutzer offline ist. Das Clientobjekt aktualisiert das Zugriffstoken nach Bedarf.
Ruby
Wenn Ihre 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, kannst du den API-Client weiterhin 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 Ihre 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, kannst du den API-Client weiterhin 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 es bald abläuft. Mit dem Token-Ereignis können Sie ganz einfach dafür sorgen, dass immer die neuesten Tokens gespeichert werden:
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. Du musst access_type
auf offline
setzen, wenn die Methode generateAuthUrl
aufgerufen wird, um das Aktualisierungstoken zu erhalten. Wenn Sie Ihrer Anwendung bereits 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 erfasst und beim nächsten Aufruf an die API automatisch aktualisiert.
HTTP/REST
Zum Aktualisieren eines Zugriffstokens sendet Ihre Anwendung eine HTTPS-POST
-Anfrage mit den folgenden Parametern an den Autorisierungsserver https://oauth2.googleapis.com/token
von Google:
Felder | |
---|---|
client_id |
Die vom API Consoleabgerufene Client-ID. |
client_secret |
Der vom API Consoleabgerufene Clientschlüssel. |
grant_type |
Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Felds auf refresh_token festgelegt werden. |
refresh_token |
Das vom Austausch des Autorisierungscodes 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 der Anwendung gewährten 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" }
Die Anzahl der ausgegebenen Aktualisierungstokens ist begrenzt: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens langfristig aufbewahren und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits überschritten werden. Ältere Aktualisierungstokens funktionieren in diesem Fall nicht mehr.
Token widerrufen
Manchmal möchte ein Nutzer den Zugriff einer App widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument Website- oder App-Zugriff entfernen auf Websites und Apps von Drittanbietern mit Zugriff auf dein Konto.
Eine Anwendung kann den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer das Abo kündigt, eine Anwendung entfernt oder sich die für eine Anwendung erforderlichen API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage beinhalten, mit der sichergestellt wird, dass die zuvor der Anwendung gewährten Berechtigungen entfernt werden.
PHP
Wenn Sie ein Token programmatisch widerrufen möchten, rufen Sie revokeToken()
auf:
$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 es sich bei dem Token um ein Zugriffstoken handelt und es über ein entsprechendes Aktualisierungstoken verfügt, wird auch das Aktualisierungstoken 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 Parameter „token“ kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es über ein entsprechendes Aktualisierungstoken verfügt, wird auch das Aktualisierungstoken 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
Zum programmatischen Widerrufen eines Tokens sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke
und nimmt das Token als Parameter auf:
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 es sich bei dem Token um ein Zugriffstoken handelt und es über ein entsprechendes Aktualisierungstoken verfügt, wird auch das Aktualisierungstoken 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.