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:

Der Nutzer meldet sich auf einem separaten Gerät mit einem Browser an.

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:

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert unter API Console Credentials page.
scope Erforderlich

Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte werden auf dem Zustimmungsbildschirm angezeigt, den Google dem Nutzer präsentiert. Eine Liste der zulässigen Bereiche für installierte Apps oder Geräte finden Sie unter Zulässige Bereiche.

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 ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

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:

Attribute
device_code Ein von Google eindeutig zugewiesener Wert, mit dem das Gerät identifiziert wird, auf dem die App ausgeführt wird, für die die Autorisierung angefordert wird. Der Nutzer autorisiert dieses Gerät von einem anderen Gerät mit umfangreicheren Eingabemöglichkeiten. Ein Nutzer kann beispielsweise einen Laptop oder ein Smartphone verwenden, um eine App zu autorisieren, die auf einem Fernseher ausgeführt wird. In diesem Fall identifiziert die device_code den Fernseher.

Anhand dieses Codes kann das Gerät, auf dem die App ausgeführt wird, sicher feststellen, ob der Nutzer den Zugriff gewährt oder abgelehnt hat.
expires_in Die Gültigkeitsdauer von device_code und user_code in Sekunden. Wenn der Nutzer innerhalb dieser Zeit den Autorisierungsvorgang nicht abschließt und Ihr Gerät auch nicht abfragt, um Informationen zur Entscheidung des Nutzers abzurufen, müssen Sie diesen Vorgang möglicherweise von Schritt 1 aus wiederholen.
interval Die Zeitspanne in Sekunden, die Ihr Gerät zwischen Abfrageanfragen warten soll. Wenn der Wert beispielsweise 5 ist, sollte Ihr Gerät alle fünf Sekunden eine Abfrage an den Autorisierungsserver von Google senden. Weitere Informationen finden Sie unter Schritt 3.
user_code Ein groß- und kleinschreibungssensitiver Wert, der Google die Bereiche angibt, für die die Anwendung Zugriff anfordert. Auf Ihrer Benutzeroberfläche wird der Nutzer aufgefordert, diesen Wert auf einem separaten Gerät mit erweiterten Eingabemöglichkeiten einzugeben. Google verwendet den Wert dann, um die richtigen Zugriffsbereiche anzuzeigen, wenn der Nutzer aufgefordert wird, Zugriff auf Ihre Anwendung zu gewähren.
verification_url Eine URL, zu der der Nutzer auf einem anderen Gerät wechseln muss, um die user_code einzugeben und Zugriff auf Ihre Anwendung zu gewähren oder zu verweigern. Dieser Wert wird auch auf der Benutzeroberfläche angezeigt.

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:

Parameter
client_id Die Client-ID für Ihre Anwendung. Sie finden diesen Wert unter API Console Credentials page.
client_secret Der Clientschlüssel für die angegebene client_id. Sie finden diesen Wert unter API Console Credentials page.
device_code Die device_code, die vom Autorisierungsserver in Schritt 2 zurückgegeben wurde.
grant_type Setzen Sie diesen Wert auf urn:ietf:params:oauth:grant-type:device_code.

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:

Gerät durch Eingabe eines Codes verbinden

Nachdem der Nutzer die user_code eingegeben und sich ggf. bei Google angemeldet hat, wird ein Einwilligungsbildschirm wie der unten gezeigte angezeigt:

Beispiel für einen Zustimmungsbildschirm für einen Geräteclient

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:

Felder
access_token Das Token, das Ihre Anwendung sendet, um eine Google API-Anfrage zu autorisieren.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
refresh_token Ein Token, mit dem Sie ein neues Zugriffstoken abrufen können. Aktualisierungstokens sind gültig, bis der Nutzer den Zugriff widerruft. Aktualisierungstokens werden immer für Geräte zurückgegeben.
scope Die Zugriffsbereiche, die durch das access_token gewährt werden, als Liste von durch Leerzeichen getrennten, groß- und kleinschreibungssensitiven Strings.
token_type Der Typ des zurückgegebenen Tokens. Derzeit ist der Wert dieses Felds immer auf Bearer festgelegt.

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:

Fehler HTTP-Statuscode Beschreibung
admin_policy_enforced 400 Das Google-Konto kann aufgrund der Richtlinien des Google Workspace-Administrators einen oder mehrere der angeforderten Bereiche nicht autorisieren. Weitere Informationen dazu, wie ein Administrator den Zugriff auf Bereiche einschränken kann, bis der Zugriff Ihrer OAuth-Client-ID ausdrücklich gewährt wird, finden Sie im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten verwalten.
invalid_client 401

Der OAuth-Client wurde nicht gefunden. Dieser Fehler tritt beispielsweise auf, wenn der Parameterwert für client_id ungültig ist.

Der OAuth-Clienttyp ist falsch. Der Anwendungstyp für die Client-ID muss auf Fernseher und Geräte mit begrenzter Eingabe festgelegt sein.
invalid_grant 400 Der Wert des Parameters code ist ungültig, wurde bereits beansprucht oder kann nicht geparst werden.
unsupported_grant_type 400 Der Parameterwert für grant_type ist ungültig.
org_internal 403 Die OAuth-Client-ID in der Anfrage ist Teil eines Projekts, das den Zugriff auf Google-Konten in einer bestimmten Google Cloud-Organisation einschränkt. Bestätigen Sie die Konfiguration des Nutzertyps für Ihre OAuth-Anwendung.

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:

Felder
client_id Die Client-ID, die von der API Consoleabgerufen wurde.
client_secret Der Clientschlüssel, der von der API Consoleabgerufen wurde.
grant_type Gemäß der OAuth 2.0-Spezifikation muss der Wert dieses Felds auf refresh_token gesetzt werden.
refresh_token Das Aktualisierungstoken, das vom Autorisierungscode-Austausch zurückgegeben wird.

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:

OpenID Connect, Google Log-in

  • email
  • openid
  • profile

Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly

Produktübergreifenden Kontoschutz implementieren

Sie sollten außerdem den Kontoübergreifenden Schutz implementieren, indem Sie den Kontoübergreifenden Schutzdienst von Google verwenden. Mit diesem Dienst können Sie Benachrichtigungen zu Sicherheitsereignissen abonnieren, die Ihre Anwendung über wichtige Änderungen am Nutzerkonto informieren. Je nachdem, wie Sie auf Ereignisse reagieren möchten, können Sie dann Maßnahmen ergreifen.

Beispiele für Ereignistypen, die vom geräteübergreifenden Schutzdienst von Google an Ihre App gesendet werden:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Auf der Seite Nutzerkonten mit dem produktübergreifenden Kontoschutz schützen finden Sie weitere Informationen zur Implementierung des produktübergreifenden Kontoschutzes und eine vollständige Liste der verfügbaren Ereignisse.