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

In diesem Dokument wird die Implementierung der OAuth 2.0-Autorisierung für den Zugriff auf Google APIs über Anwendungen erläutert, die auf Geräten wie Fernsehern, Spielekonsolen und Druckern ausgeführt werden. Dieser Ablauf ist für Geräte gedacht, die entweder keinen Zugriff auf einen Browser oder nur begrenzte Eingabemöglichkeiten haben.

OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise könnte eine TV-Anwendung OAuth 2.0 verwenden, um die Berechtigung zur Auswahl einer auf Google Drive gespeicherten Datei zu erhalten.

Da die Anwendungen, die diesen Ablauf verwenden, an einzelne Geräte verteilt sind, wird davon ausgegangen, dass die Anwendungen keine Secrets behalten dürfen. Sie können auf Google APIs zugreifen, während der Nutzer die App verwendet 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 universellen Windows-Plattform) schreiben, die Zugriff auf den Browser und vollständige Eingabefunktionen hat, verwenden Sie den OAuth 2.0-Vorgang für mobile und Desktopanwendungen. Sie sollten diesen Ablauf auch dann verwenden, wenn Ihre Anwendung ein Befehlszeilentool ohne grafische Benutzeroberfläche ist.

Wenn Sie nur Nutzer mit ihren Google-Konten anmelden und ein JWT-ID-Token verwenden möchten, um grundlegende Nutzerprofilinformationen abzurufen, lesen Sie die Informationen unter Anmeldung auf Fernsehern und eingeschränkten Eingabegeräten.

Voraussetzungen

Die APIs für Ihr Projekt aktivieren

Jede Anwendung, die Google APIs aufruft, muss diese APIs in 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. In API Library sind alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert aufgeführt. Wenn die gewünschte API nicht in der Liste aufgeführt ist, suchen Sie sie oder klicken Sie in der zugehörigen Produktfamilie auf Alle ansehen.
  4. Wählen Sie die API aus, die Sie aktivieren möchten, und klicken Sie 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

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss über Autorisierungsanmeldedaten verfügen, 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 App-Typ Fernseher und Geräte mit begrenzter Eingabe aus.
  4. Benennen Sie Ihren OAuth 2.0-Client und klicken Sie auf Erstellen.

Zugriffsbereiche identifizieren

Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann es eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit des Einholens der Nutzereinwilligung geben.

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

Informationen zu installierten Apps oder Geräten finden Sie in der Liste Zulässige Bereiche.

OAuth 2.0-Zugriffstokens abrufen

Auch wenn Ihre Anwendung auf einem Gerät mit eingeschränkten Eingabemöglichkeiten ausgeführt wird, benötigen Nutzer einen separaten Zugriff auf ein Gerät mit umfassenderen Eingabefunktionen, um diesen Autorisierungsvorgang abzuschließen. Der Ablauf besteht aus den folgenden Schritten:

  1. Ihre Anwendung sendet eine Anfrage an den Autorisierungsserver von Google, die die Bereiche identifiziert, für die Ihre Anwendung die Zugriffsberechtigung anfordert.
  2. Der Server antwortet mit mehreren Informationen, die in den nachfolgenden Schritten verwendet werden, z. B. einem Gerätecode und einem Nutzercode.
  3. Es werden Informationen angezeigt, die der Nutzer auf einem separaten Gerät eingeben kann, um deine App zu autorisieren.
  4. Ihre Anwendung beginnt mit dem Abfragen des Autorisierungsservers von Google, um festzustellen, ob der Nutzer Ihre Anwendung autorisiert hat.
  5. Der Nutzer wechselt zu einem Gerät mit umfassenderen Eingabefunktionen, 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 Zugriff auf Ihre Anwendung gewähren oder verweigern.
  6. Die nächste Antwort auf Ihre Abfrageanfrage enthält die Tokens, die Ihre Anwendung 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 folgende Abbildung 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 erläutert. Angesichts der Bandbreite von Funktionen und Laufzeitumgebungen, die Geräte haben können, wird für die in diesem Dokument gezeigten Beispiele das Befehlszeilendienstprogramm curl verwendet. Diese Beispiele sollten einfach in verschiedene Sprachen und Laufzeiten portiert werden können.

Schritt 1: Geräte- und Nutzercodes anfordern

