OAuth 2.0 für Webserveranwendungen verwenden

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. Eine Anwendung kann beispielsweise OAuth 2.0 verwenden, um die Berechtigung von Nutzern zum Speichern von Dateien in ihren Google Drives zu erhalten.

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

Webserveranwendungen verwenden häufig auch Dienstkonten, um API-Anfragen zu autorisieren, insbesondere beim Aufrufen von Cloud APIs für den Zugriff auf projektbasierte Daten anstelle von nutzerspezifischen Daten. Webserveranwendungen können Dienstkonten in Verbindung mit der Nutzerautorisierung verwenden.

Hinweis:Angesichts der Sicherheitsrisiken, die mit einer fehlerhaften Implementierung verbunden sind, empfehlen wir dringend, OAuth 2.0-Bibliotheken zu verwenden, wenn Sie mit den OAuth 2.0-Endpunkten von Google interagieren. Es ist eine Best Practice, gut debuggten Code von anderen zu verwenden. So können Sie sich und Ihre Nutzer schützen. Weitere Informationen finden Sie unter Clientbibliotheken.

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-Ablauf Ihrer Anwendung zu verarbeiten, führt die Clientbibliothek viele Aktionen aus, die die Anwendung ansonsten selbst ausführen müsste. So wird beispielsweise festgelegt, wann die Anwendung gespeicherte Zugriffstokens verwenden oder aktualisieren kann und wann die Einwilligung neu eingeholt werden muss. Die Clientbibliothek generiert auch korrekte Weiterleitungs-URLs und hilft bei der Implementierung von Weiterleitungs-Handlern, die Autorisierungscodes gegen Zugriffstokens tauschen.

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

• Go
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

Wichtig:Die Google API-Clientbibliothek für JavaScript und Mit Google anmelden sind nur für die Verarbeitung von OAuth 2.0 im Browser des Nutzers vorgesehen. Wenn Sie serverseitig JavaScript verwenden möchten, um OAuth 2.0-Interaktionen mit Google zu verwalten, sollten Sie die Node.js-Bibliothek auf Ihrer Backend-Plattform verwenden.

Vorbereitung

Die APIs für Ihr Projekt aktivieren

Für jede Anwendung, die Google APIs aufruft, müssen diese APIs in der API Consoleaktiviert werden.

So aktivieren Sie eine API für Ihr Projekt:

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

Anmeldedaten für die Autorisierung erstellen

Für jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, müssen Autorisierungsanmeldedaten vorhanden sein, mit denen die Anwendung beim 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 mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

1. Go to the Credentials page.
2. Klicken Sie auf Create Client.
3. Wählen Sie den Anwendungstyp Webanwendung aus.
4. 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.

   Für Tests können Sie URIs angeben, die auf den lokalen Computer verweisen, z. B. http://localhost:8080. Daher wird in allen Beispielen in diesem Dokument http://localhost:8080 als Weiterleitungs-URI verwendet.

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

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

Wichtig:Speichern Sie die Datei client_secret.json nicht an einem öffentlich zugänglichen Ort. Wenn Sie den Quellcode Ihrer Anwendung freigeben, z. B. auf GitHub, sollten Sie die Datei client_secret.json außerhalb der Quellstruktur speichern, um zu vermeiden, dass Ihre Clientanmeldedaten versehentlich freigegeben werden.

Der Clientschlüssel Ihrer Anwendung wird erst angezeigt, nachdem Sie den Client erstellt haben. Sie können den Clientschlüssel dann nicht mehr aufrufen oder herunterladen. Weitere Informationen

Zugriffsbereiche ermitteln

Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher kann es ein umgekehrtes Verhältnis zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit geben, dass die Einwilligung des Nutzers eingeholt wird.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, empfehlen wir Ihnen, die Bereiche zu identifizieren, für die Ihre Anwendung eine Zugriffsberechtigung benötigt.

Wir empfehlen außerdem, dass Ihre Anwendung den Zugriff auf Autorisierungsbereiche über eine schrittweise Autorisierung anfordert, bei der Ihre Anwendung den Zugriff auf Nutzerdaten im Kontext anfordert. So können Nutzer leichter 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.

Wenn Ihre öffentliche Anwendung Bereiche verwendet, die den Zugriff auf bestimmte Nutzerdaten ermöglichen, muss sie ein Überprüfungsverfahren durchlaufen. Wenn beim Testen Ihrer Anwendung auf dem Bildschirm Nicht bestätigte App angezeigt wird, müssen Sie einen Bestätigungsantrag einreichen, um die Meldung zu entfernen. Weitere Informationen zu nicht bestätigten Apps und Antworten auf häufig gestellte Fragen zur App-Bestätigung finden Sie in der Hilfe.

Sprachspezifische Anforderungen

Wenn Sie eines der Codebeispiele in diesem Dokument ausführen möchten, benötigen Sie ein Google-Konto, Internetzugang und einen Webbrowser. Wenn Sie eine der API-Clientbibliotheken verwenden, lesen Sie auch die sprachspezifischen Anforderungen unten.

PHP

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

• PHP 8.0 oder höher mit installierter Befehlszeile (Command Line Interface, CLI) und JSON-Erweiterung.
• Das Tool zur Abhängigkeitsverwaltung Composer.

• Die Google APIs-Clientbibliothek für PHP:

  composer require google/apiclient:^2.15.0

Weitere Informationen finden Sie unter Google APIs-Clientbibliothek für PHP.

Python

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

• Python 3.7 oder höher
• Das Paketverwaltungstool pip
• Die Google APIs-Clientbibliothek für Python 2.0 bietet folgende Vorteile:

  pip install --upgrade google-api-python-client

• Die google-auth, google-auth-oauthlib und google-auth-httplib2 für die Nutzerautorisierung.

  pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

• Das Flask-Python-Webanwendungs-Framework.

  pip install --upgrade flask

• Die requests-HTTP-Bibliothek.

  pip install --upgrade requests

Sehen Sie sich die Versionshinweise zur Google API-Clientbibliothek für Python an, wenn Sie Python und den zugehörigen Migrationsleitfaden nicht aktualisieren können.

Ruby

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

• Ruby 2.6 oder höher

• Die Google Auth Library für Ruby:

  gem install googleauth

• Die Clientbibliotheken für die Google Drive- und Google Calendar-APIs:

  gem install google-apis-drive_v3 google-apis-calendar_v3

• Das Sinatra-Ruby-Webanwendungs-Framework.

  gem install sinatra

Node.js

Wenn Sie die Node.js-Codebeispiele in diesem Dokument ausführen möchten, benötigen Sie Folgendes:

• Der Maintenance-LTS-, Active-LTS- oder aktuelle Release von Node.js.

• Der Google APIs Node.js-Client:

  npm install googleapis crypto express express-session

HTTP/REST

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

OAuth 2.0-Zugriffstokens abrufen

In den folgenden Schritten wird beschrieben, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Zustimmung eines Nutzers zum Ausführen einer API-Anfrage in seinem Namen einzuholen. Ihre Anwendung muss diese Einwilligung haben, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.

In der folgenden Liste sind diese Schritte kurz zusammengefasst:

1. Ihre Anwendung gibt die benötigten Berechtigungen an.
2. Ihre Anwendung leitet den Nutzer zusammen mit der Liste der angeforderten Berechtigungen zu Google weiter.
3. Der Nutzer entscheidet, ob er Ihrer Anwendung die Berechtigungen erteilt.
4. Ihre Anwendung erfährt, wie sich der Nutzer entschieden hat.
5. Wenn der Nutzer die angeforderten Berechtigungen gewährt hat, ruft Ihre Anwendung die erforderlichen Tokens ab, um API-Anfragen im Namen des Nutzers zu stellen.

Schritt 1: Autorisierungsparameter festlegen

