OAuth 2.0 für JavaScript-Webanwendungen verwenden

In diesem Dokument wird erläutert, wie die OAuth 2.0-Autorisierung implementiert wird, um über eine JavaScript-Webanwendung auf die YouTube Data API zuzugreifen. OAuth 2.0 ermöglicht es 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 wird als impliziter Gewährungsvorgang bezeichnet. Sie ist für Anwendungen gedacht, die nur auf APIs zugreifen, wenn der Nutzer die Anwendung anwesend ist. Diese Anwendungen können keine vertraulichen Informationen speichern.

In diesem Ablauf öffnet Ihre Anwendung eine Google-URL, die mithilfe von Abfrageparametern Ihre Anwendung und die Art des API-Zugriffs, den die Anwendung benötigt, identifiziert. Sie können die URL im aktuellen Browserfenster oder in einem Pop-up-Fenster öffnen. Der Nutzer kann sich bei Google authentifizieren und die angeforderten Berechtigungen erteilen. Google leitet den Nutzer dann zurück zu Ihrer Anwendung zurück. Die Weiterleitung enthält ein Zugriffstoken, das von Ihrer Anwendung verifiziert und dann für API-Anfragen verwendet wird.

Google API-Clientbibliothek und Google Identity Services

Wenn du autorisierte Aufrufe an Google über die Google API-Clientbibliothek für JavaScript sendest, solltest du für den OAuth 2.0-Vorgang die JavaScript-Bibliothek der Google Identity Services verwenden. Weitere Informationen finden Sie im Tokenmodell der Google-Identitätsdienste, das auf dem impliziten OAuth 2.0-Zustimmungsvorgang basiert.

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 es aus. Anwendungen, die autorisierte Google API-Anfragen mithilfe von JavaScript senden, müssen autorisierte JavaScript-Quellen angeben. Die Quellen identifizieren die Domains, von denen deine Anwendung Anfragen an den OAuth 2.0-Server senden kann. Diese Ursprünge müssen den Validierungsregeln von Google entsprechen.

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.

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.

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.

Schritt 1: Zum OAuth 2.0-Server von Google weiterleiten

Wenn du die Berechtigung für den Zugriff auf die Daten eines Nutzers anfordern möchtest, leite den Nutzer an den OAuth 2.0-Server von Google weiter.

OAuth 2.0-Endpunkte

Generiere eine URL, um Zugriff vom OAuth 2.0-Endpunkt von Google unter https://accounts.google.com/o/oauth2/v2/auth anzufordern. Auf diesen Endpunkt kann ü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

JavaScript-Anwendungen müssen den Wert des Parameters auf token setzen. Mit diesem Wert wird der Google-Autorisierungsserver angewiesen, das Zugriffstoken als name=value-Paar in der Fragment-ID des URI (#) zurückzugeben, an den der Nutzer nach Abschluss des Autorisierungsvorgangs weitergeleitet wird.

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.

state Empfohlen

Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten. Der Server gibt genau den Wert zurück, den Sie als name=value-Paar in der URL-Fragment-ID (#) von 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 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

Beispiel für eine Weiterleitung zum Autorisierungsserver von Google

Mit der folgenden Beispiel-URL wird der Offlinezugriff (access_type=offline) für einen Bereich angefordert, der das Aufrufen des YouTube-Kontos des Nutzers ermöglicht. Durch die inkrementelle Autorisierung wird sichergestellt, dass das neue Zugriffstoken alle Bereiche abdeckt, für die der Nutzer zuvor der Anwendung Zugriff gewährt hat. Die URL legt auch Werte für die erforderlichen Parameter redirect_uri, response_type und client_id sowie für den Parameter state fest. Die URL enthält zur besseren Lesbarkeit Zeilenumbrüche und Leerzeichen.

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

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

JavaScript-Beispielcode

Das folgende JavaScript-Snippet zeigt, wie Sie den Autorisierungsvorgang in JavaScript initiieren, ohne die Google APIs-Clientbibliothek für JavaScript zu verwenden. Da dieser OAuth 2.0-Endpunkt Cross-Origin Resource Sharing (CORS) nicht unterstützt, erstellt das Snippet ein Formular, das die Anfrage an diesen Endpunkt öffnet.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

Schritt 2: 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 Ursprung, von dem die Anfrage stammt, ist für diesen Client nicht autorisiert. Siehe origin_mismatch.

invalid_grant

Bei Verwendung der inkrementellen Autorisierung ist das Token möglicherweise abgelaufen oder ungültig. Authentifizieren Sie den Nutzer noch einmal und bitten Sie ihn um seine Zustimmung, um neue Tokens zu erhalten. Wenn dieser Fehler weiterhin 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.

origin_mismatch

Das Schema, die Domain und/oder der Port des JavaScript-Codes, von dem die Autorisierungsanfrage stammt, stimmen möglicherweise nicht mit einem autorisierten JavaScript-Ursprungs-URI überein, der für die OAuth-Client-ID registriert ist. Prüfen Sie die autorisierten JavaScript-Quellen in der Google API Console Credentials page.

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.

Das Schema, die Domain und/oder der Port des JavaScript-Codes, von dem die Autorisierungsanfrage stammt, stimmen möglicherweise nicht mit einem autorisierten JavaScript-Ursprungs-URI überein, der für die OAuth-Client-ID registriert ist. Informationen zu autorisierten JavaScript-Quellen findest du in der Google API Console Credentials page.

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 3: OAuth 2.0-Serverantwort verarbeiten

OAuth 2.0-Endpunkte

Der OAuth 2.0-Server sendet eine Antwort an den redirect_uri, der in Ihrer Zugriffstoken-Anfrage angegeben ist.

Wenn der Nutzer die Anfrage genehmigt, enthält die Antwort ein Zugriffstoken. Wenn der Nutzer die Anfrage nicht genehmigt, enthält die Antwort eine Fehlermeldung. Das Zugriffstoken oder die Fehlermeldung wird wie unten dargestellt als Hash-Fragment des Weiterleitungs-URI zurückgegeben:

  • Eine Zugriffstoken-Antwort:

    https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

    Zusätzlich zum Parameter access_token enthält der Fragmentstring auch den Parameter token_type, der immer auf Bearer gesetzt ist, und den Parameter expires_in, der die Lebensdauer des Tokens in Sekunden angibt. Wenn der Parameter state in der Zugriffstoken-Anfrage angegeben wurde, ist sein Wert auch in der Antwort enthalten.

  • Eine Fehlerantwort:
    https://oauth2.example.com/callback#error=access_denied

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&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

Nach Abschluss des OAuth 2.0-Vorgangs werden Sie zu http://localhost/oauth2callback weitergeleitet. Diese URL gibt den Fehler 404 NOT FOUND zurück, es sei denn, Ihr lokaler Rechner stellt unter dieser Adresse eine Datei bereit. Im nächsten Schritt finden Sie weitere Details zu den Informationen, die im URI zurückgegeben werden, wenn der Nutzer zu Ihrer Anwendung zurückgeleitet wird.

Google APIs aufrufen

OAuth 2.0-Endpunkte

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

JavaScript-Beispielcode

Das folgende Code-Snippet zeigt, wie mithilfe von CORS (Cross-Origin Resource Sharing) eine Anfrage an eine Google API gesendet wird. In diesem Beispiel wird die Google APIs-Clientbibliothek für JavaScript nicht verwendet. Aber auch wenn Sie die Clientbibliothek nicht verwenden, können Sie diese Anfragen wahrscheinlich besser verstehen, wenn Sie in der Dokumentation der Bibliothek den CORS-Support-Leitfaden verwenden.

In diesem Code-Snippet stellt die Variable access_token das Token dar, das Sie für API-Anfragen im Namen des autorisierten Nutzers erhalten haben. Das vollständige Beispiel zeigt, wie dieses Token im lokalen Speicher des Browsers gespeichert und beim Senden einer API-Anfrage abgerufen wird.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Vollständiges Beispiel

OAuth 2.0-Endpunkte

In diesem Codebeispiel wird gezeigt, wie der OAuth 2.0-Vorgang in JavaScript ausgeführt wird, ohne die Google APIs-Clientbibliothek für JavaScript zu verwenden. Der Code bezieht sich auf eine HTML-Seite, auf der eine Schaltfläche zum Versuch einer API-Anfrage angezeigt wird. Wenn du auf die Schaltfläche klickst, prüft der Code, ob die Seite ein API-Zugriffstoken im lokalen Speicher des Browsers gespeichert hat. In diesem Fall wird die API-Anfrage ausgeführt. Andernfalls wird der OAuth 2.0-Vorgang initiiert.

Für den OAuth 2.0-Vorgang umfasst die Seite die folgenden Schritte:

  1. Der Nutzer wird an den OAuth 2.0-Server von Google weitergeleitet, der Zugriff auf den Bereich https://www.googleapis.com/auth/youtube.force-ssl anfordert.
  2. Nachdem der Nutzer Zugriff auf einen oder mehrere angeforderte Bereiche gewährt (oder verweigert) hat, wird er zur ursprünglichen Seite weitergeleitet, die das Zugriffstoken aus dem String der Fragment-ID parst.
  3. Die Seite verwendet das Zugriffstoken für die Beispiel-API-Anfrage.

    Diese API-Anfrage ruft die channels.list-Methode der YouTube Data API auf, um Daten zum YouTube-Kanal des autorisierten Nutzers abzurufen.

  4. Wenn die Anfrage erfolgreich ausgeführt wird, wird die API-Antwort in der Fehlerbehebungskonsole des Browsers protokolliert.

Du kannst den Zugriff auf die App auf der Seite Berechtigungen für dein Google-Konto widerrufen. Die App wird als OAuth 2.0 Demo for Google API Docs aufgeführt.

Wenn Sie diesen Code lokal ausführen möchten, müssen Sie Werte für die Variablen YOUR_CLIENT_ID und YOUR_REDIRECT_URI festlegen, die Ihren Autorisierungsdaten entsprechen. Für die Variable YOUR_REDIRECT_URI muss dieselbe URL festgelegt werden, unter der die Seite bereitgestellt wird. 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 pagekonfiguriert hast. Wenn dieser Wert mit keinem autorisierten URI übereinstimmt, erhalten Sie den Fehler redirect_uri_mismatch. Außerdem muss für Ihr Projekt die entsprechende API für diese Anfrage aktiviert sein.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                  'state': 'try_sample_request',
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

Regeln für die JavaScript-Ursprungsvalidierung

Google wendet die folgenden Validierungsregeln auf JavaScript-Quellen an, um Entwicklern dabei zu helfen, ihre Anwendungen zu schützen. Bei Ihren JavaScript-Quellen müssen diese Regeln eingehalten werden. Die Definition von Domain, Host und Schema finden Sie unter RFC 3986, Abschnitt 3 (siehe unten).

Validierungsregeln
Schema

JavaScript-Quellen 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.
  • JavaScript-Quellen dürfen keine Domains mit Kurz-URL-Inhalten (z.B. goo.gl) enthalten, es sei denn, die App ist Inhaber der Domain.
  • Nutzerinformationen

    JavaScript-Quellen dürfen die Unterkomponente „userinfo“ nicht enthalten.

    Pfad

    JavaScript-Quellen dürfen die Pfadkomponente nicht enthalten.

    Abfrage

    JavaScript-Quellen dürfen die Abfragekomponente nicht enthalten.

    Fragment

    JavaScript-Quellen dürfen die Fragment-Komponente nicht enthalten.

    Zeichen JavaScript-Quellen dürfen folgende Zeichen nicht enthalten:
    • Platzhalterzeichen ('*')
    • Nicht druckbare ASCII-Zeichen
    • Ungültige Prozentcodierungen (alle Prozentcodierungen, die nicht der URL-Codierungsform eines Prozentzeichens gefolgt von zwei Hexadezimalziffern 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.

    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.

    Die folgenden Codebeispiele zeigen, wie Sie einem vorhandenen Zugriffstoken Bereiche hinzufügen. So muss Ihre Anwendung nicht mehrere Zugriffstokens verwalten.

    OAuth 2.0-Endpunkte

    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.

    Wenn du einem vorhandenen Zugriffstoken Bereiche hinzufügen möchtest, füge den Parameter include_granted_scopes in deine Anfrage an den OAuth 2.0-Server von Google ein.

    Das folgende Code-Snippet zeigt, wie das funktioniert. Das Snippet geht davon aus, dass Sie die Bereiche, für die Ihr Zugriffstoken gültig ist, im lokalen Speicher des Browsers gespeichert haben. Im vollständigen Beispielcode wird eine Liste der Bereiche gespeichert, für die das Zugriffstoken gültig ist. Dazu wird das Attribut oauth2-test-params.scope im lokalen Speicher des Browsers festgelegt.

    Das Snippet vergleicht die Bereiche, für die das Zugriffstoken gültig ist, mit dem Bereich, den Sie für eine bestimmte Abfrage verwenden möchten. Wenn das Zugriffstoken diesen Bereich nicht abdeckt, wird der OAuth 2.0-Vorgang gestartet. Hier entspricht die Funktion oauth2SignIn der Funktion in Schritt 2 (und wird später im vollständigen Beispiel verwendet).

    var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    
    var current_scope_granted = false;
    if (params.hasOwnProperty('scope')) {
      var scopes = params['scope'].split(' ');
      for (var s = 0; s < scopes.length; s++) {
        if (SCOPE == scopes[s]) {
          current_scope_granted = true;
        }
      }
    }
    
    if (!current_scope_granted) {
      oauth2SignIn(); // This function is defined elsewhere in this document.
    } else {
      // Since you already have access, you can proceed with the API request.
    }

    Token widerrufen

    In manchen Fällen möchte ein Nutzer den Zugriff auf eine Anwendung 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.

    OAuth 2.0-Endpunkte

    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.

    Das folgende JavaScript-Snippet zeigt, wie ein Token in JavaScript widerrufen wird, ohne die Google APIs-Clientbibliothek für JavaScript zu verwenden. Da der OAuth 2.0-Endpunkt von Google für das Widerrufen von Tokens Cross-Origin Resource Sharing (CORS) nicht unterstützt, wird mit dem Code ein Formular erstellt und an den Endpunkt gesendet, anstatt die Anfrage mit der Methode XMLHttpRequest() zu senden.

    function revokeAccess(accessToken) {
      // Google's OAuth 2.0 endpoint for revoking access tokens.
      var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
    
      // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
      var form = document.createElement('form');
      form.setAttribute('method', 'post');
      form.setAttribute('action', revokeTokenEndpoint);
    
      // Add access token to the form so it is set as value of 'token' parameter.
      // This corresponds to the sample curl request, where the URL is:
      //      https://oauth2.googleapis.com/revoke?token={token}
      var tokenField = document.createElement('input');
      tokenField.setAttribute('type', 'hidden');
      tokenField.setAttribute('name', 'token');
      tokenField.setAttribute('value', accessToken);
      form.appendChild(tokenField);
    
      // Add form to page and submit it to actually revoke the token.
      document.body.appendChild(form);
      form.submit();
    }