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 die YouTube Data API zu implementieren.

OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise kann eine Anwendung über OAuth 2.0 die Berechtigung erhalten, Videos in den YouTube-Kanal eines Nutzers hochzuladen.

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

Webserveranwendungen verwenden häufig auch Dienstkonten zum Autorisieren von API-Anfragen, insbesondere wenn Cloud APIs für den Zugriff auf projektbasierte Daten statt auf nutzerspezifische Daten aufgerufen werden. Webserveranwendungen können Dienstkonten in Verbindung mit der Nutzerautorisierung verwenden. Die YouTube Data API unterstützt den Dienstkontovorgang nur für YouTube-Rechteinhaber, die mehrere YouTube-Kanäle haben und verwalten. Insbesondere können Rechteinhaber Dienstkonten verwenden, um API-Methoden aufzurufen, die den Anfrageparameter onBehalfOfContentOwner unterstützen.

Clientbibliotheken

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

Wenn Sie eine Google API-Clientbibliothek verwenden, um den OAuth 2.0-Vorgang Ihrer Anwendung zu verarbeiten, führt die Clientbibliothek viele Aktionen aus, die die Anwendung sonst selbst verarbeiten müsste. Beispielsweise wird festgelegt, wann die Anwendung gespeicherte Zugriffstokens verwenden oder aktualisieren kann und wann die Anwendung die Einwilligung noch einmal einholen muss. Die Clientbibliothek generiert außerdem korrekte Weiterleitungs-URLs und hilft bei der Implementierung von Weiterleitungs-Handlern, die Autorisierungscodes gegen Zugriffstokens austauschen.

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

Voraussetzungen

Die APIs für Ihr Projekt aktivieren

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

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. Auf der Seite Bibliothek kannst du die YouTube Data API suchen und aktivieren. Suchen Sie nach anderen APIs, die Ihre Anwendung verwenden wird, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, müssen Anmeldedaten zur Identifizierung gegenüber dem OAuth 2.0-Server von Google haben. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für das Projekt aktiviert haben.

  1. Go to the Credentials page.
  2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
  3. Wählen Sie den Anwendungstyp Webanwendung aus.
  4. Füllen Sie das Formular aus und klicken Sie auf Erstellen. 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 sich auf den lokalen Computer beziehen, z. B. http://localhost:8080. In allen Beispielen in diesem Dokument wird daher http://localhost:8080 als Weiterleitungs-URI verwendet.

    Wir empfehlen, die Authentifizierungsendpunkte Ihrer Anwendung so zu entwerfen, dass Ihre Anwendung keine Autorisierungscodes für andere Ressourcen auf der Seite bereitstellt.

Nachdem Sie die Anmeldedaten erstellt haben, laden Sie die Datei client_secret.json aus dem API Consoleherunter. Speichern Sie die Datei an einem sicheren Ort, auf den nur Ihre Anwendung zugreifen kann.

Zugriffsbereiche identifizieren

Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann es eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit des Einholens der Nutzereinwilligung geben.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, für die Ihre App eine Zugriffsberechtigung benötigt.

Außerdem empfiehlt es sich, dass Ihre Anwendung den Zugriff auf Autorisierungsbereiche über eine inkrementelle Autorisierung anfordert. Dabei fordert Ihre Anwendung den Zugriff auf Nutzerdaten im Kontext an. So können Nutzer leichter nachvollziehen, warum Ihre Anwendung den angeforderten Zugriff benötigt.

Die YouTube Data API Version 3 nutzt die folgenden Bereiche:

Sucher
https://www.googleapis.com/auth/youtubeYouTube-Konto verwalten
https://www.googleapis.com/auth/youtube.channel-memberships.creatorEine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen
https://www.googleapis.com/auth/youtube.force-sslIhre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen
https://www.googleapis.com/auth/youtube.readonlyYouTube-Konto abrufen
https://www.googleapis.com/auth/youtube.uploadYouTube-Videos verwalten
https://www.googleapis.com/auth/youtubepartnerIhre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten
https://www.googleapis.com/auth/youtubepartner-channel-auditPrivate Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind

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

Sprachspezifische Anforderungen

Zum Ausführen der Codebeispiele in diesem Dokument benötigen Sie ein Google-Konto, eine Internetverbindung und einen Webbrowser. Wenn Sie eine der API-Clientbibliotheken verwenden, beachten Sie auch die sprachspezifischen Anforderungen unten.

PHP

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

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

    composer require google/apiclient:^2.10