Als Erstes müssen Sie die Autorisierungsanfrage erstellen. In dieser Anfrage werden Parameter festgelegt, die Ihre Anwendung identifizieren und die Berechtigungen definieren, die der Nutzer Ihrer Anwendung gewähren soll.

• 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, wird eine URL generiert und die Parameter für diese URL festgelegt.

Auf den Tabs unten sind die unterstützten Autorisierungsparameter für Webserveranwendungen definiert. In den sprachspezifischen Beispielen wird auch gezeigt, wie Sie eine Clientbibliothek oder Autorisierungsbibliothek verwenden, um ein Objekt zu konfigurieren, 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 gibt auch die Bereiche an, für die Ihre Anwendung die Berechtigung zum Zugriff anfordert, sowie die URL des Authentifizierungsendpunkts Ihrer Anwendung, der die Antwort des OAuth 2.0-Servers von Google verarbeitet. Schließlich werden die optionalen Parameter access_type und include_granted_scopes festgelegt.

Mit diesem Code wird beispielsweise schreibgeschützter Offlinezugriff auf die Google Drive-Metadaten und Kalendertermine eines Nutzers angefordert:

use Google\Client;

$client = new Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfig('client_secret.json');

// Required, to set the scope value, call the addScope function
$client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);

// Required, call the setRedirectUri function to specify a valid redirect URI for the
// provided client_id
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');

// Recommended, 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');

// Recommended, call the setState function. Using a state value can increase your assurance that
// an incoming connection is the result of an authentication request.
$client->setState($sample_passthrough_value);

// Optional, if your application knows which user is trying to authenticate, it can use this
// parameter to provide a hint to the Google Authentication Server.
$client->setLoginHint('[e-mail]');

// Optional, call the setPrompt function to set "consent" will prompt the user for consent
$client->setPrompt('consent');

// Optional, call the setIncludeGrantedScopes function with true to enable incremental
// authorization
$client->setIncludeGrantedScopes(true);

Python

Im folgenden Code-Snippet wird das Modul google-auth-oauthlib.flow verwendet, um die Autorisierungsanfrage zu erstellen.

Der Code erstellt ein Flow-Objekt, das Ihre Anwendung anhand von Informationen aus der Datei client_secret.json identifiziert, die Sie nach dem Erstellen von Autorisierungsanmeldedaten heruntergeladen haben. Dieses Objekt gibt auch die Bereiche an, für die Ihre Anwendung die Berechtigung zum Zugriff anfordert, sowie die URL des Authentifizierungsendpunkts Ihrer Anwendung, der die Antwort des OAuth 2.0-Servers von Google verarbeitet. Schließlich werden die optionalen Parameter access_type und include_granted_scopes festgelegt.

Mit diesem Code wird beispielsweise schreibgeschützter Offlinezugriff auf die Google Drive-Metadaten und Kalendertermine eines Nutzers angefordert:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Required, call the from_client_secrets_file method to retrieve the client ID from a
# client_secret.json file. The client ID (from that file) and access scopes are required. (You can
# also use the from_client_config method, which passes the client configuration as it originally
# appeared in a client secrets file but doesn't access the file itself.)
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly',
            'https://www.googleapis.com/auth/calendar.readonly'])

# Required, 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(
    # Recommended, 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',
    # Optional, enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true',
    # Optional, if your application knows which user is trying to authenticate, it can use this
    # parameter to provide a hint to the Google Authentication Server.
    login_hint='[e-mail]',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

Verwenden Sie die Datei „client_secrets.json“, die Sie erstellt haben, 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 vom OAuth 2.0-Server verarbeitet.

Mit diesem Code wird beispielsweise schreibgeschützter Offlinezugriff auf die Google Drive-Metadaten und Kalendertermine eines Nutzers angefordert:

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/drive_v3'
require 'google/apis/calendar_v3'

# Required, call the from_file method to retrieve the client ID from a
# client_secret.json file.
client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')

# Required, scope value 
# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
         'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

# Required, Authorizers require a storage instance to manage long term persistence of
# access and refresh tokens.
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

# Required, 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.
callback_uri = '/oauth2callback'

# 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.
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope,
                                                token_store, callback_uri)

Ihre Anwendung verwendet das Client-Objekt, um OAuth 2.0-Vorgänge auszuführen, z. B. Autorisierungsanfrage-URLs zu generieren und Zugriffstokens auf HTTP-Anfragen anzuwenden.

Node.js

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

Dieses Objekt verwendet Informationen aus Ihrer Datei „client_secret.json“, um Ihre Anwendung zu identifizieren. Wenn Sie einen Nutzer um Berechtigungen zum Abrufen eines Zugriffstokens bitten möchten, leiten Sie ihn zu einer Einwilligungsseite weiter. So erstellen Sie eine URL für die Einwilligungsseite:

const {google} = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a secure random state value.
const state = crypto.randomBytes(32).toString('hex');

// Store state in the session
req.session.state = state;

// Generate a url that asks permissions for the Drive activity and Google Calendar 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,
  // Include the state parameter to reduce the risk of CSRF attacks.
  state: state
});

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

HTTP/REST

Der OAuth 2.0-Endpunkt von Google ist https://accounts.google.com/o/oauth2/v2/auth. Dieser Endpunkt ist nur über HTTPS zugänglich. Reine 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 .
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 Sie in der Ihres Clients konfiguriert haben. . Wenn dieser Wert nicht mit einem autorisierten Weiterleitungs-URI für die angegebene client_id übereinstimmt, erhalten Sie einen redirect_uri_mismatch-Fehler. Das Schema http oder https, die Groß- und Kleinschreibung und der nachgestellte Schrägstrich („/“) müssen übereinstimmen.
response_type	Erforderlich Gibt an, ob der Google OAuth 2.0-Endpunkt einen Autorisierungscode zurückgibt. Legen Sie den Parameterwert für Webserveranwendungen auf code fest.
scope	Erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte werden auf dem Zustimmungsbildschirm angezeigt, den Google dem Nutzer präsentiert. Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht ein umgekehrtes Verhältnis zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, dass Nutzer ihre Einwilligung erteilen. Wir empfehlen, dass Ihre Anwendung nach Möglichkeit kontextbezogenen Zugriff auf Autorisierungsbereiche anfordert. Wenn Sie über die schrittweise Autorisierung im Kontext auf Nutzerdaten zugreifen, 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 am Browser ist. Gültige Parameterwerte sind online (Standardwert) und offline. Legen Sie den Wert auf offline fest, wenn Ihre Anwendung Zugriffstokens aktualisieren muss, wenn der Nutzer nicht am Browser ist. Dies ist die Methode zum Aktualisieren von Zugriffstokens, die weiter unten in diesem Dokument beschrieben wird. Mit diesem Wert wird der Google-Autorisierungsserver angewiesen, beim ersten Mal, wenn Ihre Anwendung einen Autorisierungscode gegen Tokens eintauscht, ein Aktualisierungstoken und ein Zugriffstoken zurückzugeben.
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 den genauen Wert zurück, den Sie als name=value-Paar in der URL-Anfragekomponente (?) des redirect_uri senden, nachdem der Nutzer der Zugriffsanfrage Ihrer Anwendung zugestimmt oder sie abgelehnt hat. Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung weiterzuleiten, Nounces zu senden und Cross-Site-Request-Forgery zu verhindern. Da Ihr redirect_uri erraten werden kann, kann die Verwendung eines state-Werts die Wahrscheinlichkeit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den Status des Clients erfasst, können Sie die Antwort validieren, um zusätzlich sicherzustellen, dass Anfrage und Antwort aus demselben Browser stammen. So können Sie sich vor Angriffen wie Cross-Site Request Forgery schützen. Ein Beispiel für das Erstellen und Bestätigen eines state-Tokens finden Sie in der OpenID Connect-Dokumentation. Wichtig:Der OAuth-Client muss CSRF verhindern, wie in der OAuth2-Spezifikation beschrieben. Eine Möglichkeit, dies zu erreichen, ist die Verwendung des Parameters state, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers beizubehalten.
include_granted_scopes	Optional Ermöglicht Anwendungen, die schrittweise Autorisierung zu verwenden, um im Kontext Zugriff auf zusätzliche Bereiche anzufordern. Wenn Sie den Wert dieses Parameters auf true festlegen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken auch alle Bereiche ab, auf die der Nutzer der Anwendung zuvor Zugriff gewährt hat. Beispiele finden Sie im Abschnitt Inkrementelle Autorisierung.
enable_granular_consent	Optional Die Standardeinstellung ist true. Wenn der Wert auf false festgelegt ist, werden granularere Google-Konto-Berechtigungen für OAuth-Client-IDs deaktiviert, die vor 2019 erstellt wurden. Bei neueren OAuth-Client-IDs hat das keine Auswirkungen, da für sie immer detailliertere Berechtigungen aktiviert sind. Wenn Google detaillierte Berechtigungen für eine Anwendung aktiviert, hat dieser Parameter keine Auswirkungen mehr.
login_hint	Optional Wenn Ihre Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie diesen Parameter verwenden, um dem Google-Authentifizierungsserver einen Hinweis zu geben. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er entweder das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Multi-Login-Sitzung auswählt. Legen Sie den Parameterwert auf eine E-Mail-Adresse oder eine sub-Kennung fest, die der Google-ID des Nutzers entspricht.
prompt	Optional Eine durch Leerzeichen getrennte Liste von Aufforderungen, die dem Nutzer präsentiert werden sollen. Bei den Aufforderungen wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur beim ersten Zugriff auf Ihr Projekt aufgefordert, die Berechtigung zu erteilen. Weitere Informationen finden Sie unter Erneute Einwilligung einholen. Folgende Werte sind möglich: none Es dürfen keine Authentifizierungs- oder Zustimmungsbildschirme angezeigt werden. Darf nicht mit anderen Werten angegeben werden. consent Nutzer um Einwilligung bitten select_account Fordern Sie den Nutzer auf, ein Konto auszuwählen.

