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

In diesem Dokument wird erläutert, wie Sie die OAuth 2.0-Autorisierung für den Zugriff auf Google APIs mit Anwendungen implementieren, die auf Geräten wie Fernsehern, Spielekonsolen und Druckern ausgeführt werden. Dieser Ablauf ist speziell für Geräte gedacht, 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 einzelne Geräte verteilt werden, wird davon ausgegangen, dass die Anwendungen 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 Nutzer nur mit ihren Google-Konten anmelden und das JWT-ID-Token verwenden möchten, um grundlegende Nutzerprofilinformationen abzurufen, lesen Sie den Hilfeartikel 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 Console aktiviert werden.

So aktivieren Sie eine API für Ihr Projekt:

1. Öffnen Sie die API-Bibliothek in der Google API Console.
2. Wählen Sie ein Projekt aus oder erstellen Sie ein neues, wenn Sie dazu aufgefordert werden.
3. In der API-Bibliothek finden Sie alle verfügbaren APIs, gruppiert nach Produktfamilie und Beliebtheit. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie die Suchfunktion verwenden oder in der Produktfamilie, zu der sie gehört, auf Alle ansehen klicken.
4. Wählen Sie die gewünschte API aus und klicken Sie dann auf den Button Aktivieren.
5. Aktivieren Sie die Abrechnung, wenn Sie dazu aufgefordert werden.
6. Lesen und akzeptieren Sie die Nutzungsbedingungen der API, wenn Sie dazu aufgefordert werden.

Anmeldedaten für die Autorisierung erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss über Autorisierungsdaten verfügen, mit denen sie sich gegenüber dem OAuth 2.0-Server von Google identifiziert. In den folgenden Schritten wird beschrieben, 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. Rufen Sie die Seite „Clients“ auf.
2. Klicken Sie auf Client erstellen.
3. Wählen Sie den Anwendungstyp Fernsehgeräte und Geräte mit begrenzter Eingabe aus.
4. Geben Sie einen Namen für den OAuth 2.0-Client ein und klicken Sie auf Erstellen.

Zugriffsbereiche identifizieren

Mit Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Außerdem können Nutzer so den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Es kann also eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit geben, dass die Nutzereinwilligung erteilt wird.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche ermitteln, für die Ihre App Zugriffsberechtigungen benötigt.

Sehen Sie sich die Liste der zulässigen Bereiche für installierte Apps oder Geräte an.

OAuth 2.0-Zugriffstokens abrufen

Auch wenn deine Anwendung auf einem Gerät mit eingeschränkten Eingabemöglichkeiten ausgeführt wird, müssen Nutzer separaten Zugriff auf ein Gerät mit umfangreicheren Eingabemöglichkeiten haben, 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 sind, für die Ihre Anwendung eine Zugriffsberechtigung anfordert.
2. Der Server antwortet mit mehreren Informationen, die in den folgenden Schritten verwendet werden, z. B. einem Gerätecode und einem Nutzercode.
3. Du zeigst Informationen an, die der Nutzer auf einem separaten Gerät eingeben kann, um deine App zu autorisieren.
4. Ihre Anwendung beginnt, den Autorisierungsserver von Google abzufragen, um festzustellen, ob der Nutzer Ihre Anwendung autorisiert hat.
5. Der Nutzer wechselt zu einem Gerät mit umfangreicheren 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 Abrufanfrage 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 verweigert hat, enthält die Antwort keine Tokens.

Die Abbildung veranschaulicht diesen Vorgang:

In den folgenden Abschnitten werden diese Schritte ausführlich beschrieben. Angesichts der Vielfalt an Funktionen und Laufzeitumgebungen, die Geräte haben können, wird in den Beispielen in diesem Dokument das Befehlszeilen-Dienstprogramm curl verwendet. Diese Beispiele können in verschiedene Sprachen und Laufzeiten portiert werden.

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. Dadurch werden Ihre Anwendung und die Zugriffsbereiche identifiziert, auf die Ihre Anwendung im Namen des Nutzers zugreifen möchte. Sie sollten diese URL mit dem Metadatenwert device_authorization_endpoint aus dem Discovery-Dokument abrufen. Geben Sie die folgenden HTTP-Anfrageparameter an:

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=email%20profile

In diesem Beispiel wird ein curl-Befehl zum Senden derselben Anfrage verwendet:

curl -d "client_id=client_id&scope=email%20profile" \
     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, enthält 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 „Kontingent überschritten“

Wenn Ihre Gerätecodeanfragen 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 Anfragerate zu reduzieren.

Schritt 3: Nutzercode anzeigen lassen

Zeige dem Nutzer die in Schritt 2 erhaltenen Werte für verification_url und user_code an. Beide Werte können beliebige druckbare Zeichen aus dem US-ASCII-Zeichensatz enthalten. Der Inhalt, den du dem Nutzer anzeigst, sollte ihn anweisen, auf einem separaten Gerät die verification_url aufzurufen und den user_code einzugeben.