In diesem Schritt sendet dein Gerät eine HTTP-POST-Anfrage an den Autorisierungsserver von Google unter https://oauth2.googleapis.com/device/code. Diese Anfrage identifiziert deine Anwendung sowie die Zugriffsbereiche, auf die deine Anwendung im Namen des Nutzers zugreifen möchte. Rufen Sie diese URL mithilfe des Metadatenwerts device_authorization_endpoint aus dem Discovery-Dokument ab. Geben Sie die folgenden HTTP-Anfrageparameter an:

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der 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 beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Informationen zu installierten Apps oder Geräten finden Sie in der Liste Zulässige Bereiche.

Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs auf Ihre Anwendung steuern. Daher besteht eine umgekehrte Beziehung 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: Antwort des Autorisierungsservers verarbeiten

Der Autorisierungsserver gibt eine der folgenden Antworten zurück:

Erfolgsantwort

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

Attribute
device_code Ein Wert, den Google eindeutig zuweist, um das Gerät zu identifizieren, auf dem die Autorisierungsanwendung ausgeführt wird. Der Nutzer autorisiert dieses Gerät von einem anderen Gerät mit umfassenderen Eingabefunktionen. Beispielsweise kann ein Nutzer 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.

Mit diesem Code kann das Gerät, auf dem die App ausgeführt wird, auf sichere Weise feststellen, ob der Nutzer den Zugriff gewährt oder verweigert hat.
expires_in Die Gültigkeitsdauer von device_code und user_code in Sekunden. Wenn der Nutzer in dieser Zeit den Autorisierungsvorgang nicht abschließt und dein Gerät keine Informationen zur Entscheidung des Nutzers abfragt, musst du diesen Prozess unter Umständen ab Schritt 1 neu starten.
interval Die Zeit 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 Abfrageanfrage an den Autorisierungsserver von Google senden. Weitere Informationen finden Sie in Schritt 3.
user_code Ein Wert unter Beachtung der Groß- und Kleinschreibung, der für Google die Bereiche identifiziert, für die die Anwendung Zugriff anfordert. Die Benutzeroberfläche weist den Nutzer an, diesen Wert auf einem separaten Gerät mit umfassenderen Eingabefunktionen einzugeben. Google verwendet diesen Wert dann, um den richtigen Bereich von Bereichen anzuzeigen, wenn der Nutzer aufgefordert wird, Zugriff auf Ihre Anwendung zu gewähren.
verification_url Eine URL, die der Nutzer auf einem separaten Gerät aufrufen muss, um die user_code einzugeben und den Zugriff auf Ihre Anwendung zu gewähren oder zu verweigern. Dieser Wert wird ebenfalls 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 zu Kontingentüberschreitung

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

Zeige dem Nutzer die in Schritt 2 abgerufenen 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 anzeigen lässt, sollte den Nutzer anweisen, auf einem anderen Gerät zum verification_url zu gehen und den user_code einzugeben.