Schritt 2: Weiterleitung an den OAuth 2.0-Server von Google

Leiten Sie den Nutzer zum OAuth 2.0-Server von Google weiter, um den Authentifizierungs- und Autorisierungsprozess zu starten. Dies geschieht in der Regel, wenn Ihre Anwendung zum ersten Mal auf die Daten des Nutzers zugreifen muss. Bei der inkrementellen Autorisierung erfolgt dieser Schritt auch, wenn Ihre Anwendung zum ersten Mal auf zusätzliche Ressourcen zugreifen muss, für die sie noch keine Berechtigung hat.

PHP

1. Generieren Sie eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:

   $auth_url = $client->createAuthUrl();

2. Leiten Sie den Nutzer zu $auth_url weiter:

   header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

In diesem Beispiel wird gezeigt, wie Sie den Nutzer mit dem Flask-Webanwendungs-Framework zur Autorisierungs-URL weiterleiten:

return flask.redirect(authorization_url)

Ruby

1. Generieren Sie eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:

   auth_uri = authorizer.get_authorization_url(request: request)

2. Verweise den Nutzer an auth_uri.

Node.js

1. Verwenden Sie die generierte URL authorizationUrl aus der Methode generateAuthUrl in Schritt 1, um Zugriff vom OAuth 2.0-Server von Google anzufordern.
2. Verweise den Nutzer an authorizationUrl.

   res.redirect(authorizationUrl);

HTTP/REST

Beispiel für eine Weiterleitung an den Google-Autorisierungsserver

Unten sehen Sie ein Beispiel für eine URL mit Zeilenumbrüchen und Leerzeichen für eine bessere Lesbarkeit.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.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 Ihre Anwendung auf die angeforderten Bereiche zugreifen kann. Die Antwort wird über die von Ihnen angegebene Weiterleitungs-URL an Ihre Anwendung zurückgesendet.

Schritt 3: Google fordert Nutzer zur Einwilligung auf

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewähren möchte. In dieser Phase zeigt Google ein Zustimmungsfenster an, in dem der Name Ihrer Anwendung und die Google API-Dienste angezeigt werden, für die mit den Autorisierungsanmeldedaten des Nutzers eine Berechtigung angefordert wird, sowie eine Zusammenfassung der zu erteilenden Zugriffsbereiche. Der Nutzer kann dann zustimmen, den Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.

Ihre Anwendung muss in dieser Phase nichts tun, da sie auf die Antwort des OAuth 2.0-Servers von Google wartet, in der angegeben wird, ob Zugriff gewährt wurde. Diese Antwort wird im nächsten Schritt erläutert.

Fehler

Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden möglicherweise für Nutzer sichtbare Fehlermeldungen anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe angezeigt. Häufige Fehlercodes und empfohlene Lösungen sind unten aufgeführt.

admin_policy_enforced

Das Google-Konto kann aufgrund der Richtlinien des Google Workspace-Administrators einen oder mehrere angeforderte Bereiche nicht autorisieren. Weitere Informationen dazu, wie ein Administrator den Zugriff auf alle Bereiche oder auf vertrauliche und eingeschränkte Bereiche einschränken kann, bis der Zugriff explizit für Ihre OAuth-Client-ID gewährt wird, finden Sie im Google Workspace-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 sehen diese Fehlermeldung möglicherweise, wenn sie Autorisierungsanfragen in android.webkit.WebView öffnen. Entwickler sollten stattdessen Android-Bibliotheken wie Google Sign-In for Android oder AppAuth for Android von der OpenID Foundation verwenden.

Webentwickler können auf diesen Fehler stoßen, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von Ihrer Website aus zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten zulassen, dass allgemeine Links im Standard-Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Android App Links-Handler als auch die Standardbrowser-App. Die Android Custom Tabs-Bibliothek ist ebenfalls eine unterstützte Option.

iOS

iOS- und macOS-Entwickler können diesen Fehler erhalten, wenn sie Autorisierungsanfragen in WKWebView öffnen. Entwickler sollten stattdessen iOS-Bibliotheken wie Google Sign-In for iOS oder AppAuth for iOS von der OpenID Foundation verwenden.

Webentwickler können auf diesen Fehler stoßen, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von Ihrer Website aus zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten zulassen, dass allgemeine Links im Standard-Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Universal Links-Handler als auch die Standardbrowser-App. Die SFSafariViewController-Bibliothek ist ebenfalls eine unterstützte Option.

org_internal

Die OAuth-Client-ID in der Anfrage gehört zu einem Projekt, 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

Das OAuth-Client-Secret ist falsch. Überprüfen Sie die OAuth-Clientkonfiguration, einschließlich der für diese Anfrage verwendeten Client-ID und des Clientschlüssels.

deleted_client

Der OAuth-Client, der für die Anfrage verwendet wird, wurde gelöscht. Das Löschen kann manuell oder automatisch erfolgen, z. B. bei nicht verwendeten Clients . Gelöschte Mandanten können innerhalb von 30 Tagen nach dem Löschen wiederhergestellt werden. Weitere Informationen

invalid_grant

Beim Aktualisieren eines Zugriffstokens oder bei Verwendung der inkrementellen Autorisierung ist das Token möglicherweise abgelaufen oder wurde ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um die Einwilligung, neue Tokens zu erhalten. Wenn dieser Fehler weiterhin auftritt, prüfen Sie, ob Ihre Anwendung richtig konfiguriert ist und ob Sie die richtigen Tokens und Parameter in Ihrer Anfrage verwenden. Andernfalls wurde das Nutzerkonto möglicherweise gelöscht oder deaktiviert.

redirect_uri_mismatch