Beachten Sie beim Entwerfen der Benutzeroberfläche die folgenden Regeln:

• user_code
  • Die user_code muss in einem Feld angezeigt werden, das 15 Zeichen der Größe „W“ aufnehmen kann. Wenn du den Code WWWWWWWWWWWWWWW korrekt anzeigen kannst, ist deine Benutzeroberfläche gültig. Wir empfehlen, diesen Stringwert zu verwenden, wenn du testest, wie der user_code in deiner Benutzeroberfläche angezeigt wird.
  • Bei der user_code wird die Groß- und Kleinschreibung berücksichtigt. Sie darf in keiner Weise geändert werden, z. B. durch Ändern der Groß-/Kleinschreibung oder Einfügen anderer Formatierungszeichen.
• verification_url
  • Der Bereich, in dem Sie die verification_url anzeigen, muss breit genug sein, um einen URL-String mit 40 Zeichen zu verarbeiten.
  • Du solltest die verification_url in keiner Weise ändern, außer um optional das Schema für die Anzeige zu entfernen. Wenn du das Schema (z.B. https://) aus Darstellungsgründen aus der URL entfernen möchtest, muss deine App sowohl die Variante http als auch die Variante https verarbeiten können.

Schritt 4: Autorisierungsserver von Google abfragen

Da der Nutzer ein separates Gerät verwendet, um zu 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 antwortet. 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 Abrufanfragen 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 lautet https://oauth2.googleapis.com/token. Die Abrufanfrage 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

In diesem Beispiel wird ein curl-Befehl zum Senden derselben Anfrage verwendet:

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

Die folgende Abbildung zeigt eine Seite, die der Seite ähnelt, die Nutzer sehen, wenn sie die verification_url aufrufen, die Sie in Schritt 3 angezeigt haben:

Nachdem der Nutzer die user_code eingegeben und sich, falls noch nicht geschehen, bei Google angemeldet hat, wird ein Zustimmungsbildschirm angezeigt:

Schritt 6: Antworten auf Abrufanfragen verarbeiten

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

Zugriff gewährt

Wenn der Nutzer den Zugriff auf das Gerät gewährt hat (durch Klicken auf Allow auf dem Zustimmungsbildschirm), 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 Autorisierungsablauf 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 Abrufanfragen 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 Abfrageanfrage erforderliche Parameter fehlen oder ein falscher Parameterwert vorhanden 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 damit im Namen eines bestimmten Nutzerkontos Aufrufe an eine Google API senden, sofern die von der 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-Suchparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Wenn möglich, ist der HTTP-Header vorzuziehen, da Abfragestrings in Server-Logs sichtbar sein können. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Ihre Aufrufe an Google APIs einzurichten (z. B. beim Aufrufen der Drive Files API).

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

HTTP-GET-Beispiele

Ein Aufruf des Endpunkts drive.files (Drive Files API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:

GET /drive/v2/files 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/drive/v2/files?access_token=access_token

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/drive/v2/files

Oder alternativ die Option für den Abfragestringparameter:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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 Erlaubnis zu bitten (auch wenn der Nutzer nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

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

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&
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 https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Beachten Sie, dass die Anzahl der ausgestellten Aktualisierungstokens begrenzt ist. Es gibt ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und sie so lange verwenden, 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-Widerruf

In einigen Fällen möchte ein Nutzer möglicherweise den Zugriff einer Anwendung widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Supportdokument Drittanbieter-Websites und ‑Apps mit Zugriff auf Ihr Konto im Abschnitt „Zugriff von 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. Das bedeutet, dass ein Teil des Entfernungsprozesses eine API-Anfrage sein kann, um sicherzustellen, 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 das Aktualisierungstoken ebenfalls widerrufen.

Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird ein HTTP-Statuscode 400 zusammen mit einem Fehlercode 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 eine begrenzte Dauer Zugriff auf seine Daten gewähren, um eine Aktion auszuführen. In ausgewählten Google-Produkten ist während des Einwilligungsverfahrens ein zeitbasierter Zugriff verfügbar. Nutzer können damit den Zugriff für einen begrenzten Zeitraum gewähren. Ein Beispiel ist die Data Portability API, die eine einmalige Übertragung von Daten ermöglicht.

Wenn ein Nutzer Ihrer Anwendung zeitbasierten Zugriff gewährt, läuft das Aktualisierungstoken nach der angegebenen Dauer ab. Beachten Sie, dass Aktualisierungstokens unter bestimmten Umständen früher ungültig werden können. Weitere Informationen finden Sie in diesen Fällen. Das Feld refresh_token_expires_in, das in der Antwort auf den Austausch des Autorisierungscodes zurückgegeben wird, stellt in solchen Fällen die verbleibende Zeit bis zum Ablauf des Aktualisierungstokens dar.