Entwerfen Sie Ihre Benutzeroberfläche (UI) unter Berücksichtigung der folgenden Regeln:

  • user_code
    • user_code muss in einem Feld angezeigt werden, das 15 W-Zeichen verarbeiten kann. Mit anderen Worten: Wenn Sie den Code WWWWWWWWWWWWWWW korrekt anzeigen können, ist Ihre UI gültig. Wir empfehlen, diesen Stringwert zu verwenden, wenn Sie testen, wie user_code in der UI angezeigt wird.
    • Bei user_code wird zwischen Groß- und Kleinschreibung unterschieden und es sollte in keiner Weise geändert werden, z. B. durch Ändern der Groß-/Kleinschreibung oder Einfügen anderer Formatierungszeichen.
  • verification_url
    • Der Bereich, in dem verification_url angezeigt wird, muss so breit sein, dass ein URL-String mit 40 Zeichen verarbeitet werden kann.
    • Sie sollten verification_url in keiner Weise ändern, außer um das Anzeigeschema optional zu entfernen. Wenn du vorhast, das Schema (z.B. https://) aus Anzeigegründen aus der URL zu entfernen, achte darauf, dass deine App sowohl http- als auch https-Varianten verarbeiten kann.

Schritt 4: Autorisierungsserver von Google abfragen

Da der Nutzer ein separates Gerät verwendet, um verification_url aufzurufen und Zugriff zu gewähren oder zu verweigern, wird das anfordernde 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 geantwortet hat.

Das anfragende Gerät sollte so lange Abfrageanfragen senden, bis es eine Antwort erhält, dass der Nutzer auf die Zugriffsanfrage geantwortet hat, oder bis die in Schritt 2 abgerufenen device_code und user_code abgelaufen sind. Der in Schritt 2 zurückgegebene interval gibt die Zeit in Sekunden an, die zwischen Anfragen gewartet werden soll.

Die URL des abzufragenden Endpunkts 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 in der API Console Credentials page.
client_secret Der Clientschlüssel für die angegebene client_id. Sie finden diesen Wert in der API Console Credentials page.
device_code Die device_code, die in Schritt 2 vom Autorisierungsserver 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

Die folgende Abbildung zeigt eine ähnliche Seite wie die Seite, die Nutzer sehen, wenn sie das in Schritt 3 angezeigte verification_url aufrufen:

Gerät durch Eingabe eines Codes verbinden

Nachdem der Nutzer user_code eingegeben und sich bei Google angemeldet hat, wird ein Zustimmungsbildschirm wie der folgende 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 durch Klicken auf Allow auf dem Zustimmungsbildschirm Zugriff auf das Gerät gewährt 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 zum Autorisieren einer Google API-Anfrage sendet.
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. Für Geräte werden immer Aktualisierungstokens zurückgegeben.
scope Die durch access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten Strings unter Beachtung der Groß- und Kleinschreibung.
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 Zugriff auf eine API benötigt, kann sie das Aktualisierungstoken verwenden, um ein neues Zugriffstoken abzurufen. 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-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 Statuscode 428 der HTTP-Antwort (Precondition Required) zurück. Die Antwort enthält den folgenden Fehler:

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

Zu häufige Abfrage

Wenn das Gerät zu häufig Abfrageanfragen 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 dann Fehler zurück, wenn in der Abfrageanfrage erforderliche Parameter fehlen oder ein falscher Parameterwert vorhanden ist. Diese Anfragen haben normalerweise den HTTP-Antwortstatuscode 400 (Bad Request) oder 401 (Unauthorized). Zu diesen Fehlern gehören:

Fehler HTTP-Statuscode Beschreibung
admin_policy_enforced 400 Das Google-Konto kann einen oder mehrere angeforderte Bereiche aufgrund der Richtlinien seines Google Workspace-Administrators nicht autorisieren. Im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten steuern finden Sie weitere Informationen dazu, wie ein Administrator den Zugriff auf Bereiche einschränken kann, bis der Zugriff für Ihre OAuth-Client-ID explizit gewährt wurde.
invalid_client 401

Der OAuth-Client wurde nicht gefunden. Dieser Fehler tritt beispielsweise auf, wenn der Wert des Parameters client_id ungültig ist.

Der OAuth-Clienttyp ist falsch. Achte darauf, dass der Anwendungstyp für die Client-ID auf Fernseher und Geräte mit begrenzter Eingabe festgelegt ist.
invalid_grant 400 Der Parameterwert code ist ungültig, wurde bereits beansprucht oder kann nicht geparst werden.
unsupported_grant_type 400 Der Wert des Parameters 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 Nutzertypkonfiguration für Ihre OAuth-Anwendung.

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, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein. Dazu fügen Sie entweder einen access_token-Abfrageparameter oder den Bearer-Wert eines Authorization-HTTP-Headers ein. Der HTTP-Header ist nach Möglichkeit zu bevorzugen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie Aufrufe an Google APIs mithilfe einer Clientbibliothek einrichten, z. B. beim Aufrufen der Drive Files API.

Du kannst alle Google APIs testen und ihre Bereiche im OAuth 2.0 Playground ansehen.

HTTP GET-Beispiele

Ein Aufruf an den Endpunkt drive.files (die 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. Im folgenden Beispiel wird die HTTP-Header-Option (bevorzugt) verwendet:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternativ können Sie die Parameteroption des Abfragestrings 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 dass der Nutzer um eine Berechtigung gebeten wird (auch wenn der Nutzer nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

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

Felder
client_id Die vom API Consoleabgerufene Client-ID.
client_secret Der vom API Consoleabgerufene Clientschlüssel.
grant_type Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Felds auf refresh_token festgelegt werden.
refresh_token Das vom Austausch des Autorisierungscodes zurückgegebene Aktualisierungstoken.

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

Die Anzahl der ausgegebenen Aktualisierungstokens ist begrenzt: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens langfristig aufbewahren und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits überschritten werden. Ältere Aktualisierungstokens funktionieren in diesem Fall nicht mehr.

Token widerrufen

Manchmal möchte ein Nutzer den Zugriff einer App widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument Website- oder App-Zugriff entfernen auf Websites und Apps von Drittanbietern mit Zugriff auf dein Konto.

Eine Anwendung kann den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer das Abo kündigt, 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 beinhalten, mit der sichergestellt wird, dass die zuvor der Anwendung gewährten Berechtigungen entfernt werden.

Zum programmatischen Widerrufen eines Tokens sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und nimmt das Token als Parameter auf:

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 es sich bei dem Token um ein Zugriffstoken handelt und es über ein entsprechendes Aktualisierungstoken verfügt, wird auch das Aktualisierungstoken widerrufen.

Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Für Fehlerbedingungen wird der 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:

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