Der in der Autorisierungsanfrage übergebene redirect_uri stimmt nicht mit einem autorisierten Weiterleitungs-URI für die OAuth-Client-ID überein. Überprüfen Sie die autorisierten Weiterleitungs-URIs in der .

Der Parameter redirect_uri bezieht sich möglicherweise auf den OAuth-Out-of-Band-Ablauf (OOB), der eingestellt wurde und nicht mehr unterstützt wird. Weitere Informationen finden Sie in der Migrationsanleitung.

invalid_request

Bei Ihrer Anfrage ist ein Fehler aufgetreten. Das kann verschiedene Gründe haben:

• Die Anfrage war nicht richtig formatiert
• In der Anfrage fehlten erforderliche Parameter.
• Die Anfrage verwendet eine Autorisierungsmethode, die von Google nicht unterstützt wird. Prüfen, ob für Ihre OAuth-Integration eine empfohlene Integrationsmethode verwendet wird

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Wichtig:Bevor Sie die OAuth 2.0-Antwort auf dem Server verarbeiten, sollten Sie bestätigen, dass der von Google empfangene state mit dem im Autorisierungsantrag gesendeten state übereinstimmt. Diese Bestätigung trägt dazu bei, dass die Anfrage vom Nutzer und nicht von einem schädlichen Skript stammt, und verringert das Risiko von CSRF-Angriffen.

Der OAuth 2.0-Server antwortet auf die Zugriffsanfrage Ihrer Anwendung über die in der Anfrage angegebene 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 angezeigt, wie unten dargestellt:

Eine Fehlerantwort:

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

Antwort mit Autorisierungscode:

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

Wichtig:Wenn Ihr Antwortendpunkt eine HTML-Seite rendert, können alle Ressourcen auf dieser Seite den Autorisierungscode in der URL sehen. Scripts können die URL direkt lesen und die URL im Referer-HTTP-Header kann an beliebige oder alle Ressourcen auf der Seite gesendet werden.

Überlegen Sie genau, ob Sie Autorisierungsanmeldedaten an alle Ressourcen auf dieser Seite senden möchten, insbesondere an Drittanbieter-Scripts wie Social-Media-Plug-ins und Analysetools. Um dieses Problem zu vermeiden, empfehlen wir, dass der Server die Anfrage zuerst verarbeitet und dann zu einer anderen URL weiterleitet, die die Antwortparameter nicht enthält.

Beispiel für eine OAuth 2.0-Serverantwort

Sie können diesen Ablauf testen, indem Sie auf die folgende Beispiel-URL klicken, mit der schreibgeschützter Zugriff zum Anzeigen von Metadaten für Dateien in Ihrem Google Drive und schreibgeschützter Zugriff zum Anzeigen Ihrer Google Kalender-Termine angefordert wird:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.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-Ablaufs sollten Sie zu http://localhost/oauth2callback weitergeleitet werden. Dort wird wahrscheinlich ein 404 NOT FOUND-Fehler angezeigt, sofern auf Ihrem lokalen Computer keine Datei unter dieser Adresse bereitgestellt wird. Im nächsten Schritt finden Sie weitere Informationen zu den Informationen, die im URI zurückgegeben werden, 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 ihn gegen ein Zugriffstoken eintauschen.

PHP

So tauschen Sie einen Autorisierungscode gegen ein Zugriffstoken ein:fetchAccessTokenWithAuthCode

$access_token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

Python

Verwenden Sie auf Ihrer Callback-Seite die google-auth-Bibliothek, 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 einzutauschen:

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,
    'granted_scopes': credentials.granted_scopes}

Ruby