Python

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

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

Ruby

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

  • Ruby 2.6 oder höher
  • Die Google-Authentifizierungsbibliothek für Ruby:

    gem install googleauth
  • Das Sinatra-Framework für Ruby-Webanwendungen

    gem install sinatra

Node.js

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

  • Der Wartungs-LTS, der aktive LTS oder der aktuelle Release von Node.js.
  • Der Node.js-Client für Google APIs:

    npm install googleapis

HTTP/REST

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

OAuth 2.0-Zugriffstokens abrufen

In den folgenden Schritten wird gezeigt, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung eines Nutzers einzuholen, im Namen des Nutzers eine API-Anfrage auszuführen. Ihre Anwendung muss über diese Einwilligung verfügen, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.

In der folgenden Liste werden diese Schritte kurz zusammengefasst:

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

Schritt 1: Autorisierungsparameter festlegen

Im ersten Schritt erstellen Sie die Autorisierungsanfrage. Mit 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, generieren Sie eine URL und legen die Parameter für diese URL fest.

In den folgenden Registerkarten werden die unterstützten Autorisierungsparameter für Webserveranwendungen definiert. Die sprachspezifischen Beispiele zeigen auch, wie mit einer Clientbibliothek oder Autorisierungsbibliothek ein Objekt konfiguriert wird, das diese Parameter festlegt.

PHP

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

Dieses Objekt identifiziert Ihre Anwendung anhand von Informationen aus der Datei client_secret.json. Weitere Informationen zu dieser Datei finden Sie unter Anmeldedaten für die Autorisierung erstellen. Das Objekt identifiziert auch die Bereiche, für die Ihre Anwendung eine Zugriffsberechtigung anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, der die Antwort des OAuth 2.0-Servers von Google verarbeitet. Abschließend legt der Code die optionalen Parameter access_type und include_granted_scopes fest.

Mit diesem Code wird beispielsweise der Offlinezugriff zur Verwaltung des YouTube-Kontos eines Nutzers angefordert:

$client = new Google\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_YOUTUBE::YOUTUBE_FORCE_SSL);

// 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('hint@example.com');

// 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 zum Erstellen der Autorisierungsanfrage verwendet.

Mit dem Code wird ein Flow-Objekt erstellt, das Ihre Anwendung anhand von Informationen aus der Datei client_secret.json identifiziert, die Sie nach dem Erstellen der Anmeldedaten für die Autorisierung heruntergeladen haben. Dieses Objekt identifiziert auch die Bereiche, für die Ihre Anwendung eine Zugriffsberechtigung anfordert, sowie die URL zum Authentifizierungsendpunkt Ihrer Anwendung, der die Antwort des OAuth 2.0-Servers von Google verarbeitet. Abschließend legt der Code die optionalen Parameter access_type und include_granted_scopes fest.

Mit diesem Code wird beispielsweise der Offlinezugriff zur Verwaltung des YouTube-Kontos 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/youtube.force-ssl'])

# 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',
    # Recommended, state value can increase your assurance that an incoming connection is the result
    # of an authentication request.
    state=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.
    login_hint='hint@example.com',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

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

Mit diesem Code wird beispielsweise der Offlinezugriff zur Verwaltung des YouTube-Kontos eines Nutzers angefordert:

require 'google/apis/youtube_v3'
require "googleauth"
require 'googleauth/stores/redis_token_store'

client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')
scope = 'https://www.googleapis.com/auth/youtube.force-ssl'
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope, token_store, '/oauth2callback')

Ihre Anwendung verwendet das Clientobjekt, 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 auf eine Einwilligungsseite weiter. So erstellen Sie die URL einer Einwilligungsseite:

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

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

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

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

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

HTTP/REST

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

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

Parameter
client_id Erforderlich

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

redirect_uri Erforderlich

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

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

response_type Erforderlich

Bestimmt, 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 angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen könnte. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.

Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig ermöglichen sie Nutzern, den Umfang des Zugriffs auf Ihre Anwendung zu steuern. Daher besteht ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, dass die Nutzereinwilligung eingeholt wird.

Die YouTube Data API Version 3 nutzt die folgenden Bereiche:

Sucher
https://www.googleapis.com/auth/youtubeYouTube-Konto verwalten
https://www.googleapis.com/auth/youtube.channel-memberships.creatorEine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen
https://www.googleapis.com/auth/youtube.force-sslIhre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen
https://www.googleapis.com/auth/youtube.readonlyYouTube-Konto abrufen
https://www.googleapis.com/auth/youtube.uploadYouTube-Videos verwalten
https://www.googleapis.com/auth/youtubepartnerIhre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten
https://www.googleapis.com/auth/youtubepartner-channel-auditPrivate Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind

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.

Wir empfehlen, dass Ihre Anwendung den Zugriff auf Autorisierungsbereiche nach Möglichkeit im entsprechenden Kontext anfordert. Wenn Sie über eine inkrementelle Autorisierung Zugriff auf Nutzerdaten im Kontext anfordern, können Nutzer leichter nachvollziehen, warum Ihre Anwendung den angeforderten Zugriff benötigt.

access_type Empfohlen

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

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

state Empfohlen

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

Sie können diesen Parameter für verschiedene Zwecke verwenden, z. B. um den Nutzer zur richtigen Ressource in Ihrer Anwendung zu leiten, Nonces zu senden und websiteübergreifende Anfragefälschungen zu verhindern. Da die redirect_uri erraten werden kann, lässt sich mit einem state-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Cookies oder eines anderen Werts codieren, der den Status des Clients erfasst, können Sie die Antwort validieren, um zusätzlich sicherzustellen, dass die Anfrage und die Antwort vom selben Browser stammen. So ist sie vor Angriffen wie websiteübergreifender Anfragefälschung geschützt. In der Dokumentation zu OpenID Connect finden Sie ein Beispiel zum Erstellen und Bestätigen eines state-Tokens.

include_granted_scopes Optional

Ermöglicht Anwendungen die Verwendung der inkrementellen Autorisierung, um den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf true setzen und die Autorisierungsanfrage genehmigt wird, deckt das neue Zugriffstoken auch alle Bereiche ab, für die der Nutzer zuvor den Anwendungszugriff gewährt hat. Beispiele finden Sie im Abschnitt Inkrementelle Autorisierung.

login_hint Optional

Wenn Ihre Anwendung weiß, welcher Nutzer sich authentifizieren möchte, kann sie mit diesem Parameter dem Google-Authentifizierungsserver einen Hinweis geben. Der Server verwendet den Hinweis, um den Anmeldevorgang zu vereinfachen, indem er das E-Mail-Feld im Anmeldeformular vorab ausfüllt oder die entsprechende Mehrfachanmeldungssitzung auswählt.

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

prompt Optional

Eine Liste von Aufforderungen, die dem Nutzer angezeigt werden sollen, wobei die Groß- und Kleinschreibung durch Leerzeichen voneinander getrennt ist. Wenn Sie diesen Parameter nicht angeben, wird der Nutzer nur dann aufgefordert, wenn Ihr Projekt zum ersten Mal Zugriff anfordert. Weitere Informationen finden Sie unter Aufforderung zur erneuten Einwilligung.

Folgende Werte sind möglich:

none Blenden Sie keine Authentifizierungs- oder Zustimmungsbildschirme ein. Darf nicht mit anderen Werten angegeben werden.
consent Fordern Sie den Nutzer zur Einwilligung auf.
select_account Nutzer auffordern, ein Konto auszuwählen

Schritt 2: Zum OAuth 2.0-Server von Google weiterleiten

Leite den Nutzer zum OAuth 2.0-Server von Google weiter, um den Authentifizierungs- und Autorisierungsprozess zu starten. In der Regel tritt dies auf, wenn Ihre Anwendung zuerst auf die Daten des Nutzers zugreifen muss. Bei einer inkrementellen Autorisierung wird dieser Schritt auch ausgeführt, wenn Ihre Anwendung zuerst auf zusätzliche Ressourcen zugreifen muss, für die sie noch keine Zugriffsberechtigung hat.

PHP

  1. Generiere eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:
    $auth_url = $client->createAuthUrl();
  2. Leite 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 mithilfe des gcloud-Frameworks zur Autorisierung an die Autorisierungs-URL weiterleiten:

return flask.redirect(authorization_url)

Ruby

  1. Generiere eine URL, um Zugriff vom OAuth 2.0-Server von Google anzufordern:
    auth_uri = authorizer.get_authorization_url(login_hint: user_id, request: request)
  2. Leiten Sie den Nutzer zu auth_uri weiter.

Node.js

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

HTTP/REST

Sample redirect to Google's authorization server

The sample URL below requests offline access (access_type=offline) to a scope that permits access to view the user's YouTube account. It uses incremental authorization to ensure that the new access token covers any scopes to which the user previously granted the application access. The URL also sets values for the required redirect_uri, response_type, and client_id parameters as well as for the state parameter. The URL contains line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 access_type=offline&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=code&
 client_id=client_id

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

Der OAuth 2.0-Server von Google authentifiziert den Nutzer und erhält die Einwilligung des Nutzers für den Zugriff Ihrer Anwendung auf die angeforderten Bereiche. Die Antwort wird unter Verwendung der von Ihnen angegebenen Weiterleitungs-URL an Ihre Anwendung zurückgesendet.

Schritt 3: Google fordert den Nutzer zur Einwilligung auf

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewährt. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, für die die Berechtigung für den Zugriff mit den Autorisierungsanmeldedaten des Nutzers angefordert wird. Außerdem wird eine Zusammenfassung der Zugriffsbereiche angezeigt, die gewährt werden sollen. Der Nutzer kann dann zustimmen, Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.

Deine Anwendung muss in dieser Phase nichts tun, da sie auf die Antwort vom OAuth 2.0-Server von Google wartet, die angibt, ob Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.

Fehler

Bei Anfragen an den OAuth 2.0-Autorisierungsendpunkt von Google werden möglicherweise nutzerseitige Fehlermeldungen anstelle der erwarteten Authentifizierungs- und Autorisierungsabläufe angezeigt. Häufige Fehlercodes und Lösungsvorschläge sind unten aufgeführt.

admin_policy_enforced

Das Google-Konto kann einen oder mehrere angeforderte Bereiche aufgrund der Richtlinien des Google Workspace-Administrators nicht autorisieren. Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten steuern finden Sie weitere Informationen dazu, wie ein Administrator den Zugriff auf alle oder vertrauliche und eingeschränkte Bereiche einschränken kann, bis der OAuth-Client-ID explizit Zugriff gewährt wird.

disallowed_useragent

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

Android

Android-Entwicklern kann diese Fehlermeldung beim Öffnen von Autorisierungsanfragen in android.webkit.WebView angezeigt werden. Entwickler sollten stattdessen Android-Bibliotheken wie Google Log-in für Android oder AppAuth for Android der OpenID Foundation verwenden.

Dieser Fehler kann bei Webentwicklern auftreten, wenn eine Android-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten zulassen, dass allgemeine Links im standardmäßigen Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl Handler für Android-App-Links oder die Standard-Browser-App. Die Bibliothek Benutzerdefinierte Tabs für Android wird ebenfalls unterstützt.

iOS

iOS- und macOS-Entwickler können auf diesen Fehler stoßen, wenn sie Autorisierungsanfragen in WKWebView öffnen. Entwickler sollten stattdessen iOS-Bibliotheken wie Google Log-in für iOS oder AppAuth for iOS der OpenID Foundation verwenden.

Bei Webentwicklern kann dieser Fehler auftreten, wenn eine iOS- oder macOS-App einen allgemeinen Weblink in einem eingebetteten User-Agent öffnet und ein Nutzer von deiner Website zum OAuth 2.0-Autorisierungsendpunkt von Google navigiert. Entwickler sollten zulassen, dass allgemeine Links im standardmäßigen Link-Handler des Betriebssystems geöffnet werden. Dazu gehören sowohl universelle Links-Handler als auch die Standard-Browser-App. Auch die Bibliothek SFSafariViewController ist eine unterstützte Option.

org_internal

Die OAuth-Client-ID in der Anfrage ist Teil eines Projekts, das den Zugriff auf Google-Konten in einer bestimmten Google Cloud-Organisation einschränkt. Weitere Informationen zu dieser Konfigurationsoption finden Sie im Hilfeartikel „OAuth-Zustimmungsbildschirm einrichten“ im Abschnitt Nutzertyp.

invalid_client

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

invalid_grant

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

redirect_uri_mismatch

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

Der redirect_uri-Parameter kann sich auf den OAuth-Out-of-Band-Vorgang (OOB) beziehen, der eingestellt wurde und nicht mehr unterstützt wird. Informationen zum Aktualisieren deiner Integration findest du in der Migrationsanleitung.

invalid_request

Bei Ihrer Anfrage ist ein Fehler aufgetreten. Dafür kann es mehrere Gründe geben:

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

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Der OAuth 2.0-Server antwortet über die in der Anfrage angegebene URL auf die Zugriffsanfrage deiner Anwendung.

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 an den Webserver zurückgegebene Autorisierungscode oder die an den Webserver zurückgegebene Fehlermeldung wird im Abfragestring wie unten dargestellt angezeigt:

Eine Fehlerantwort:

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

Eine Antwort mit einem Autorisierungscode:

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

Beispiel für eine OAuth 2.0-Serverantwort

Sie können diesen Ablauf testen, indem Sie auf die folgende Beispiel-URL klicken, die Lesezugriff zum Ansehen von Metadaten für Dateien in Google Drive anfordert:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 access_type=offline&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=code&
 client_id=client_id

Nach Abschluss des OAuth 2.0-Vorgangs sollten Sie zu http://localhost/oauth2callback weitergeleitet werden. Wenn Ihr lokaler Computer keine Datei unter dieser Adresse bereitstellt, wird wahrscheinlich der Fehler 404 NOT FOUND zurückgegeben. Der nächste Schritt enthält weitere Details 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 empfangen hat, kann er den Autorisierungscode gegen ein Zugriffstoken austauschen.

PHP

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

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

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

$access_token = $client->getAccessToken();

Python

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

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

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

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

Ruby

Prüfen Sie auf der Callback-Seite die googleauth-Bibliothek, um die Antwort des Autorisierungsservers zu prüfen. Verwende die Methode authorizer.handle_auth_callback_deferred, um den Autorisierungscode zu speichern und zu der URL zurückzukehren, die die Autorisierung ursprünglich angefordert hat. Dadurch wird der Codeaustausch aufgeschoben, da die Ergebnisse vorübergehend in der Nutzersitzung gespeichert werden.

  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url

Node.js

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

const url = require('url');

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

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

HTTP/REST

Wenn Sie einen Autorisierungscode gegen ein Zugriffstoken austauschen möchten, rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen Sie die folgenden Parameter fest:

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

Das folgende Snippet zeigt eine Beispielanfrage:

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

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

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

Die Antwort umfasst die folgenden Felder:

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

Das folgende Snippet zeigt eine Beispielantwort:

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

Fehler

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

invalid_grant

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

Google APIs aufrufen

PHP

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

  1. Wenn Sie ein Zugriffstoken auf ein neues Google\Client-Objekt anwenden müssen, z. B. wenn Sie das Zugriffstoken in einer Nutzersitzung gespeichert haben, verwenden Sie die Methode setAccessToken:
    $client->setAccessToken($access_token);
  2. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Zum Erstellen eines Dienstobjekts müssen Sie dem Konstruktor der API, die Sie aufrufen möchten, ein autorisiertes Google\Client-Objekt zur Verfügung stellen. So rufen Sie beispielsweise die YouTube Data API auf:
    $youtube = new Google_Service_YouTube($client);
  3. Anfragen an den API-Dienst stellen Sie über die vom Dienstobjekt bereitgestellte Schnittstelle. So rufen Sie beispielsweise Daten zum YouTube-Kanal des autorisierten Nutzers ab:
    $channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));

Python

Nachdem Sie ein Zugriffstoken erhalten haben, kann Ihre Anwendung dieses Token verwenden, um API-Anfragen im Namen eines bestimmten Nutzerkontos oder Dienstkontos zu autorisieren. Verwenden Sie die nutzerspezifischen Anmeldedaten für die Autorisierung, um ein Dienstobjekt für die aufzurufende API zu erstellen, und nutzen Sie dieses Objekt dann für autorisierte API-Anfragen.

  1. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. Zum Erstellen eines Dienstobjekts rufen Sie die build-Methode der googleapiclient.discovery-Bibliothek mit dem Namen und der Version der API sowie den Nutzeranmeldedaten auf: So rufen Sie beispielsweise Version 3 der YouTube Data API auf:
    from googleapiclient.discovery import build
    
    youtube = build('youtube', 'v3', credentials=credentials)
  2. Anfragen an den API-Dienst stellen Sie über die vom Dienstobjekt bereitgestellte Schnittstelle. So rufen Sie beispielsweise Daten zum YouTube-Kanal des autorisierten Nutzers ab:
    channel = youtube.channels().list(mine=True, part='snippet').execute()

Ruby

Nachdem Sie ein Zugriffstoken erhalten haben, kann Ihre Anwendung dieses Token verwenden, um API-Anfragen im Namen eines bestimmten Nutzerkontos oder Dienstkontos zu senden. Verwenden Sie die nutzerspezifischen Anmeldedaten für die Autorisierung, um ein Dienstobjekt für die aufzurufende API zu erstellen, und nutzen Sie dieses Objekt dann für autorisierte API-Anfragen.

  1. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten. So rufen Sie beispielsweise Version 3 der YouTube Data API auf:
    youtube = Google::Apis::YoutubeV3::YouTubeService.new
  2. Legen Sie die Anmeldedaten für den Dienst fest:
    youtube.authorization = credentials
  3. Senden Sie Anfragen an den API-Dienst über die vom Dienstobjekt bereitgestellte Schnittstelle. So rufen Sie beispielsweise Daten zum YouTube-Kanal des autorisierten Nutzers ab:
    channel = youtube.list_channels(part, :mine => mine)

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

channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })

Node.js

Nachdem du ein Zugriffstoken abgerufen und auf das OAuth2-Objekt festgelegt hast, kannst du mit dem Objekt Google APIs aufrufen. Ihre Anwendung kann dieses Token verwenden, um API-Anfragen im Namen eines bestimmten Nutzerkontos oder Dienstkontos zu autorisieren. Erstellen Sie ein Dienstobjekt für die API, die Sie aufrufen möchten.

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

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

HTTP/REST

Nachdem Ihre Anwendung ein Zugriffstoken abgerufen hat, können Sie mit dem Token im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein. Dazu geben Sie entweder den Abfrageparameter access_token oder den Bearer-Wert eines Authorization-HTTP-Headers an. Wenn möglich, sollte der HTTP-Header verwendet werden, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du deine Aufrufe von Google APIs mithilfe einer Clientbibliothek einrichten, z. B. beim Aufruf der YouTube Data API.

Die YouTube Data API unterstützt Dienstkonten nur für YouTube-Rechteinhaber, die mehrere YouTube-Kanäle wie Musiklabels und Filmstudios besitzen und verwalten.

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

HTTP GET-Beispiele

Ein Aufruf des Endpunkts youtube.channels (die YouTube Data API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen. Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Beispiele für curl

Sie können diese Befehle mit der curl-Befehlszeilenanwendung testen. Hier ein Beispiel, in dem die HTTP-Header-Option (bevorzugt) verwendet wird:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Alternativ können Sie die Parameteroption für den Abfragestring verwenden:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Vollständiges Beispiel

Im folgenden Beispiel wird ein Objekt im JSON-Format mit Informationen zum YouTube-Kanal eines Nutzers gedruckt, nachdem der Nutzer die Anwendung authentifiziert und autorisiert hat, das YouTube-Konto des Nutzers zu verwalten.

PHP

So führen Sie das Beispiel aus:

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

index.php

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

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $youtube = new Google_Service_YouTube($client);
  $channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));
  echo json_encode($channel);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

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

session_start();

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

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

Python

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

  • API-Anfrage testen:Dieser Link verweist auf eine Seite, auf der versucht wird, eine Beispiel-API-Anfrage auszuführen. Falls erforderlich, wird der Autorisierungsvorgang gestartet. Bei Erfolg wird auf der Seite die API-Antwort angezeigt.
  • Autorisierungsablauf direkt testen:Dieser Link verweist auf eine Seite, auf der versucht wird, den Nutzer durch den Autorisierungsablauf weiterzuleiten. Die App fordert die Berechtigung zum Senden autorisierter API-Anfragen im Namen des Nutzers an.
  • Aktuelle Anmeldedaten widerrufen:Dieser Link führt zu einer Seite, auf der Berechtigungen widerrufen werden, die der Nutzer der Anwendung bereits erteilt hat.
  • Löschen der Anmeldedaten für eine gcloud-Sitzung:Über diesen Link werden die in der Bot-Sitzung gespeicherten Anmeldedaten gelöscht. So können Sie sehen, was passieren würde, wenn ein Nutzer, der Ihrer App bereits die Berechtigung erteilt hat, versucht, eine API-Anfrage in einer neuen Sitzung auszuführen. Außerdem können Sie die API-Antwort sehen, die Ihre App erhält, wenn ein Nutzer die Berechtigungen für Ihre App widerrufen hätte, und die App immer noch versucht, eine Anfrage mit einem widerrufenen Zugriffstoken zu autorisieren.
# -*- coding: utf-8 -*-

import os
import flask
import requests

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

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

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

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


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


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

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

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

  channel = youtube.channels().list(mine=True, part='snippet').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(**channel)


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

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

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

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

  return flask.redirect(authorization_url)


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

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

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

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

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


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

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

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

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


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


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

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


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

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

Ruby

In diesem Beispiel wird das Sinatra-Framework verwendet.

require 'google/apis/youtube_v3'
require 'sinatra'
require 'googleauth'
require 'googleauth/stores/redis_token_store'

configure do
  enable :sessions

  set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json')
  set :scope, Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY
  set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope, settings.token_store, '/oauth2callback')
end

get '/' do
  user_id = settings.client_id.id
  credentials = settings.authorizer.get_credentials(user_id, request)
  if credentials.nil?
    redirect settings.authorizer.get_authorization_url(login_hint: user_id, request: request)
  end
  youtube = Google::Apis::YoutubeV3::YouTubeService.new
  channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })
  
  "<pre>#{JSON.pretty_generate(channel.to_h)}</pre>"
end

get '/oauth2callback' do
  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url
end

Node.js

So führen Sie das Beispiel aus:

  1. Fügen Sie im API Consoledie URL des lokalen Computers der Liste der Weiterleitungs-URLs hinzu, z. B. http://localhost.
  2. Achten Sie darauf, dass ein Wartungs-LTS, ein aktives LTS oder ein aktueller Release von Node.js installiert ist.
  3. Erstellen Sie ein neues Verzeichnis und wechseln Sie dorthin. Beispiel:
    mkdir ~/nodejs-oauth2-example
    cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm:
    npm install googleapis
  5. Erstellen Sie die Dateien main.js mit den unten stehenden Inhalten.
  6. Beispiel ausführen:
    node .\main.js

main.js

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

HTTP/REST

In diesem Python-Beispiel wird der OAuth 2.0-Webfluss mithilfe des Flask und der Bibliothek Requests veranschaulicht. Wir empfehlen die Verwendung der Google API-Clientbibliothek für Python für diesen Ablauf. (Im Beispiel auf dem Python-Tab wird die Clientbibliothek verwendet.)

import json

import flask
import requests


app = flask.Flask(__name__)

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


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


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


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

Validierungsregeln für Weiterleitungs-URIs

Google wendet die folgenden Validierungsregeln für die Weiterleitung von URIs an, um Entwicklern dabei zu helfen, ihre Anwendungen zu schützen. Ihre Weiterleitungs-URIs müssen diesen Regeln entsprechen. Die unten aufgeführten Definitionen von Domain, Host, Pfad, Abfrage, Schema und Nutzerinformationen finden Sie unter RFC 3986, Abschnitt 3.

Validierungsregeln
Schema

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

Organisator

Hosts können keine unformatierten IP-Adressen sein. Localhost-IP-Adressen sind von dieser Regel ausgenommen.

Domain
  • Host-TLDs (Top-Level-Domains) müssen zur öffentlichen Suffixliste gehören.
  • Hostdomains dürfen nicht “googleusercontent.com” sein.
  • Weiterleitungs-URIs dürfen keine Domains mit Kurz-URL-Inhalten (z.B. goo.gl) enthalten, es sei denn, die Domain ist Inhaber der Anwendung. Wenn sich eine Anwendung, die eine Shortener-Domain besitzt, für die Weiterleitung zu dieser Domain entscheidet, muss der Weiterleitungs-URI im Pfad entweder “/google-callback/” enthalten oder mit “/google-callback” enden.
  • Nutzerinformationen

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

    Pfad

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

    Abfrage

    Weiterleitungs-URIs dürfen keine offenen Weiterleitungen enthalten.

    Fragment

    Weiterleitungs-URIs dürfen die Fragment-Komponente nicht enthalten.

    Zeichen Weiterleitungs-URIs dürfen keine bestimmten Zeichen enthalten, z. B.:
    • Platzhalterzeichen ('*')
    • Nicht druckbare ASCII-Zeichen
    • Ungültige Prozentcodierungen (alle Prozentcodierungen, die nicht der URL-Codierungsform 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 Anwendung die Autorisierung für den Zugriff auf Ressourcen an, die durch Bereiche gekennzeichnet sind. Es hat sich bewährt, Ressourcen dann anzufordern, wenn Sie sie benötigen. Dafür unterstützt der Autorisierungsserver von Google die inkrementelle Autorisierung. Mit diesem Feature können Sie Bereiche bei Bedarf anfordern. Wenn der Nutzer die Berechtigung für den neuen Bereich gewährt, wird ein Autorisierungscode zurückgegeben, der möglicherweise gegen ein Token mit allen Bereichen ausgetauscht wird, die der Nutzer dem Projekt gewährt hat.

    Angenommen, eine App hilft Nutzern, interessante lokale Ereignisse zu identifizieren. Mit der App können Nutzer Videos zu den Ereignissen ansehen, die Videos bewerten und die Videos zu Playlists hinzufügen. Nutzer können die App auch verwenden, um ihren Google-Kalendern Termine hinzuzufügen.

    In diesem Fall benötigt die Anwendung bei der Anmeldung möglicherweise keinen Zugriff auf Bereiche und fordert sie auch nicht an. Wenn der Nutzer jedoch versucht, ein Video zu bewerten, einer Playlist ein Video hinzuzufügen oder eine andere YouTube-Aktion auszuführen, kann die App Zugriff auf den Bereich https://www.googleapis.com/auth/youtube.force-ssl anfordern. Ebenso könnte die App Zugriff auf den Bereich https://www.googleapis.com/auth/calendar anfordern, wenn der Nutzer versucht, einen Kalendertermin hinzuzufügen.

    Zum Implementieren der inkrementellen Autorisierung führen Sie den normalen Vorgang zur Anforderung eines Zugriffstokens durch. Achten Sie dabei aber darauf, dass die Autorisierungsanfrage zuvor gewährte Bereiche enthält. So muss Ihre Anwendung nicht mehrere Zugriffstokens verwalten.

    Die folgenden Regeln gelten für Zugriffstokens, die über eine inkrementelle Autorisierung abgerufen werden:

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

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

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

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

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

    Ruby

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

    Node.js

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

    HTTP/REST

    In diesem Beispiel fordert die aufrufende Anwendung zusätzlich zu allen anderen Zugriffsrechten, die der Nutzer der App bereits gewährt hat, Zugriff auf die YouTube Analytics-Daten des Nutzers an.

    GET https://accounts.google.com/o/oauth2/v2/auth?
      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
      access_type=offline&
      state=security_token%3D138rk%3Btarget_url%3Dhttp...index&
      redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
      response_type=code&
      client_id=client_id&
      include_granted_scopes=true
    
          

    Refreshing an access token (offline access)

    Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

    • If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
    • If you are not using a client library, you need to set the access_type HTTP query parameter to offline when redirecting the user to Google's OAuth 2.0 server. In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.

    Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online.

    Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

    PHP

    If your application needs offline access to a Google API, set the API client's access type to offline:

    $client->setAccessType("offline");

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

    Python

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

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

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

    Ruby

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

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

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

    Node.js

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

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

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

    Zugriffstokens laufen ab. Diese Bibliothek verwendet automatisch ein Aktualisierungstoken, um bei Ablauf eines neuen Zugriffstokens ein neues Zugriffstoken abzurufen. Mit dem Token-Ereignis können Sie ganz einfach sicherstellen, dass Sie immer die neuesten Tokens speichern:

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

    Dieses Tokenereignis tritt nur bei der ersten Autorisierung auf. Außerdem müssen Sie access_type auf offline setzen, wenn Sie die Methode generateAuthUrl aufrufen, um das Aktualisierungstoken zu erhalten. Wenn Sie Ihrer Anwendung die erforderlichen Berechtigungen bereits 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 refresh_token später festlegen möchten, können Sie die Methode setCredentials verwenden:

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

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

    HTTP/REST

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

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

    Das folgende Snippet zeigt eine Beispielanfrage:

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

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

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

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

    Token widerrufen

    In manchen Fällen möchte ein Nutzer den Zugriff auf eine App widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument Website- oder App-Zugriff entfernen im Supportdokument von Drittanbietern.

    Apps können den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn sich ein Nutzer abmeldet, eine Anwendung entfernt oder sich die für eine Anwendung erforderlichen API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage umfassen, mit der sichergestellt wird, dass die zuvor der Anwendung gewährten Berechtigungen entfernt werden.

    PHP

    Um ein Token programmatisch zu widerrufen, rufen Sie revokeToken() auf:

    $client->revokeToken();

    Python

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

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

    Ruby

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

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

    Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken vorhanden ist, wird auch das Aktualisierungstoken widerrufen.

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

    Node.js

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

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

    Der Tokenparameter kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken vorhanden ist, wird auch das Aktualisierungstoken widerrufen.

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

    HTTP/REST

    Zum programmatischen Widerrufen eines Tokens sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und nimmt das Token als Parameter auf:

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

    Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken vorhanden ist, wird auch das Aktualisierungstoken widerrufen.

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