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.

Mit OAuth 2.0 können Nutzer bestimmte Daten für eine Anwendung freigeben, 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 wahren können. Sie können auf Google APIs zugreifen, während sich der Nutzer in der App befindet oder die App im Hintergrund ausgeführt wird.

Dieser Autorisierungsablauf ähnelt dem, der für Webserveranwendungen verwendet wird. 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.

Alternativen

Für mobile Apps können Sie Google Sign-in für Android oder iOS verwenden. Die Clientbibliotheken für die Google-Anmeldung übernehmen die Authentifizierung und Nutzerautorisierung. Sie sind möglicherweise 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 eingeschränkte Eingabemöglichkeiten haben, z. B. Fernseher, Spielekonsolen, Kameras oder Drucker, finden Sie unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und Geräten mit begrenzter Eingabe.

Bibliotheken und Beispiele

Wir empfehlen die folgenden Bibliotheken und Beispiele, um den in diesem Dokument beschriebenen OAuth 2.0-Ablauf zu implementieren:

• Bibliothek AppAuth for Android
• AppAuth for iOS-Bibliothek
• OAuth für Apps: Windows-Beispiele

Vorbereitung

Die APIs für Ihr Projekt aktivieren

Jede Anwendung, die Google APIs aufruft, muss diese APIs in der 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. Suche auf der Seite Bibliothek nach der YouTube Data API und aktiviere sie. Suchen Sie alle anderen APIs, die Ihre Anwendung verwendet, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Alle Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, müssen Autorisierungsdaten haben, die die Anwendung beim OAuth 2.0-Server von Google identifizieren. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

1. Go to the Credentials page.
2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
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 einen Namen für Ihren OAuth-Client ein und legen Sie die anderen Felder im Formular entsprechend fest.

Zugriffsbereiche identifizieren

Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht möglicherweise ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

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

Die YouTube Data API 3 verwendet die folgenden Zugriffsbereiche:

Das Dokument OAuth 2.0 API Scopes 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, eine API-Anfrage im Namen des Nutzers auszuführen. Ihre Anwendung benötigt diese Einwilligung, 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 Protokoll Proof Key for Code Exchange (PKCE), um den Ablauf der installierten App sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Code Verifier erstellt. Der umgewandelte Wert, „code_challenge“, wird an den Autorisierungsserver gesendet, um den Autorisierungscode abzurufen.

Code Verifier erstellen

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

Der Code Verifier sollte eine ausreichende Entropie haben, damit es nicht möglich ist, den Wert zu erraten.

Code Challenge erstellen

Es werden zwei Methoden zum Erstellen der Code-Abfrage unterstützt.

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

code_challenge = code_verifier

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

Wenn du die Nutzerautorisierung erhalten möchtest, sende 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 Nutzereinwilligung ein. Der Endpunkt ist nur über SSL zugänglich und HTTP-Verbindungen (ohne SSL) werden abgelehnt.

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

Beispiele für Autorisierungs-URLs

Auf den folgenden Tabs finden Sie Beispielautorisierungs-URLs für die verschiedenen Weiterleitungs-URI-Optionen.

Die URLs sind bis auf den Wert des Parameters redirect_uri identisch. Die URLs enthalten außerdem 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 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 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. Außerdem wird eine Zusammenfassung der zu gewährenden Zugriffsbereiche angezeigt. Der Nutzer kann dann zustimmen, Zugriff auf einen oder mehrere Bereiche zu gewähren, die von Ihrer Anwendung angefordert werden, oder die Anfrage ablehnen.

Ihre 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 nächsten Schritt erläutert.

Schritt 4: Die Antwort des OAuth 2.0-Servers verarbeiten

Wie Ihre Anwendung die Autorisierungsantwort empfängt, hängt vom verwendeten Weiterleitungs-URI-Schema ab. 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 Zugriff auf Ihre Anwendung 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 Zugriffstoken austauschen

Wenn du einen Autorisierungscode gegen ein Zugriffstoken eintauschen möchtest, rufe den Endpunkt https://oauth2.googleapis.com/token auf und lege 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"
}

Google APIs aufrufen

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie damit im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Dazu fügen Sie das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Wenn möglich, ist der HTTP-Header vorzuziehen, da Suchstrings in Serverprotokollen in der Regel sichtbar sind. In den meisten Fällen kannst du mit einer Clientbibliothek Aufrufe von Google APIs einrichten, z. B. beim Aufrufen der YouTube Data API.

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

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

Beispiele für HTTP-GET

Ein Aufruf des youtube.channels-Endpunkts (die YouTube Data API) über den 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 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 Befehlszeilenanwendung curl testen. Hier ein Beispiel, in dem die HTTP-Header-Option verwendet wird (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 „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.

Um ein Zugriffstoken zu aktualisieren, sendet Ihre Anwendung eine HTTPS-POST-Anfrage an den Autorisierungsserver (https://oauth2.googleapis.com/token) von Google, 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 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 weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann diese Grenze überschritten werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token widerrufen

In einigen Fällen möchte ein Nutzer den einer Anwendung erteilten Zugriff widerrufen. Nutzer können 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.

Es ist auch möglich, den Zugriff einer Anwendung programmatisch zu widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer sein Abo kündigt, eine App 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, mit der sichergestellt wird, dass die der Anwendung zuvor 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 hinzu:

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

Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken hat, 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.

Methoden für App-Weiterleitungen