Verwenden Sie auf Ihrer Callback-Seite die googleauth-Bibliothek, um die Antwort des Autorisierungsservers zu überprüfen. Verwenden Sie die Methode authorizer.handle_auth_callback_deferred, um den Autorisierungscode zu speichern und zur URL zurückzuleiten, die die Autorisierung ursprünglich angefordert hat. Dadurch wird der Austausch des Codes verzögert, indem die Ergebnisse vorübergehend in der Sitzung des Nutzers 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 einzutauschen:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
app.get('/oauth2callback', async (req, res) => {
  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 if (q.state !== req.session.state) { //check state value
    console.log('State mismatch. Possible CSRF attack');
    res.end('State mismatch. Possible CSRF attack');
  } else { // 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 eintauschen möchten, rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen Sie die folgenden Parameter fest:

Felder
client_id	Die Client-ID, die von der abgerufen wurde.
client_secret	Der Clientschlüssel, der von abgerufen wurde.
code	Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde.
grant_type	Gemäß der OAuth 2.0-Spezifikation muss der Wert dieses Felds auf authorization_code gesetzt werden.
redirect_uri	Einer der Weiterleitungs-URIs, die für Ihr Projekt in der 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 mit einem JSON-Objekt, 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 oder das Aktualisierungstoken abläuft. Auch dieses Feld ist nur in dieser Antwort vorhanden, wenn Sie den Parameter access_type in der ursprünglichen Anfrage an den Autorisierungsserver von Google auf offline festgelegt haben.
refresh_token_expires_in	Die verbleibende Lebensdauer des Aktualisierungstokens in Sekunden. Dieser Wert wird nur festgelegt, wenn der Nutzer zeitbasierten Zugriff gewährt.
scope	Die von access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten, groß- und kleinschreibungsabhängigen Strings.
token_type	Der Typ des zurückgegebenen Tokens. Der Wert dieses Felds ist derzeit immer auf Bearer festgelegt.

Wichtig:Ihre Anwendung sollte beide Tokens an einem sicheren, langlebigen Ort speichern, auf den bei verschiedenen Aufrufen Ihrer Anwendung zugegriffen werden kann. Mit dem Aktualisierungstoken kann Ihre Anwendung ein neues Zugriffstoken abrufen, wenn das vorhandene abläuft. Wenn das Aktualisierungstoken verloren geht, muss der Nutzer den OAuth 2.0-Einwilligungsvorgang wiederholen, damit Ihre Anwendung ein neues Aktualisierungstoken erhalten kann.

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 https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Hinweis:Ihre Anwendung sollte alle nicht erkannten Felder in der Antwort ignorieren.

Fehler

Beim Tauschen des Autorisierungscodes gegen ein Zugriffstoken kann anstelle der erwarteten Antwort der folgende Fehler auftreten. Häufige Fehlercodes und empfohlene Lösungen sind unten aufgeführt.

invalid_grant

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

Schritt 6: Prüfen, welche Bereiche Nutzer gewährt haben

Wenn Sie mehrere Berechtigungen (Bereich) anfordern, gewähren Nutzer Ihrer App möglicherweise nicht für alle Zugriff. Ihre App muss prüfen, welche Bereiche tatsächlich gewährt wurden, und Situationen, in denen einige Berechtigungen verweigert werden, angemessen behandeln. In der Regel werden die Funktionen deaktiviert, die auf diesen verweigerten Bereichen basieren.

Es gibt jedoch Ausnahmen. Google Workspace Enterprise-Apps mit domainweiter Übertragung von Befugnissen oder Apps, die als Vertrauenswürdig gekennzeichnet sind, umgehen den Zustimmungsbildschirm für detaillierte Berechtigungen. Nutzern dieser Apps wird der Zustimmungsbildschirm für detaillierte Berechtigungen nicht angezeigt. Stattdessen erhält Ihre App entweder alle angeforderten Bereiche oder keinen.

Weitere Informationen finden Sie unter Granulare Berechtigungen verwalten.

PHP

Mit der Methode getGrantedScope() können Sie prüfen, welche Bereiche der Nutzer gewährt hat:

// Space-separated string of granted scopes if it exists, otherwise null.
$granted_scopes = $client->getOAuth2Service()->getGrantedScope();

// Determine which scopes user granted and build a dictionary
$granted_scopes_dict = [
  'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
  'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
];

Python

Das zurückgegebene credentials-Objekt hat das Attribut granted_scopes, das eine Liste der Bereiche ist, die der Nutzer Ihrer App gewährt hat.

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,
    'granted_scopes': credentials.granted_scopes}

Mit der folgenden Funktion wird geprüft, welche Bereiche der Nutzer Ihrer App gewährt hat.

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

Ruby

Wenn Sie mehrere Bereiche gleichzeitig anfordern, prüfen Sie, welche Bereiche über die scope-Eigenschaft des credentials-Objekts gewährt wurden.

# User authorized the request. Now, check which scopes were granted.
if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
  # User authorized read-only Drive activity permission.
  # Calling the APIs, etc
else
  # User didn't authorize read-only Drive activity permission.
  # Update UX and application accordingly
end

# Check if user authorized Calendar read permission.
if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
  # User authorized Calendar read permission.
  # Calling the APIs, etc.
else
  # User didn't authorize Calendar read permission.
  # Update UX and application accordingly
end

Node.js

Wenn Sie mehrere Bereiche gleichzeitig anfordern, prüfen Sie, welche Bereiche über die scope-Eigenschaft des tokens-Objekts gewährt wurden.

// User authorized the request. Now, check which scopes were granted.
if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly'))
{
  // User authorized read-only Drive activity permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize read-only Drive activity permission.
  // Update UX and application accordingly
}

// Check if user authorized Calendar read permission.
if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
{
  // User authorized Calendar read permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize Calendar read permission.
  // Update UX and application accordingly
}

HTTP/REST

Wenn Sie prüfen möchten, ob der Nutzer Ihrer Anwendung Zugriff auf einen bestimmten Bereich gewährt hat, sehen Sie sich das Feld scope in der Antwort des Zugriffstokens an. Die Zugriffsbereiche, die durch das access_token gewährt werden, ausgedrückt als Liste von durch Leerzeichen getrennten, case-sensitiven Strings.

Die folgende Beispielantwort für ein Zugriffstoken gibt an, dass der Nutzer Ihrer Anwendung Zugriff auf die schreibgeschützten Berechtigungen für Drive-Aktivitäten und Kalenderereignisse gewährt hat:

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

Google APIs aufrufen

PHP

So rufen Sie Google-APIs mit dem Zugriffstoken auf:

1. Wenn Sie ein Zugriffstoken auf ein neues Google\Client-Objekt anwenden müssen, z. B. wenn Sie das Zugriffstoken in einer Nutzersitzung gespeichert haben, verwenden Sie die Methode setAccessToken:

   $client->setAccessToken($access_token);

2. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Sie erstellen ein Dienstobjekt, indem Sie dem Konstruktor für die API, die Sie aufrufen möchten, ein autorisiertes Google\Client-Objekt bereitstellen. So rufen Sie beispielsweise die Drive API auf:

   $drive = new Google\Service\Drive($client);

3. Senden Sie Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle. So listen Sie beispielsweise die Dateien im Google Drive des authentifizierten Nutzers auf:

   $files = $drive->files->listFiles(array());

Python

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

1. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Sie erstellen ein Dienstobjekt, indem Sie die Methode build der Bibliothek googleapiclient.discovery mit dem Namen und der Version der API sowie den Nutzeranmeldedaten aufrufen: Beispiel für den Aufruf von Version 3 der Drive API:

   from googleapiclient.discovery import build
   
   drive = build('drive', 'v2', credentials=credentials)

2. Stellen Sie Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle. So listen Sie beispielsweise die Dateien im Google Drive des authentifizierten Nutzers auf:

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

Ruby

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

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

2. Legen Sie die Anmeldedaten für den Dienst fest:

   drive.authorization = credentials

3. Senden Sie Anfragen an den API-Dienst über die Schnittstelle des Dienstobjekts. So listen Sie beispielsweise die Dateien im Google Drive des authentifizierten Nutzers auf:

   files = drive.list_files

Alternativ kann die Autorisierung methodenspezifisch erfolgen, indem Sie den Parameter options für eine Methode angeben:

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

Node.js

Nachdem Sie ein Zugriffstoken erhalten und für das OAuth2-Objekt festgelegt haben, können Sie das Objekt zum Aufrufen von Google-APIs verwenden. 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. Im folgenden Code wird beispielsweise die Google Drive API verwendet, um Dateinamen im Drive des Nutzers aufzulisten.

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 das Token verwenden, um im Namen eines bestimmten Nutzerkontos Aufrufe an eine Google API zu senden, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Dazu müssen Sie das Zugriffstoken in eine Anfrage an die API einfügen. Verwenden Sie dazu entweder den Abfrageparameter access_token oder den HTTP-Header Authorization mit dem Wert Bearer. Wenn möglich, ist der HTTP-Header vorzuziehen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Ihre Aufrufe von Google APIs einzurichten, z. B. beim Aufrufen der Drive Files API.

Sie können alle Google APIs ausprobieren und ihre Bereiche im OAuth 2.0 Playground ansehen.

Beispiele für HTTP GET

Ein Aufruf des Endpunkts drive.files (Drive Files API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen Ihr eigenes Zugriffstoken angeben:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Query-String-Parameter 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. Hier ein Beispiel mit der HTTP-Header-Option (bevorzugt):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternativ können Sie auch die Option für den Abfragestringparameter verwenden:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Vollständiges Beispiel

Im folgenden Beispiel wird eine JSON-formatierte Liste der Dateien im Google Drive eines Nutzers ausgegeben, nachdem sich der Nutzer authentifiziert und der Anwendung die Einwilligung zum Zugriff auf die Drive-Metadaten des Nutzers erteilt hat.

PHP

So führen Sie das Beispiel aus:

1. Fügen Sie in der API Consoledie URL des lokalen Computers in die Liste der Weiterleitungs-URLs ein, z. B. http://localhost:8080.
2. Erstellen Sie ein neues Verzeichnis und wechseln Sie in dieses Verzeichnis. Beispiel:

   mkdir ~/php-oauth2-example
   cd ~/php-oauth2-example

3. Installieren Sie die Google API-Clientbibliothek für PHP mit Composer:

   composer require google/apiclient:^2.15.0

4. Erstellen Sie die Dateien index.php und oauth2callback.php mit folgendem Inhalt.
5. Führen Sie das Beispiel mit dem in PHP integrierten Testwebserver aus:

   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_secret.json');

// User granted permission as an access token is in the session.
if (isset($_SESSION['access_token']) && $_SESSION['access_token'])
{
  $client->setAccessToken($_SESSION['access_token']);
  
  // Check if user granted Drive permission
  if ($_SESSION['granted_scopes_dict']['Drive']) {
    echo "Drive feature is enabled.";
    echo "</br>";
    $drive = new Drive($client);
    $files = array();
    $response = $drive->files->listFiles(array());
    foreach ($response->files as $file) {
        echo "File: " . $file->name . " (" . $file->id . ")";
        echo "</br>";
    }
  } else {
    echo "Drive feature is NOT enabled.";
    echo "</br>";
  }

   // Check if user granted Calendar permission
  if ($_SESSION['granted_scopes_dict']['Calendar']) {
    echo "Calendar feature is enabled.";
    echo "</br>";
  } else {
    echo "Calendar feature is NOT enabled.";
    echo "</br>";
  }
}
else
{
  // Redirect users to outh2call.php which redirects users to Google OAuth 2.0
  $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();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfigFile('client_secret.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']);

// Required, to set the scope value, call the addScope function.
$client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);

// Enable incremental authorization. Recommended as a best practice.
$client->setIncludeGrantedScopes(true);

// Recommended, 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");

// Generate a URL for authorization as it doesn't contain code and error
if (!isset($_GET['code']) && !isset($_GET['error']))
{
  // Generate and set state value
  $state = bin2hex(random_bytes(16));
  $client->setState($state);
  $_SESSION['state'] = $state;

  // Generate a url that asks permissions.
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
}

// User authorized the request and authorization code is returned to exchange access and
// refresh tokens.
if (isset($_GET['code']))
{
  // Check the state value
  if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) {
    die('State mismatch. Possible CSRF attack.');
  }

  // Get access and refresh tokens (if access_type is offline)
  $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

  /** Save access and refresh token to the session variables.
    * ACTION ITEM: In a production app, you likely want to save the
    *              refresh token in a secure persistent storage instead. */
  $_SESSION['access_token'] = $token;
  $_SESSION['refresh_token'] = $client->getRefreshToken();
  
  // Space-separated string of granted scopes if it exists, otherwise null.
  $granted_scopes = $client->getOAuth2Service()->getGrantedScope();

  // Determine which scopes user granted and build a dictionary
  $granted_scopes_dict = [
    'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
    'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
  ];
  $_SESSION['granted_scopes_dict'] = $granted_scopes_dict;
  
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

// An error response e.g. error=access_denied
if (isset($_GET['error']))
{
  echo "Error: ". $_GET['error'];
}
?>

Python

In diesem Beispiel wird das Flask-Framework verwendet. Sie 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 fünf Links sehen:

• Drive API aufrufen:Dieser Link führt zu einer Seite, auf der versucht wird, eine Beispiel-API-Anfrage auszuführen, wenn Nutzer die Berechtigung erteilt haben. Bei Bedarf wird der Autorisierungsablauf gestartet. Bei Erfolg wird die API-Antwort auf der Seite angezeigt.
• Mock-Seite zum Aufrufen der Calendar API:Dieser Link verweist auf eine Mock-Seite, auf der versucht wird, eine Beispielanfrage für die Calendar API auszuführen, wenn Nutzer die Berechtigung erteilt haben. Bei Bedarf wird der Autorisierungsablauf gestartet. Bei Erfolg wird die API-Antwort auf der Seite angezeigt.
• Autorisierungsablauf direkt testen:Dieser Link führt zu einer Seite, auf der versucht wird, den Nutzer durch den Autorisierungsablauf zu leiten. Die App fordert die Berechtigung an, autorisierte API-Anfragen im Namen des Nutzers zu senden.
• Aktuelle Anmeldedaten widerrufen:Dieser Link führt zu einer Seite, auf der Berechtigungen widerrufen werden, die der Nutzer der Anwendung bereits gewährt hat.
• Flask-Sitzungsanmeldedaten löschen:Mit diesem Link werden Autorisierungsanmeldedaten gelöscht, die in der Flask-Sitzung gespeichert sind. So können Sie sehen, was passiert, wenn ein Nutzer, der Ihrer App bereits die Berechtigung erteilt hat, versucht, in einer neuen Sitzung eine API-Anfrage auszuführen. Außerdem können Sie damit die API-Antwort sehen, die Ihre App erhalten würde, wenn ein Nutzer die Ihrer App erteilten Berechtigungen widerrufen hätte und Ihre App trotzdem versucht, eine Anfrage mit einem widerrufenen Zugriffstoken zu autorisieren.

Hinweis:Wenn Sie diesen Code lokal ausführen möchten, müssen Sie die Anleitung im Abschnitt Voraussetzungen befolgt haben. Dazu gehört, dass Sie http://localhost:8080 als gültigen Redirect-URI für Ihre Anmeldedaten festlegen und die Datei client_secret.json für diese Anmeldedaten in Ihr Arbeitsverzeichnis herunterladen.

# -*- 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"

# The OAuth 2.0 access scope allows for access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly',
          'https://www.googleapis.com/auth/calendar.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('/drive')
def drive_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  features = flask.session['features']

  if features['drive']:
    # 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)
  else:
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
    return '<p>Drive feature is not enabled.</p>'

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

      features = flask.session['features']

      if features['calendar']:
        # User authorized Calendar read permission.
        # Calling the APIs, etc.
        return ('<p>User granted the Google Calendar read permission. '+
                'This sample code does not include code to call Calendar</p>')
      else:
        # User didn't authorize Calendar read permission.
        # Update UX and application accordingly
        return '<p>Calendar feature is not enabled.</p>'

@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
  
  credentials = credentials_to_dict(credentials)
  flask.session['credentials'] = credentials

  # Check which scopes user granted
  features = check_granted_scopes(credentials)
  flask.session['features'] = features
  return flask.redirect('/')
  

@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,
          'granted_scopes': credentials.granted_scopes}

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

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'

  # This disables the requested scopes and granted scopes check.
  # If users only grant partial request, the warning would not be thrown.
  os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE'] = '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 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/drive_v3'
require 'google/apis/calendar_v3'

require 'sinatra'

configure do
  enable :sessions

  # Required, call the from_file method to retrieve the client ID from a
  # client_secret.json file.
  set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json')

  # Required, scope value
  # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
  scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
           'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

  # Required, Authorizers require a storage instance to manage long term persistence of
  # access and refresh tokens.
  set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

  # Required, 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.
  set :callback_uri, '/oauth2callback'

  # 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.
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope,
                          settings.token_store, callback_uri: settings.callback_uri)
