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. Beispielsweise kann eine Anwendung OAuth 2.0 verwenden, um die Berechtigung zum Hochladen von Videos auf den YouTube-Kanal eines Nutzers zu erhalten.

Installierte Apps werden an einzelne Geräte verteilt und es wird davon ausgegangen, dass diese Apps keine Secrets speichern 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 Autorisierungsvorgang ähnelt dem für Webserveranwendungen. Der Hauptunterschied besteht darin, dass installierte Anwendungen den Systembrowser öffnen und einen lokalen Weiterleitungs-URI bereitstellen müssen, um Antworten vom Autorisierungsserver von Google zu verarbeiten.

Alternativen

Für mobile Apps können Sie Google Log-in für Android oder iOS verwenden. Die Google Log-in-Clientbibliotheken übernehmen die Authentifizierung und Nutzerautorisierung und sind möglicherweise einfacher zu implementieren als das hier beschriebene untergeordnete Protokoll.

Informationen zu Apps, die auf Geräten ausgeführt werden, die keinen Systembrowser unterstützen oder nur eingeschränkte Eingabefunktionen haben, z. B. Fernseher, Spielekonsolen, Kameras oder Drucker, findest du unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und Geräten mit eingeschränkter Eingabe.

Bibliotheken und Beispiele

Wir empfehlen die folgenden Bibliotheken und Beispiele, die dir bei der Implementierung des in diesem Dokument beschriebenen OAuth 2.0-Vorgangs helfen:

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

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 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 finden und aktivieren. Suchen Sie alle anderen APIs, die Ihre Anwendung verwendet, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, benötigt Autorisierungsanmeldedaten, 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 das 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 und die Weiterleitungsmethoden beschrieben, die der Autorisierungsserver von Google unterstützt. Wählen Sie den für Ihre Anwendung empfohlenen Clienttyp aus, benennen Sie den OAuth-Client und legen Sie die anderen Felder im Formular entsprechend fest.

Zugriffsbereiche identifizieren

Mit Bereichen kann Ihre Anwendung nur Zugriff auf die benötigten Ressourcen anfordern und Nutzer können gleichzeitig den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen, bestehen.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, auf die Ihre Anwendung eine Zugriffsberechtigung benötigt.

Für Version 3 der YouTube Data API werden die folgenden Umfänge verwendet:

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

Die folgenden Schritte zeigen, wie deine 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 muss diese Einwilligung haben, bevor sie eine Google API-Anfrage ausführen kann, die eine Nutzerautorisierung erfordert.

Schritt 1: Codeprüfung und ‐herausforderung 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 eine eindeutige Codeprüfung erstellt und der transformierte Wert namens „code_challenge“ wird an den Autorisierungsserver gesendet, um den Autorisierungscode abzurufen.

Codeprüfung 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.

Die Codeprüfung sollte genügend Entropie haben, damit der Wert nicht erraten werden kann.

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

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

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

Beispiele für Autorisierungs-URLs

Auf den Tabs unten sehen Sie Beispiele für 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 außerdem die erforderlichen Parameter response_type und client_id sowie den optionalen Parameter state. Jede 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&
 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ähren möchte. In dieser Phase zeigt Google ein Einwilligungsfenster mit dem Namen Ihrer Anwendung und den Google API-Diensten an, für die die Berechtigung 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 Bereiche zu gewähren, die von Ihrer Anwendung angefordert werden, oder die Anfrage ablehnen.

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

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). Zum Beispiel gibt error=access_denied an, dass der Nutzer die Anfrage abgelehnt hat.

Wenn der Nutzer Zugriff auf deine Anwendung gewährt, kannst du den Autorisierungscode wie im nächsten Schritt beschrieben gegen ein Zugriffstoken und ein Aktualisierungstoken austauschen.

Schritt 5: Autorisierungscode gegen Aktualisierungs- und Zugriffstokens austauschen

Rufen Sie den Endpunkt https://oauth2.googleapis.com/token auf und legen Sie die folgenden Parameter fest, um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen:

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 reagiert auf diese Anfrage mit der Rückgabe eines JSON-Objekts, 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 abgerufen hat, können Sie mit dem Token im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, wenn die für die API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Nach Möglichkeit ist der HTTP-Header zu empfehlen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du Aufrufe von Google APIs mithilfe einer Clientbibliothek 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: 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 sehen Sie einen 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 verwendet wird (bevorzugt):

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

Zugriffstokens aktualisieren

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

Zum Aktualisieren eines Zugriffstokens sendet Ihre Anwendung eine HTTPS-POST-Anfrage an den Autorisierungsserver von Google (https://oauth2.googleapis.com/token) mit den folgenden Parametern:

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 langfristig 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 Zugriff auf eine Anwendung widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Supportdokument zu 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 in Fällen wichtig, in denen ein Nutzer das Abo beendet oder 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 der Anwendung zuvor gewährten Berechtigungen entfernt werden.

Wenn Sie ein Token programmatisch widerrufen möchten, stellt 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 Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und 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.

Weiterführende Literatur

Die IETF Best Current Practice OAuth 2.0 for Native Apps enthält viele der hier dokumentierten Best Practices.