OAuth 2.0 für TV-Apps und Geräteanwendungen mit begrenzter Eingabe

In diesem Dokument wird beschrieben, wie Sie die OAuth 2.0-Autorisierung implementieren, um über Anwendungen, die auf Geräten wie Fernsehern, Spielekonsolen und Druckern ausgeführt werden, auf die YouTube Data API zuzugreifen. Dieser Ablauf ist speziell für Geräte konzipiert, die entweder keinen Zugriff auf einen Browser haben oder nur eingeschränkte Eingabemöglichkeiten bieten.

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 TV-Anwendung könnte beispielsweise OAuth 2.0 verwenden, um die Berechtigung zum Auswählen einer in Google Drive gespeicherten Datei zu erhalten.

Da die Anwendungen, die diesen Ablauf verwenden, auf einzelnen Geräten verteilt werden, wird davon ausgegangen, dass die Apps keine Secrets speichern 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.

Alternativen

Wenn Sie eine App für eine Plattform wie Android, iOS, macOS, Linux oder Windows (einschließlich der Universal Windows Platform) entwickeln, die Zugriff auf den Browser und vollständige Eingabefunktionen hat, verwenden Sie den OAuth 2.0-Ablauf für mobile und Desktopanwendungen. Sie sollten diesen Ablauf auch dann verwenden, wenn Ihre App ein Befehlszeilentool ohne grafische Benutzeroberfläche ist.

Wenn Sie Nutzer nur mit ihren Google-Konten anmelden und JWT-ID-Tokens verwenden möchten, um grundlegende Nutzerprofilinformationen abzurufen, lesen Sie den Abschnitt Anmeldung auf Fernsehern und Geräten mit eingeschränkter 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. YouTube Data API in der 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. Wählen Sie den Anwendungstyp Fernsehgeräte und Geräte mit begrenzter Eingabe aus.
4. Geben Sie Ihrem OAuth 2.0-Client einen Namen und klicken Sie auf Erstellen.

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:

Die Liste der zulässigen Bereiche für installierte Apps oder Geräte finden Sie hier.

OAuth 2.0-Zugriffstokens abrufen

Auch wenn Ihre Anwendung auf einem Gerät mit eingeschränkten Eingabefunktionen ausgeführt wird, müssen Nutzer separat auf ein Gerät mit umfangreicheren Eingabefunktionen zugreifen können, um diesen Autorisierungsablauf abzuschließen. Der Ablauf umfasst die folgenden Schritte:

1. Ihre Anwendung sendet eine Anfrage an den Autorisierungsserver von Google, in der die Bereiche angegeben werden, für die Ihre Anwendung die Berechtigung zum Zugriff anfordert.
2. Der Server antwortet mit mehreren Informationen, die in den nachfolgenden Schritten verwendet werden, z. B. einem Gerätecode und einem Nutzercode.
3. Sie zeigen Informationen an, die der Nutzer auf einem separaten Gerät eingeben kann, um Ihre App zu autorisieren.
4. Ihre Anwendung beginnt, den Autorisierungsserver von Google abzufragen, um festzustellen, ob der Nutzer Ihre App autorisiert hat.
5. Der Nutzer wechselt zu einem Gerät mit besseren Eingabemöglichkeiten, startet einen Webbrowser, ruft die in Schritt 3 angezeigte URL auf und gibt einen Code ein, der ebenfalls in Schritt 3 angezeigt wird. Der Nutzer kann dann den Zugriff auf Ihre Anwendung gewähren oder verweigern.
6. Die nächste Antwort auf Ihre Polling-Anfrage enthält die Tokens, die Ihre App benötigt, um Anfragen im Namen des Nutzers zu autorisieren. Wenn der Nutzer den Zugriff auf Ihre Anwendung abgelehnt hat, enthält die Antwort keine Tokens.

Das folgende Bild veranschaulicht diesen Vorgang:

In den folgenden Abschnitten werden diese Schritte im Detail erläutert. Angesichts der unterschiedlichen Funktionen und Laufzeitumgebungen, die Geräte haben können, wird in den Beispielen in diesem Dokument das curl-Befehlszeilentool verwendet. Diese Beispiele sollten sich einfach auf verschiedene Sprachen und Laufzeiten portieren lassen.