end

get '/' do
  # NOTE: Assumes the user is already authenticated to the app
  user_id = request.session['user_id']

  # Fetch stored credentials for the user from the given request session.
  # nil if none present
  credentials = settings.authorizer.get_credentials(user_id, request)

  if credentials.nil?
    # Generate a url that asks the user to authorize requested scope(s).
    # Then, redirect user to the url.
    redirect settings.authorizer.get_authorization_url(request: request)
  end
  
  # User authorized the request. Now, check which scopes were granted.
  if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
    # User authorized read-only Drive activity permission.
    # Example of using Google Drive API to list filenames in user's Drive.
    drive = Google::Apis::DriveV3::DriveService.new
    files = drive.list_files(options: { authorization: credentials })
    "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
  else
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
  end

  # Check if user authorized Calendar read permission.
  if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
    # User authorized Calendar read permission.
    # Calling the APIs, etc.
  else
    # User didn't authorize Calendar read permission.
    # Update UX and application accordingly
  end
end

# Receive the callback from Google's OAuth 2.0 server.
get '/oauth2callback' do
  # Handle the result of the oauth callback. Defers the exchange of the code by
  # temporarily stashing the results in the user's session.
  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url
end

Node.js

So führen Sie das Beispiel aus:

1. Fügen Sie in API Consoledie URL des lokalen Computers in die Liste der Weiterleitungs-URLs ein, z. B. http://localhost.
2. Achten Sie darauf, dass Sie die Maintenance LTS-, Active LTS- oder aktuelle Version von Node.js installiert haben.
3. Erstellen Sie ein neues Verzeichnis und wechseln Sie in dieses Verzeichnis. Beispiel:

   mkdir ~/nodejs-oauth2-example
   cd ~/nodejs-oauth2-example

4. Installieren Sie die Google API-Clientbibliothek für Node.js mit npm:

   npm install googleapis

5. Erstellen Sie die Dateien main.js mit folgendem Inhalt.
6. 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');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

/* 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 app = express();

  app.use(session({
    secret: 'your_secure_secret_key', // Replace with a strong secret
    resave: false,
    saveUninitialized: false,
  }));

  // Example on redirecting user to Google's OAuth 2.0 server.
  app.get('/', async (req, res) => {
    // Generate a secure random state value.
    const state = crypto.randomBytes(32).toString('hex');
    // Store state in the session
    req.session.state = state;

    // Generate a url that asks permissions for the Drive activity and Google Calendar 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,
      // Include the state parameter to reduce the risk of CSRF attacks.
      state: state
    });

    res.redirect(authorizationUrl);
  });

  // Receive the callback from Google's OAuth 2.0 server.
  app.get('/oauth2callback', async (req, res) => {
    // 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 if (q.state !== req.session.state) { //check state value
      console.log('State mismatch. Possible CSRF attack');
      res.end('State mismatch. Possible CSRF attack');
    } 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;
      
      // User authorized the request. Now, check which scopes were granted.
      if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly'))
      {
        // User authorized read-only Drive activity permission.
        // 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.');
          }
        });
      }
      else
      {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
      }

      // Check if user authorized Calendar read permission.
      if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
      {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
      }
      else
      {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
      }
    }
  });

  // Example on revoking a token
  app.get('/revoke', async (req, res) => {
    // 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();
  });


  const server = http.createServer(app);
  server.listen(8080);
}
main().catch(console.error);

HTTP/REST

In diesem Python-Beispiel wird das Flask-Framework und die Requests-Bibliothek verwendet, um den OAuth 2.0-Webablauf zu demonstrieren. Wir empfehlen, für diesen Ablauf die Google API-Clientbibliothek für Python zu verwenden. Im Beispiel auf dem Tab „Python“ wird die Clientbibliothek verwendet.

import json
import flask
import requests

app = flask.Flask(__name__)

# To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit
# https://console.cloud.google.com/apis/credentials.
CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app

# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.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.
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: 
    # User authorized the request. Now, check which scopes were granted.
    if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['scope']:
      # User authorized read-only Drive activity permission.
      # Example of using Google Drive API to list filenames in user's Drive.
      headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
      req_uri = 'https://www.googleapis.com/drive/v2/files'
      r = requests.get(req_uri, headers=headers).text
    else:
      # User didn't authorize read-only Drive activity permission.
      # Update UX and application accordingly
      r = 'User did not authorize Drive permission.'

    # Check if user authorized Calendar read permission.
    if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['scope']:
      # User authorized Calendar read permission.
      # Calling the APIs, etc.
      r += 'User authorized Calendar permission.'
    else:
      # User didn't authorize Calendar read permission.
      # Update UX and application accordingly
      r += 'User did not authorize Calendar permission.'

  return r

@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    state = str(uuid.uuid4())
    flask.session['state'] = state
    # Generate a url that asks permissions for the Drive activity
    # and Google Calendar scope. Then, redirect user to the url.
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID, REDIRECT_URI,
                                                                          SCOPE, state)
    return flask.redirect(auth_uri)
  else:
    if 'state' not in flask.request.args or flask.request.args['state'] != flask.session['state']:
      return 'State mismatch. Possible CSRF attack.', 400

    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'}

    # Exchange authorization code for access and refresh tokens (if access_type is offline)
    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 die folgenden Validierungsregeln auf Weiterleitungs-URIs an, um Entwicklern zu helfen, ihre Anwendungen zu schützen. Ihre Weiterleitungs-URIs müssen diesen Regeln entsprechen. Die Definitionen der unten erwähnten Begriffe „Domain“, „Host“, „Pfad“, „Abfrage“, „Schema“ und „Nutzerinfo“ finden Sie in RFC 3986, Abschnitt 3.

Validierungsregeln
Schema	Für Weiterleitungs-URIs muss das HTTPS-Schema verwendet werden, nicht HTTP. Localhost-URIs (einschließlich Localhost-IP-Adress-URIs) sind von dieser Regel ausgenommen.
Moderator:in	Hosts dürfen keine reinen IP-Adressen sein. Localhost-IP-Adressen sind von dieser Regel ausgenommen.
Domain	Host-TLDs (Top-Level-Domains) müssen zur Liste öffentlicher Suffixe gehören. Hostdomains dürfen nicht “googleusercontent.com” sein. Weiterleitungs-URIs dürfen keine URL-Kürzer-Domains (z.B. goo.gl) enthalten, es sei denn, die App ist Eigentümer der Domain. Wenn eine App, die eine Shortener-Domain besitzt, zu dieser Domain weiterleitet, muss der Weiterleitungs-URI entweder “/google-callback/” im Pfad enthalten oder mit “/google-callback” enden.
Userinfo	Weiterleitungs-URIs dürfen die Unterkomponente „userinfo“ nicht enthalten.
Pfad	Weiterleitungs-URIs dürfen keinen Path Traversal (auch als Directory Backtracking bezeichnet) enthalten, der durch “/..” oder “\..” oder deren URL-Codierung dargestellt wird.
Abfrage	Weiterleitungs-URIs dürfen keine offenen Weiterleitungen enthalten.
Fragment	Weiterleitungs-URIs dürfen keine Fragmentkomponente enthalten.
Zeichen	Weiterleitungs-URIs dürfen bestimmte Zeichen nicht enthalten, darunter: Platzhalterzeichen ('*') Nicht druckbare ASCII-Zeichen Ungültige Prozentcodierungen (alle Prozentcodierungen, die nicht dem URL-Codierungsformat eines Prozentzeichens gefolgt von zwei Hexadezimalziffern entsprechen) Nullzeichen (ein codiertes NULL-Zeichen, z.B. %00, %C0%80)

Inkrementelle Autorisierung

Im OAuth 2.0-Protokoll fordert Ihre App die Autorisierung für den Zugriff auf Ressourcen an, die durch Bereiche identifiziert werden. Es gilt als Best Practice für die Nutzerfreundlichkeit, die Autorisierung für Ressourcen zum Zeitpunkt des Bedarfs anzufordern. Um dies zu ermöglichen, unterstützt der Autorisierungsserver von Google die inkrementelle Autorisierung. Mit dieser Funktion können Sie Bereichsanfragen stellen, wenn sie benötigt werden. Wenn der Nutzer die Berechtigung für den neuen Bereich erteilt, wird ein Autorisierungscode zurückgegeben, der gegen ein Token mit allen Bereichen eingetauscht werden kann, die der Nutzer dem Projekt gewährt hat.

Eine App, mit der Nutzer beispielsweise Musiktracks anhören und Mixe erstellen können, benötigt bei der Anmeldung möglicherweise nur sehr wenige Ressourcen, vielleicht nur den Namen der Person, die sich anmeldet. Zum Speichern eines fertigen Mixes ist jedoch Zugriff auf Google Drive erforderlich. Die meisten Nutzer würden es als natürlich empfinden, wenn sie erst dann um Zugriff auf Google Drive gebeten werden, wenn die App ihn tatsächlich benötigt.

In diesem Fall kann die App bei der Anmeldung die Bereiche openid und profile anfordern, um die grundlegende Anmeldung durchzuführen, und dann später bei der ersten Anfrage zum Speichern eines Mixes den Bereich https://www.googleapis.com/auth/drive.file anfordern.

Wenn Sie die inkrementelle Autorisierung implementieren möchten, führen Sie den normalen Ablauf zum Anfordern eines Zugriffstokens aus. Achten Sie jedoch darauf, dass die Autorisierungsanfrage zuvor gewährte Bereiche enthält. So muss Ihre App nicht mehrere Zugriffstokens verwalten.

Für ein Zugriffstoken, das durch eine inkrementelle Autorisierung abgerufen wurde, gelten die folgenden Regeln:

• Mit dem Token kann auf Ressourcen zugegriffen werden, die einem der Bereiche entsprechen, die in der neuen, kombinierten Autorisierung enthalten sind.
• Wenn Sie das Aktualisierungstoken für die kombinierte Autorisierung verwenden, um ein Zugriffstoken zu erhalten, repräsentiert das Zugriffstoken die kombinierte Autorisierung und kann für alle scope-Werte verwendet werden, die in der Antwort enthalten sind.
• 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 über einen mobilen Client derselben Anwendung Zugriff auf einen anderen Bereich gewährt, umfasst die kombinierte Autorisierung beide Bereiche.
• Wenn Sie ein Token widerrufen, das eine kombinierte Autorisierung darstellt, wird der Zugriff auf alle Bereiche dieser Autorisierung im Namen des zugehörigen Nutzers gleichzeitig widerrufen.

Achtung:Wenn Sie sich dafür entscheiden, gewährte Bereiche einzubeziehen, werden Ihrer Autorisierungsanfrage automatisch Bereiche hinzugefügt, die der Nutzer zuvor gewährt hat. Eine Warn- oder Fehlerseite wird möglicherweise angezeigt, wenn Ihre App derzeit nicht für die Anfrage aller Bereiche genehmigt ist, die in der Antwort zurückgegeben werden können. Weitere Informationen finden Sie unter Nicht bestätigte Apps.

In den sprachspezifischen Codebeispielen in Schritt 1: Autorisierungsparameter festlegen und der HTTP/REST-Beispiel-Weiterleitungs-URL in Schritt 2: Zum OAuth 2.0-Server von Google weiterleiten wird die inkrementelle Autorisierung verwendet. In den folgenden Codebeispielen sehen Sie 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 wahrscheinlich, dass include_granted_scopes nicht das einzige Keyword-Argument ist, das Sie festlegen, wie im folgenden Beispiel 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.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
  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 den Nutzer um eine 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, wird das Zugriffstoken vom Clientobjekt nach Bedarf aktualisiert, sofern Sie dieses Objekt für den Offlinezugriff konfiguriert haben.
• Wenn Sie keine Clientbibliothek verwenden, müssen Sie den HTTP-Anfrageparameter access_type auf offline setzen, wenn Sie den Nutzer zum OAuth 2.0-Server von Google weiterleiten. In diesem Fall gibt der Autorisierungsserver von Google ein Aktualisierungstoken zurück, wenn Sie einen Autorisierungscode gegen ein Zugriffstoken eintauschen. Wenn das Zugriffstoken dann abläuft (oder zu einem beliebigen anderen Zeitpunkt), können Sie ein Aktualisierungstoken verwenden, um ein neues Zugriffstoken zu erhalten.

Das Anfordern des Offlinezugriffs ist eine Voraussetzung für jede Anwendung, die auf eine Google API zugreifen muss, wenn der Nutzer nicht vorhanden ist. Eine App, die beispielsweise Sicherungsdienste ausführt oder Aktionen zu bestimmten Zeiten ausführt, muss ihr Zugriffstoken aktualisieren können, wenn der Nutzer nicht anwesend ist. Der Standardstil für den Zugriff heißt online.

Serverseitige Webanwendungen, installierte Anwendungen und Geräte erhalten alle Aktualisierungstokens während des Autorisierungsprozesses. Aktualisierungstokens werden in clientseitigen (JavaScript-)Webanwendungen in der Regel nicht 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 den 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 zu bitten. Es ist sehr wahrscheinlich, dass access_type nicht das einzige Keyword-Argument ist, das Sie festlegen, wie im folgenden Beispiel 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 den 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 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 den 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 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 den 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 das aktuelle Zugriffstoken bald abläuft. Eine einfache Möglichkeit, immer die neuesten Tokens zu speichern, ist die Verwendung des Ereignisses „tokens“:

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 Token-Ereignis tritt nur bei der ersten Autorisierung auf. Sie müssen access_type auf offline festlegen, wenn Sie die Methode generateAuthUrl aufrufen, um das Aktualisierungstoken zu erhalten. Wenn Sie Ihrer App bereits die erforderlichen Berechtigungen erteilt 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 die refresh_token zu einem späteren Zeitpunkt 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 API-Aufruf automatisch abgerufen und aktualisiert.

HTTP/REST

Wenn Sie ein Zugriffstoken aktualisieren möchten, sendet Ihre Anwendung eine HTTPS-Anfrage POST an den Autorisierungsserver von Google (https://oauth2.googleapis.com/token), die die folgenden Parameter enthält:

Felder
client_id	Die Client-ID, die von API Consoleabgerufen wurde.
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 gesetzt werden.
refresh_token	Das Aktualisierungstoken, das beim Austausch des Autorisierungscodes zurückgegeben wird.

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 mit einem neuen Zugriffstoken zurück. Das folgende Snippet zeigt eine Beispielantwort:

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

Beachten Sie, dass die Anzahl der ausgegebenen Aktualisierungstokens begrenzt ist: ein Limit pro Client-/Nutzerkombination und ein weiteres pro Nutzer für alle Clients. Aktualisierungstokens sollten langfristig gespeichert und so lange verwendet werden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann es sein, dass diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token widerrufen

In einigen Fällen möchten Nutzer den Zugriff auf eine Anwendung widerrufen. Ein Nutzer kann den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Hilfeartikel Websites und Apps von Drittanbietern mit Zugriff auf Ihr Konto im Abschnitt Zugriff auf Websites oder Apps entfernen.

Eine Anwendung kann den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer ein Abo kündigt, eine Anwendung entfernt oder sich die von einer App benötigten API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage umfassen, um sicherzustellen, dass die zuvor der Anwendung gewährten Berechtigungen entfernt werden.

PHP

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

$client->revokeToken();

Python

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

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

Ruby

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

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

Das Token kann ein Zugriffs- oder ein Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken gibt, wird auch das Aktualisierungstoken widerrufen.

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

Node.js

Wenn Sie ein Token programmatisch widerrufen möchten, senden 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 ein entsprechendes Aktualisierungstoken gibt, wird auch das Aktualisierungstoken widerrufen.

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

HTTP/REST

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

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

Das Token kann ein Zugriffs- oder ein Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken gibt, wird auch das Aktualisierungstoken widerrufen.

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

Hinweis:Nach einer erfolgreichen Antwort auf den Widerruf kann es einige Zeit dauern, bis der Widerruf vollständig wirksam wird.

Zeitbasierter Zugriff

Mit dem zeitbasierten Zugriff kann ein Nutzer Ihrer App für einen begrenzten Zeitraum Zugriff auf seine Daten gewähren, um eine Aktion auszuführen. Der zeitbasierte Zugriff ist in ausgewählten Google-Produkten während des Einwilligungsablaufs verfügbar. Nutzer haben so die Möglichkeit, den Zugriff für einen begrenzten Zeitraum zu gewähren. Ein Beispiel ist die Data Portability API, die eine einmalige Datenübertragung ermöglicht.

Wenn ein Nutzer Ihrer Anwendung zeitbasierten Zugriff gewährt, läuft das Aktualisierungstoken nach dem angegebenen Zeitraum ab. Unter bestimmten Umständen können Aktualisierungstokens auch früher ungültig werden. Weitere Informationen Das Feld refresh_token_expires_in, das in der Antwort des Autorisierungscode-Austauschs zurückgegeben wird, gibt in solchen Fällen die verbleibende Zeit bis zum Ablauf des Aktualisierungstokens an.

Produktübergreifenden Kontoschutz implementieren

Ein zusätzlicher Schritt, den Sie unternehmen sollten, um die Konten Ihrer Nutzer zu schützen, ist die Implementierung von Cross-Account Protection mithilfe des Cross-Account Protection Service von Google. Mit diesem Dienst können Sie Benachrichtigungen zu Sicherheitsereignissen abonnieren, die Ihre Anwendung über wichtige Änderungen am Nutzerkonto informieren. Anhand dieser Informationen können Sie dann Maßnahmen ergreifen, je nachdem, wie Sie auf Ereignisse reagieren möchten.

Hier einige Beispiele für die Ereignistypen, die vom Google Cross-Account Protection Service an Ihre App gesendet werden:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Weitere Informationen zur Implementierung des produktübergreifenden Kontoschutzes und die vollständige Liste der verfügbaren Ereignisse finden Sie auf der Seite Nutzerkonten mit dem produktübergreifenden Kontoschutz schützen .