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

In diesem Dokument wird beschrieben, wie Sie die OAuth 2.0-Autorisierung implementieren, um über Anwendungen auf Geräten wie Fernsehern, Spielekonsolen und Druckern auf Google APIs 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.

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. So kann eine TV-Anwendung 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 Apps keine Geheimnisse wahren können. Sie können auf Google APIs zugreifen, während der Nutzer in der App ist oder 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 Desktop-Anwendungen. Sie sollten diesen Ablauf auch dann verwenden, wenn es sich bei Ihrer App um ein Befehlszeilentool ohne grafische Benutzeroberfläche handelt.

Wenn du Nutzer nur mit ihren Google-Konten anmelden und ein JWT-ID-Token verwenden möchtest, um grundlegende Nutzerprofilinformationen abzurufen, lies den Hilfeartikel Anmeldung auf Fernsehern und Geräten mit eingeschränkter Eingabe.

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. In der API Library finden Sie alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie die Suchfunktion verwenden oder in der zugehörigen Produktfamilie auf Alle ansehen klicken.
4. Wählen Sie die gewünschte API aus und klicken Sie dann auf die Schaltfläche Aktivieren.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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. Wählen Sie den Anwendungstyp Fernseher 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

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.

Eine Liste der zulässigen Bereiche für installierte Apps oder Geräte finden Sie unter Zulässige Bereiche.

OAuth 2.0-Zugriffstokens abrufen

Auch wenn Ihre 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 Autorisierungsvorgang 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 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 anderen Gerät eingeben kann, um Ihre App zu autorisieren.
4. Ihre Anwendung beginnt, den Autorisierungsserver von Google zu pollen, um festzustellen, ob der Nutzer Ihre App autorisiert hat.
5. Der Nutzer wechselt zu einem Gerät mit erweiterten 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 Abfrageanfrage 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 ausführlich beschrieben. Aufgrund der Vielzahl von Funktionen und Laufzeitumgebungen, die Geräte haben können, wird in den Beispielen in diesem Dokument das curl-Befehlszeilen-Dienstprogramm verwendet. Diese Beispiele sollten sich leicht in 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 und die Zugriffsbereiche angegeben sind, auf die Ihre Anwendung im Namen des Nutzers zugreifen möchte. Diese URL solltest du mit dem Metadatenwert device_authorization_endpoint aus dem Discovery-Dokument 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=email%20profile

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

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

Schritt 2: Autorisierungsserverantwort 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 Eigenschaften:

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 Sie mit Ihren 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 Anzahl der Anfragen zu reduzieren.

Schritt 3: Nutzercode anzeigen

Zeige dem Nutzer die in Schritt 2 ermittelten Werte verification_url und user_code an. Beide Werte können beliebige druckbare Zeichen aus dem US-ASCII-Zeichensatz enthalten. In den Inhalten, die Sie dem Nutzer anzeigen, sollte er aufgefordert werden, auf einem anderen Gerät die verification_url aufzurufen und die user_code einzugeben.

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

• user_code
  • Das user_code muss in einem Feld angezeigt werden, das 15 Zeichen in W-Größe aufnehmen kann. Wenn Sie den Code WWWWWWWWWWWWWWW also korrekt anzeigen können, ist Ihre Benutzeroberfläche gültig. Wir empfehlen, diesen Stringwert zu verwenden, wenn Sie testen, wie die user_code in Ihrer Benutzeroberfläche angezeigt wird.
  • Bei user_code wird die Groß- und Kleinschreibung berücksichtigt und der Wert 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 das verification_url anzeigen, muss breit genug sein, um einen URL-String mit 40 Zeichen zu verarbeiten.
  • Sie sollten verification_url in keiner Weise ändern, es sei denn, Sie möchten das Darstellungsschema optional entfernen. Wenn Sie das Schema (z.B. https://) aus der URL entfernen möchten, achten Sie darauf, dass Ihre App sowohl http- als auch https-Varianten verarbeiten kann.

Schritt 4: Autorisierungsserver von Google abfragen

Da der Nutzer ein anderes Gerät verwendet, um die verification_url aufzurufen und 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 geantwortet hat.

Das anfragende Gerät sollte weiterhin Abfrageanfragen senden, bis es eine Antwort erhält, die darauf hinweist, dass der Nutzer auf die Zugriffsanfrage reagiert hat, oder bis device_code und user_code abgelaufen sind, die in Schritt 2 abgerufen wurden. Die in Schritt 2 zurückgegebene interval gibt die Zeit in Sekunden an, die zwischen den Anfragen gewartet werden soll.

Die URL des Endpunkts, der abgefragt werden soll, lautet https://oauth2.googleapis.com/token. Die Abfrageanfrage 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

Auf der folgenden Abbildung ist eine Seite zu sehen, 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 ggf. bei Google angemeldet hat, wird ein Einwilligungsbildschirm wie der unten gezeigte angezeigt:

Schritt 6: Antworten auf Abfrageanfragen verarbeiten

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

Zugriff gewährt

Wenn der Nutzer 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 auf eine API zugreifen muss, kann sie das Aktualisierungstoken verwenden, um ein neues Zugriffstoken zu erhalten. Wenn Ihre Anwendung diese Art von Zugriff benötigt, sollte sie das Aktualisierungstoken zur späteren Verwendung speichern.

Zugriff verweigert

Wenn der Nutzer den Zugriff auf das Gerät verweigert, enthält die Serverantwort den HTTP-Statuscode 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-Statuscode 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 Abfrageanfragen sendet, gibt der Server einen 403-HTTP-Antwortstatuscode (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 Parameter einen falschen Wert hat. 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 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 können Sie mit einer Clientbibliothek Aufrufe von Google APIs einrichten, z. B. beim Aufrufen der Drive Files API.

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

Beispiele für HTTP-GET

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

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

Alternativ können Sie auch die Option „Abfragestringparameter“ verwenden:

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

Die Anzahl der ausgestellten Aktualisierungstokens ist begrenzt. Es gibt ein Limit pro Kombination aus Kunde und Nutzer sowie ein Limit pro Nutzer für alle Kunden. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann es zu diesen Limits kommen. 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, dass eine Anwendung den ihr gewährten Zugriff programmatisch widerruft. 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 Entfernungsvorgangs kann eine API-Anfrage umfassen, um sicherzustellen, dass die zuvor der Anwendung erteilten 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 Zugriffs- oder 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.

Zulässige Bereiche

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