Schritt 1: Geräte- und Nutzercodes anfordern

In diesem Schritt sendet Ihr Gerät eine HTTP-POST-Anfrage an den Autorisierungsserver von Google unter https://oauth2.googleapis.com/device/code, in der Ihre Anwendung sowie die Zugriffsbereiche angegeben werden, auf die Ihre Anwendung im Namen des Nutzers zugreifen möchte. Sie sollten diese URL aus dem Discovery-Dokument mit dem Metadatenwert device_authorization_endpoint abrufen. Fügen Sie die folgenden HTTP-Anfrageparameter ein:

Beispiele

Das folgende Snippet zeigt eine Beispielanfrage:

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

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

Dieses Beispiel zeigt einen curl-Befehl zum Senden derselben Anfrage:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Schritt 2: Antwort des Autorisierungsservers verarbeiten

Der Autorisierungsserver gibt eine der folgenden Antworten zurück:

Erfolgsantwort

Wenn die Anfrage gültig ist, ist die Antwort ein JSON-Objekt mit den folgenden Attributen:

Das folgende Snippet zeigt eine Beispielantwort:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Antwort bei Kontingentüberschreitung

Wenn Ihre Anfragen für Gerätecodes das mit Ihrer Client-ID verknüpfte Kontingent überschritten haben, erhalten Sie eine 403-Antwort mit dem folgenden Fehler:

{
  "error_code": "rate_limit_exceeded"
}

Verwenden Sie in diesem Fall eine Backoff-Strategie, um die Anzahl der Anfragen zu reduzieren.

Schritt 3: Nutzercode anzeigen

Zeigen Sie dem Nutzer die in Schritt 2 erhaltenen verification_url und user_code an. Beide Werte können beliebige druckbare Zeichen aus dem US-ASCII-Zeichensatz enthalten. Der Inhalt, den Sie dem Nutzer präsentieren, sollte ihn anweisen, auf einem separaten Gerät zu verification_url zu gehen und die user_code einzugeben.

Beachten Sie beim Design Ihrer Benutzeroberfläche (UI) die folgenden Regeln:

• user_code
  • Die user_code muss in einem Feld angezeigt werden, das 15 Zeichen der Größe „W“ aufnehmen kann. Wenn Sie den Code WWWWWWWWWWWWWWW korrekt anzeigen können, ist Ihre Benutzeroberfläche gültig. Wir empfehlen, diesen Stringwert zu verwenden, wenn Sie testen, wie user_code auf Ihrer Benutzeroberfläche angezeigt wird.
  • Bei user_code wird die Groß- und Kleinschreibung berücksichtigt und es darf in keiner Weise geändert werden, z. B. durch Ändern der Groß- und Kleinschreibung oder Einfügen anderer Formatierungszeichen.
