In diesem Dokument wird die OAuth 2.0-Autorisierung für den Zugriff auf die YouTube Data API über Anwendungen wie Fernseher, Spielekonsolen und Drucker implementiert. Genauer gesagt ist dieser Ablauf für Geräte vorgesehen, die entweder keinen Zugriff auf einen Browser oder eingeschränkte Eingabefunktionen haben.
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. Eine TV-App könnte beispielsweise OAuth 2.0 verwenden, um die Berechtigung zur Auswahl einer Datei abzurufen, die in Google Drive gespeichert ist.
Da die Anwendungen, die diesen Ablauf verwenden, an 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 sich der Nutzer in der App befindet oder diese 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) mit Zugriff auf den Browser und vollständigen Eingabefunktionen schreiben, 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 du nur Nutzer mit ihren Google-Konten anmelden und mithilfe eines JWT-ID-Tokens grundlegende Nutzerprofilinformationen abrufen möchtest, findest du weitere Informationen unter Anmeldung auf Fernsehern und Geräten mit begrenzter Eingabe.
Voraussetzungen
Die APIs für Ihr Projekt aktivieren
Jede Anwendung, die Google APIs aufruft, muss diese APIs im API Consoleaktivieren.
So aktivieren Sie eine API für Ihr Projekt:
- Open the API Library in Google API Console.
- If prompted, select a project, or create a new one.
- Auf der Seite „Mediathek“ kannst du die YouTube Data API finden und aktivieren. Suchen Sie nach weiteren APIs, die Ihre Anwendung verwenden wird, und aktivieren Sie diese ebenfalls.
Anmeldedaten für die Autorisierung erstellen
Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, benötigt Autorisierungsanmeldedaten, 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 das Projekt aktiviert haben.
- Go to the Credentials page.
- Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
- Wählen Sie den Anwendungstyp Fernseher und Geräte mit begrenzter Eingabe aus.
- Benennen Sie Ihren OAuth 2.0-Client und klicken Sie auf Erstellen.
Zugriffsbereiche identifizieren
Mit Bereichen kann Ihre Anwendung nur Zugriff auf die benötigten Ressourcen anfordern und Nutzer können gleichzeitig den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen, bestehen.
Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, auf die Ihre Anwendung eine Zugriffsberechtigung benötigt.
Für Version 3 der YouTube Data API werden die folgenden Umfänge verwendet:
| Sucher | |
|---|---|
| https://www.googleapis.com/auth/youtube | YouTube-Konto verwalten |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | Eine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen |
| https://www.googleapis.com/auth/youtube.force-ssl | Ihre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen |
| https://www.googleapis.com/auth/youtube.readonly | YouTube-Konto abrufen |
| https://www.googleapis.com/auth/youtube.upload | YouTube-Videos verwalten |
| https://www.googleapis.com/auth/youtubepartner | Ihre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten |
| https://www.googleapis.com/auth/youtubepartner-channel-audit | Private Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind |
Installierte Apps oder Geräte finden Sie in der Liste Zulässige Bereiche.
OAuth 2.0-Zugriffstokens abrufen
Auch wenn Ihre Anwendung auf einem Gerät mit eingeschränkten Eingabefunktionen ausgeführt wird, müssen Nutzer einen separaten Zugriff auf ein Gerät mit umfassenderen Eingabefunktionen haben, um diesen Autorisierungsvorgang abzuschließen. Der Ablauf umfasst die folgenden Schritte:
- Ihre Anwendung sendet eine Anfrage an den Autorisierungsserver von Google, die die Bereiche identifiziert, für die Ihre Anwendung Zugriffsberechtigungen anfordert.
- Der Server antwortet mit verschiedenen Informationen, die in den nachfolgenden Schritten verwendet werden, z. B. mit einem Gerätecode und einem Nutzercode.
- Sie zeigen Informationen an, die der Nutzer auf einem separaten Gerät eingeben kann, um Ihre App zu autorisieren.
- Ihre Anwendung beginnt mit der Abfrage des Autorisierungsservers von Google, um festzustellen, ob der Nutzer Ihre Anwendung autorisiert hat.
- Der Nutzer wechselt zu einem Gerät mit umfassenderen Eingabefunktionen, startet einen Webbrowser, ruft die in Schritt 3 angegebene URL auf und gibt einen Code ein, der ebenfalls in Schritt 3 angezeigt wird. Der Nutzer kann dann den Zugriff auf die Anwendung gewähren oder verweigern.
- 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.)
Das folgende Bild veranschaulicht diesen Vorgang:
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 in den Beispielen in diesem Dokument das curl-Befehlszeilendienstprogramm verwendet. Diese Beispiele sollten sich einfach in verschiedene Sprachen und Laufzeiten übertragen 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. Dieser identifiziert Ihre Anwendung und die Zugriffsbereiche, auf die Ihre Anwendung im Namen des Nutzers zugreifen möchte.
Du solltest diese URL mithilfe des Metadatenwerts 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 in der API Console- Credentials page. |
||||||||||||||||
scope |
Erforderlich
Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen könnte. Diese Werte bilden die Grundlage für den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Installierte Apps oder Geräte finden Sie in der Liste Zulässige Bereiche. Mit Bereichen kann Ihre Anwendung nur Zugriff auf die benötigten Ressourcen anfordern und Nutzer können gleichzeitig den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher besteht eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen. Für Version 3 der YouTube Data API werden die folgenden Umfänge verwendet:
Das Dokument OAuth 2.0 API-Bereiche enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können. |
||||||||||||||||
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, erhalten Sie als Antwort ein JSON-Objekt mit den folgenden Attributen:
| Attribute | |
|---|---|
device_code |
Ein Wert, den Google eindeutig zuweist, um das Gerät zu identifizieren, auf dem die App ausgeführt wird, die Autorisierung anfordert. Der Nutzer autorisiert dieses Gerät dann über ein anderes 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 das device_code den Fernseher.
Mit diesem Code kann das Gerät, auf dem die App ausgeführt wird, sicher feststellen, ob der Nutzer Zugriff gewährt oder verweigert hat. |
expires_in |
Die Dauer in Sekunden, die device_code und user_code gültig sind. Wenn der Nutzer in diesem Zeitraum den Autorisierungsvorgang nicht abschließt und dein Gerät keine Informationen zur Entscheidung des Nutzers abfragt, musst du diesen Prozess möglicherweise ab Schritt 1 neu starten. |
interval |
Die Zeit in Sekunden, die Ihr Gerät zwischen den Abfrageanfragen warten soll. Lautet der Wert beispielsweise 5, 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, der gegenüber Google die Bereiche identifiziert, für die die Anwendung Zugriff anfordert. Dabei ist die Groß-/Kleinschreibung zu beachten. Über die Benutzeroberfläche wird der Nutzer angewiesen, 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, zu der der Nutzer auf einem anderen Gerät gehen muss, um die user_code einzugeben und den 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 Ihre Gerätecodeanfragen das Ihrer Client-ID zugeordnete Kontingent überschreiten, erhalten Sie eine 403-Antwort mit folgendem 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 verification_url und user_code aus Schritt 2 an. Beide Werte können beliebige druckbare Zeichen aus dem US-ASCII-Zeichensatz enthalten. Mit dem Inhalt, den du dem Nutzer präsentierst, sollte er aufgefordert werden, auf einem anderen Gerät die verification_url aufzurufen und die user_code einzugeben.
Berücksichtigen Sie beim Entwerfen der Benutzeroberfläche (UI) die folgenden Regeln:
user_code- Die
user_codemuss in einem Feld angezeigt werden, das 15 Zeichen der Größe „W“ verarbeiten kann. Mit anderen Worten: Wenn Sie den CodeWWWWWWWWWWWWWWWkorrekt anzeigen können, ist Ihre UI gültig. Wir empfehlen, diesen Stringwert zu verwenden, wenn Sie testen, wieuser_codein Ihrer UI angezeigt wird. - Bei
user_codewird zwischen Groß- und Kleinschreibung unterschieden und es sollte in keiner Weise geändert werden, zum Beispiel durch Ändern der Groß-/Kleinschreibung oder Einfügen anderer Formatierungszeichen.
- Die
verification_url- Der Bereich, in dem
verification_urlangezeigt wird, muss breit genug sein, um einen URL-String mit 40 Zeichen zu verarbeiten. - Du solltest das
verification_urlin keiner Weise ändern, es sei denn, du kannst optional das Schema für die Anzeige entfernen. Wenn du beabsichtigst, das Schema (z.B.https://) aus Anzeigegründen aus der URL zu entfernen, achte darauf, dass deine App sowohl die Variantenhttpals auchhttpsverarbeiten kann.
- Der Bereich, in dem
Schritt 4: Autorisierungsserver von Google abfragen
Da der Nutzer ein separates 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 so lange Abfrageanfragen senden, bis es eine Antwort erhält, die darauf hinweist, dass der Nutzer auf die Zugriffsanfrage geantwortet hat, oder bis die in
Schritt 2 abgerufenen device_code und user_code abgelaufen sind. Die 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: Der Nutzer antwortet auf die Zugriffsanfrage
Die folgende Abbildung zeigt eine Seite, die der ähnelt, die Nutzer sehen, wenn sie die verification_url aufrufen, die du in Schritt 3 angezeigt hast:
Nach der Eingabe von user_code und der Anmeldung bei Google, sofern nicht bereits angemeldet, wird dem Nutzer ein Zustimmungsbildschirm 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 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 dein 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 für Geräte immer zurückgegeben. |
scope |
Die durch access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten Strings mit 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 die 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 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 HTTP-Antwortstatuscode 428 (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 Fehler zurück, wenn in der Abfrageanfrage erforderliche Parameter fehlen oder ein falscher Parameterwert vorliegt. 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 |
Mindestens ein Bereich kann aufgrund der Richtlinien seines Google Workspace-Administrators nicht mit dem Google-Konto autorisiert werden. Weitere Informationen dazu, wie ein Administrator den Zugriff auf Bereiche einschränken kann, bis der OAuth-Client-ID explizit Zugriff gewährt wird, finden Sie im Hilfeartikel Zugriff externer und interner Apps auf Google Workspace-Daten steuern. |
invalid_client |
401 |
Der OAuth-Client wurde nicht gefunden. Dieser Fehler tritt beispielsweise auf, wenn der Parameterwert 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 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. Prüfen 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, wenn die für die 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-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Nach Möglichkeit ist der HTTP-Header zu empfehlen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du Aufrufe an Google APIs mithilfe einer Clientbibliothek einrichten (z. B. beim Aufrufen der YouTube Live Streaming API).
Beachte, dass die YouTube Live Streaming API den Dienstkontoablauf nicht unterstützt. Da es keine Möglichkeit gibt, ein Dienstkonto mit einem YouTube-Konto zu verknüpfen, wird beim Autorisieren von Anfragen mit diesem Ablauf der Fehler NoLinkedYouTubeAccount ausgelöst.
Im OAuth 2.0 Playground können Sie alle Google APIs ausprobieren und ihre Bereiche ansehen.
Beispiele für HTTP GET
Ein Aufruf des
liveBroadcasts.list-Endpunkts (die YouTube Live Streaming API) über den Authorization: Bearer-HTTP-Header könnte so aussehen. Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Hier sehen Sie einen Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter 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, in dem die HTTP-Header-Option verwendet wird (bevorzugt):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Alternativ können Sie die Parameteroption für den Abfragestring verwenden:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Zugriffstokens aktualisieren
Zugriffstokens laufen in regelmäßigen Abständen ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben, können Sie ein Zugriffstoken aktualisieren, ohne dass der Nutzer um seine Berechtigung gebeten wird (auch wenn der Nutzer nicht anwesend ist).
Zum Aktualisieren eines Zugriffstokens sendet Ihre Anwendung eine HTTPS-POST-Anfrage an den Autorisierungsserver von Google (https://oauth2.googleapis.com/token) mit den folgenden Parametern:
| Felder | |
|---|---|
client_id |
Die Client-ID, die von der API Consoleabgerufen wird. |
client_secret |
Der von API Consoleabgerufene Clientschlüssel. |
grant_type |
Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Felds auf refresh_token festgelegt sein. |
refresh_token |
Das vom Autorisierungscode-Austausch 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"
}
Beachten Sie, dass es Limits für die Anzahl der ausgegebenen Aktualisierungstokens gibt: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens langfristig speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann diese Grenze überschritten werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.
Token widerrufen
In einigen Fällen möchte ein Nutzer den Zugriff auf eine Anwendung widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Supportdokument zu Websites und Apps von Drittanbietern mit Zugriff auf Ihr Konto im Abschnitt Zugriff auf Websites oder Apps entfernen.
Es ist auch möglich, den Zugriff einer Anwendung programmatisch zu widerrufen. Der programmatische Widerruf ist in Fällen wichtig, in denen ein Nutzer das Abo beendet oder 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 umfassen, mit der sichergestellt wird, 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 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-Vorgang für Geräte wird nur für die folgenden Bereiche unterstützt:
OpenID Connect, Google Log-in
emailopenidprofile
Drive-API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly