OAuth 2.0 für mobile und Desktop-Apps

In diesem Dokument wird erläutert, wie Anwendungen, die auf Geräten wie Smartphones, Tablets und Computern installiert sind, die OAuth 2.0-Endpunkte von Google verwenden, um den Zugriff auf die YouTube Data API zu autorisieren.

OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Eine Anwendung kann beispielsweise OAuth 2.0 verwenden, um die Berechtigung zum Hochladen von Videos auf den YouTube-Kanal eines Nutzers zu erhalten.

Installierte Apps werden auf einzelne Geräte verteilt und es wird davon ausgegangen, dass diese Apps keine Geheimnisse bewahren können. Sie können auf Google APIs zugreifen, während der Nutzer die App verwendet oder wenn die App im Hintergrund ausgeführt wird.

Dieser Autorisierungsvorgang ähnelt dem für Webserveranwendungen. Der Hauptunterschied besteht darin, dass installierte Apps den Systembrowser öffnen und einen lokalen Weiterleitungs-URI angeben müssen, um Antworten vom Autorisierungsserver von Google zu verarbeiten.

Bibliotheken und Beispiele

Für mobile Apps empfehlen wir die Verwendung der aktuellen Version der nativen Google Identity Services-Bibliothek für Android und der nativen Google Log-in-Bibliothek für iOS. Diese Bibliotheken übernehmen die Nutzerautorisierung und sind einfacher zu implementieren als das hier beschriebene Protokoll auf niedrigerer Ebene.

Informationen zu Apps, die auf Geräten ausgeführt werden, die keinen Systembrowser unterstützen oder nur begrenzte Eingabefunktionen haben, z. B. Fernseher, Spielekonsolen, Kameras oder Drucker, finden Sie unter OAuth 2.0 für Fernseher und Geräte oder Anmelden auf Fernsehern und Geräten mit begrenzter Eingabe.

Vorbereitung

Die APIs für Ihr Projekt aktivieren

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

So aktivieren Sie eine API für Ihr Projekt:

1. Open the API Library in der Google API Console.
2. If prompted, select a project, or create a new one.
3. Die YouTube Data API auf der Seite Bibliothek suchen und aktivieren Suchen Sie nach anderen APIs, die von Ihrer Anwendung verwendet werden, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Für jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, müssen Autorisierungsanmeldedaten vorhanden sein, mit denen die Anwendung beim OAuth 2.0-Server von Google identifiziert wird. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

1. Go to the Credentials page.
2. Klicken Sie auf Create client.
3. In den folgenden Abschnitten werden die Clienttypen beschrieben, die vom Autorisierungsserver von Google unterstützt werden. Wählen Sie den für Ihre Anwendung empfohlenen Clienttyp aus, geben Sie Ihrem OAuth-Client einen Namen und legen Sie die anderen Felder im Formular entsprechend fest.

Zugriffsbereiche ermitteln

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

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

Die YouTube Data API v3 verwendet die folgenden Bereiche:

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 beschrieben, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Zustimmung eines Nutzers zum Ausführen einer API-Anfrage in seinem Namen einzuholen. Ihre Anwendung muss diese Einwilligung haben, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.

Schritt 1: Code-Verifier und -Challenge generieren

Google unterstützt das PKCE-Protokoll (Proof Key for Code Exchange), um den Ablauf für installierte Apps sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Code-Verifier erstellt. Der transformierte Wert, der als „code_challenge“ bezeichnet wird, wird an den Autorisierungsserver gesendet, um den Autorisierungscode zu erhalten.

Code-Verifier erstellen

Ein code_verifier ist ein kryptografischer Zufallsstring mit hoher Entropie, der die nicht reservierten Zeichen [A-Z] / [a-z] / [0-9] / „-“ / „.“ / „_“ / „~“ verwendet und eine Mindestlänge von 43 Zeichen und eine maximale Länge von 128 Zeichen hat.

Der Code-Verifier sollte genügend Entropie haben, damit der Wert nicht erraten werden kann.

Code-Herausforderung erstellen

Es gibt zwei unterstützte Methoden zum Erstellen der Code-Challenge.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Schritt 2: Anfrage an den OAuth 2.0-Server von Google senden

Um die Nutzerautorisierung zu erhalten, senden Sie eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth. Dieser Endpunkt verarbeitet die Suche nach aktiven Sitzungen, authentifiziert den Nutzer und holt die Einwilligung des Nutzers ein. Der Endpunkt ist nur über SSL zugänglich und lehnt HTTP-Verbindungen (ohne SSL) ab.

Der Autorisierungsserver unterstützt die folgenden Abfragestringparameter für installierte Anwendungen:

Beispiel-Autorisierungs-URLs

Auf den Tabs unten finden Sie Beispiel-Autorisierungs-URLs für die verschiedenen Optionen für Weiterleitungs-URIs.

Die URLs sind bis auf den Wert des Parameters redirect_uri identisch. Die URLs enthalten auch die erforderlichen Parameter response_type und client_id sowie den optionalen Parameter state. Jede URL enthält Zeilenumbrüche und Leerzeichen für eine bessere Lesbarkeit.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Schritt 3: Google fordert Nutzer zur Einwilligung auf

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

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

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Wie Ihre Anwendung die Autorisierungsantwort empfängt, hängt vom Weiterleitungs-URI-Schema ab, das sie verwendet. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode (code) oder einen Fehler (error). error=access_denied gibt beispielsweise an, dass der Nutzer die Anfrage abgelehnt hat.

Wenn der Nutzer Ihrer Anwendung Zugriff gewährt, können Sie den Autorisierungscode wie im nächsten Schritt beschrieben gegen ein Zugriffstoken und ein Aktualisierungstoken eintauschen.

Schritt 5: Autorisierungscode gegen Aktualisierungs- und Zugriffstokens austauschen

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

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=http://127.0.0.1:9004&
grant_type=authorization_code

Google antwortet auf diese Anfrage mit einem JSON-Objekt, das ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken enthält.

Die Antwort umfasst die folgenden Felder:

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

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

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

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

Weitere Informationen finden Sie unter Granulare Berechtigungen verwalten.

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

Die folgende Beispielantwort für ein Zugriffstoken gibt beispielsweise an, dass der Nutzer Ihrer Anwendung die Berechtigung erteilt hat, die YouTube-Videos, ‑Bewertungen, ‑Kommentare und ‑Untertitel des Nutzers anzusehen, zu bearbeiten und dauerhaft zu löschen:

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

Google APIs aufrufen

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

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

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

Beispiele für HTTP GET

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

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 Query-String-Parameter 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 mit der HTTP-Header-Option (bevorzugt):

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

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

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

Zugriffstokens aktualisieren

Zugriffstokens laufen regelmäßig ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um eine Berechtigung zu bitten (auch wenn der Nutzer nicht anwesend ist), wenn Sie den Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

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

Das folgende Snippet zeigt eine Beispielanfrage:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

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

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

Token widerrufen

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

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

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

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

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

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

Methoden für App-Weiterleitungen

Apps schützen

Zeitbasierter Zugriff

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

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

Weiterführende Literatur

Viele der hier dokumentierten Best Practices sind in der IETF Best Current Practice OAuth 2.0 for Native Apps festgelegt.