• verification_url
  • Der Bereich, in dem Sie verification_url anzeigen, muss breit genug sein, um einen URL-String mit 40 Zeichen aufzunehmen.
  • Sie dürfen verification_url in keiner Weise ändern, außer um das Schema optional für die Anzeige zu entfernen. Wenn Sie das Schema (z.B. https://) aus der URL entfernen möchten, um sie besser darstellen zu können, muss Ihre App sowohl die Varianten http als auch https unterstützen.

Schritt 4: Google-Autorisierungsserver abfragen

Da der Nutzer ein separates Gerät verwendet, um zur verification_url zu navigieren und den Zugriff zu gewähren oder zu verweigern, wird das anfragende Gerät nicht automatisch benachrichtigt, wenn der Nutzer auf die Zugriffsanfrage reagiert. Aus diesem Grund muss das anfragende Gerät den Autorisierungsserver von Google abfragen, um festzustellen, wann der Nutzer auf die Anfrage reagiert hat.

Das anfragende Gerät sollte weiterhin Polling-Anfragen senden, bis es eine Antwort erhält, die angibt, dass der Nutzer auf die Zugriffsanfrage reagiert hat, oder bis die in Schritt 2 erhaltenen device_code und user_code abgelaufen sind. Der in Schritt 2 zurückgegebene interval gibt die Wartezeit in Sekunden zwischen Anfragen an.

Die URL des abzufragenden Endpunkts ist https://oauth2.googleapis.com/token. Die Polling-Anfrage enthält die folgenden Parameter:

Beispiele

Das folgende Snippet zeigt eine Beispielanfrage:

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Dieses Beispiel zeigt einen curl-Befehl zum Senden derselben Anfrage:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Schritt 5: Nutzer antwortet auf Zugriffsanfrage

Das folgende Bild zeigt eine Seite, die der Seite ähnelt, die Nutzer sehen, wenn sie zu der verification_url navigieren, die Sie in Schritt 3 angezeigt haben:

Nachdem der Nutzer die user_code eingegeben und sich bei Google angemeldet hat (falls er noch nicht angemeldet war), wird ihm ein Einwilligungsbildschirm wie der unten gezeigte angezeigt:

Schritt 6: Antworten auf Umfrageanfragen verarbeiten

Der Autorisierungsserver von Google antwortet auf jede Abfrageanfrage mit einer der folgenden Antworten:

Zugriff gewährt

Wenn der Nutzer den Zugriff auf das Gerät gewährt hat (indem er auf dem Einwilligungsbildschirm auf Allow geklickt hat), enthält die Antwort ein Zugriffstoken und ein Aktualisierungstoken. Mit den Tokens kann Ihr Gerät im Namen des Nutzers auf Google APIs zugreifen. Das Attribut scope in der Antwort bestimmt, auf welche APIs das Gerät zugreifen kann.

In diesem Fall enthält die API-Antwort die folgenden Felder:

Das folgende Snippet zeigt eine Beispielantwort:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Zugriffstokens haben eine begrenzte Lebensdauer. Wenn Ihre Anwendung über einen längeren Zeitraum Zugriff auf eine API benötigt, kann sie das Aktualisierungstoken verwenden, um ein neues Zugriffstoken zu erhalten. Wenn Ihre Anwendung diese Art von Zugriff benötigt, sollte sie das Aktualisierungstoken für die spätere Verwendung speichern.

Zugriff verweigert

Wenn der Nutzer den Zugriff auf das Gerät verweigert, hat die Serverantwort den HTTP-Antwortstatuscode 403 (Forbidden). Die Antwort enthält den folgenden Fehler:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Autorisierung ausstehend

Wenn der Nutzer den Autorisierungsvorgang noch nicht abgeschlossen hat, gibt der Server den HTTP-Antwortstatuscode 428 (Precondition Required) zurück. Die Antwort enthält den folgenden Fehler:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Zu häufiges Polling

Wenn das Gerät zu häufig Polling-Anfragen sendet, gibt der Server den HTTP-Antwortstatuscode 403 (Forbidden) zurück. Die Antwort enthält den folgenden Fehler:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Weitere Fehler

Der Autorisierungsserver gibt auch Fehler zurück, wenn in der Polling-Anfrage erforderliche Parameter fehlen oder ein falscher Parameterwert angegeben ist. Diese Anfragen haben in der Regel den HTTP-Antwortstatuscode 400 (Bad Request) oder 401 (Unauthorized). Dazu gehören:

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 Live Streaming API.

Hinweis: Die YouTube Live Streaming API unterstützt den Dienstkonto-Ablauf nicht. Da es nicht möglich ist, ein Dienstkonto mit einem YouTube-Konto zu verknüpfen, wird bei dem Versuch, Anfragen mit diesem Ablauf zu autorisieren, ein NoLinkedYouTubeAccount-Fehler generiert.

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 liveBroadcasts.list (YouTube Live Streaming API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen Ihr eigenes Zugriffstoken angeben:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&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/liveBroadcasts?access_token=access_token&part=id%2Csnippet&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/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&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 https://www.googleapis.com/auth/calendar.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.

Zulässige Bereiche

Der OAuth 2.0-Vorgang für Geräte wird nur für die folgenden Bereiche unterstützt:

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.