Notice: We're retiring Works with Nest. See the home page for more information.
Google is committed to advancing racial equity for Black communities. See how.
Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

OAuth 2.0-Authentifizierung und -Autorisierung

Die Nest-API verwendet das OAuth 2.0-Protokoll zur Authentifizierung und Autorisierung.

Bevor Ihr Produkt über die Nest-API auf private Daten zugreifen kann, muss es ein Zugriffstoken erhalten, das den Zugriff auf diese API gewährt. Ein einzelnes Zugriffstoken kann mehreren Abschnitten der API unterschiedlich viel Zugriff gewähren.

Die Autorisierungssequenz beginnt, wenn Ihr Produkt einen Browser zu einer Nest-URL mit Abfrageparametern umleitet, die den angeforderten Zugriff angeben. Nest übernimmt die Benutzerauthentifizierung, Sitzungsauswahl und Benutzereinwilligung. Das Ergebnis ist ein Autorisierungscode, den Ihr Produkt gegen ein Zugriffstoken eintauschen kann. Ihr Produkt kann dann das Zugriffstoken verwenden, um Aufrufe an die Nest-API zu tätigen.

OAuth 2.0 Flow
OAuth 2.0 Flow

Konfigurieren Sie Ihren Works with Nest-Client

Überprüfen Sie die Registerkarte Übersicht auf der Client-Seite, um die OAuth 2.0-Anmeldeinformationen für Ihren Client zu ermitteln.

URI oder PIN-basierte Autorisierung umleiten?

Wenn Sie Ihren Client konfigurieren, werden Sie aufgefordert, einen Umleitungs-URI einzugeben oder die Felder für den Umleitungs-URI leer zu lassen, um die PIN-basierte Autorisierung zu verwenden.

Wenn es sich bei Ihrem Produkt um ein Gerät handelt, dem keine App oder Webseite zugeordnet ist (z. B. ein Fitness-Tracker, eine Appliance oder ein Sicherheitspanel), lassen Sie die Felder URI umleiten leer.

Wenn Ihr Produkt über eine Browserkomponente verfügt, empfiehlt es sich, einen Umleitungs-URI einzuschließen.

Berechtigungen anfordern

Die Client-Konfiguration enthält eine Reihe von Berechtigungen (auch als Bereiche bezeichnet). Eine Berechtigung ist ein variabler Parameter, der die Ressourcen und Operationen steuert, die ein Zugriffstoken zulässt. Es ist im Allgemeinen eine bewährte Methode, Berechtigungen schrittweise anzufordern, wenn der Zugriff erforderlich ist, und nicht im Voraus.

Ergebnis

Wenn Sie die Konfiguration speichern, wird Ihrem Client eine eindeutige Client-ID und ein Client-Geheimnis zugewiesen. Zusätzlich wird Ihrem Kunden eine Autorisierungs-URL zugewiesen.

Die Autorisierungs-URL enthält einen Statusparameter, mit dem Sie mögliche CSRF-Angriffe (Cross-Site Request Forgery) testen können. Siehe Test auf CSRF-Angriffe .

OAuth Details

Fordern Sie einen Autorisierungscode an

Nachdem Ihr Client konfiguriert wurde, können Sie einen Autorisierungscode anfordern (manchmal auch als PIN-Code bezeichnet). Der Autorisierungscode ist nicht das letzte Token, mit dem Sie Nest anrufen. Es wird im nächsten Schritt des OAuth 2.0-Flows verwendet, um es gegen ein tatsächliches Zugriffstoken auszutauschen. Dieser Schritt bietet dem Benutzer direkt von Nest die Gewissheit, dass die Berechtigung für das richtige Produkt mit dem vereinbarten Zugriff erteilt wird.

Die Benutzererfahrung

Wir präsentieren eine Works with Nest-Seite, auf der der Benutzer aufgefordert wird, Zugriff auf Ihr Produkt zu gewähren. Dies identifiziert Ihr Produkt und beschreibt die bestimmten Benutzerberechtigungen (Bereiche), die Ihr Produkt angefordert hat. Die Wörter auf dem Bildschirm stammen aus Ihrer Client-Konfiguration.

Um dies selbst zu testen, laden Sie die Autorisierungs-URL aus Schritt 1 in einen Browser. Sie sollten eine Seite mit Works with Nest-Zugriffsanfragen sehen:

Arbeitet mit Nest

Klicken Sie selbst auf [AKZEPTIEREN], um zu sehen, was der Benutzer sieht. Durch Klicken auf die Schaltfläche [AKZEPTIEREN] genehmigt der Benutzer die Anforderung Ihres Produkts, auf seine Daten zuzugreifen.

PIN-Erfahrung

Wenn Sie die Felder für den Umleitungs-URI in Ihrer Client-Konfiguration leer lassen, wird der Benutzer auf eine Nest-Seite umgeleitet, auf der eine PIN (Autorisierungscode) angezeigt wird. Die Benutzeroberfläche Ihres Geräts sollte den Benutzer dann auffordern, die PIN manuell einzugeben.

Geheimzahl

URI-Erfahrung umleiten

Wenn Sie einen Umleitungs-URI in Ihre Client-Konfiguration aufnehmen, wird der Benutzer zu einer Seite in Ihrer Cloud (oder zu localhost) umgeleitet, und Nest sendet den Autorisierungscode automatisch an das Gerät des Benutzers.

Test auf CSRF-Angriffe

Bevor Sie den Autorisierungscode akzeptieren, sollte Ihr Produkt sicherstellen, dass der im Statusparameter zurückgegebene Wert mit dem Statuswert Ihrer ursprünglichen Autorisierungsanforderung übereinstimmt. Dies stellt sicher, dass Sie mit dem tatsächlichen Benutzer und nicht mit einem schädlichen Skript zu tun haben. Wenn die Statuswerte nicht übereinstimmen, sollten Sie als Antwort einen 401 Unauthorized HTTP-Fehlercode auslösen.

Ein CSRF-Angriff ist ein Angriff, der einen Endbenutzer dazu zwingt, unerwünschte Aktionen in einer Webanwendung auszuführen, in der er derzeit authentifiziert ist.

CSRF-Angriff
CSRF-Angriff

Um CSRF-Angriffe zu verhindern, empfehlen wir, dass Sie immer einen nicht abschätzbaren state angeben, wenn Sie eine Autorisierung anfordern.

Auf diese Weise kann Ihre Works with Nest-Integration überprüfen, ob die aus der Nest-Cloud erhaltenen Zugriffscodes auf Anforderungen Ihres Produkts und nicht auf ein anderes Produkt reagieren.

Beispiel:

Angenommen, Sie geben in Ihrer Client-Konfiguration den Umleitungs-URI an:

 http://localhost:5000/callback
 

7tvPJiv8StrAqo9IQE9xsJaDso4 , Ihr Client sendet den 7tvPJiv8StrAqo9IQE9xsJaDso4 in der Autorisierungs-URL:

 https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
 

Der Benutzer stimmt der Anfrage zu.

Die Nest-Cloud gibt den Statusparameter als Teil des Umleitungs-URI zurück:

 127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
 

Ihr Produkt erhält diesen Statuswert und sollte so programmiert werden, dass nur Weiterleitungen mit einem überprüfbaren Status akzeptiert werden.

Es gibt mehrere Möglichkeiten, einen nicht erratenen Statusparameter zu generieren. Sie können zufällige Statuswerte aus einem im Speicher befindlichen Wörterbuch oder einem neu berechenbaren Wert bereitstellen. Sie können einen privaten Schlüssel mit einigen leicht überprüfbaren Variablen verwenden, z. B. die Client-ID und ein Sitzungscookie, um einen Hash-Wert zu berechnen. Dies führt zu einem Bytewert, der ohne den privaten Schlüssel schwer zu erraten ist. Ein weiterer Vorschlag ist, das aktuelle Datum und die aktuelle Uhrzeit zu hashen. Bei diesem Ansatz muss Ihre Anwendung die Übertragungszeit sparen, um sie zu überprüfen, oder eine verschiebbare Gültigkeitsdauer zulassen (z. B. mithilfe des zeitbasierten Einmalkennwortalgorithmus [TOTP]).

Nach der Berechnung des Keyed-Hash-Message-Authentifizierungscodes (HMAC) codiert Base-64 ihn und übergibt ihn als Statusparameter an die Nest-Cloud.

Hier ist ein Python-Beispiel, das datetime :

 import base64
import datetime
import hmac
import hashlib

def generate_state_parameter(client_id, private_key):
    date = datetime.datetime.today()
    raw_state = str(date) + client_id
    hashed = hmac.new(private_key, raw_state, hashlib.sha1)
    state = base64.b64encode(hashed.digest())
    return (state, date)
 

Autorisierungscode-Fehlermeldungen

Wenn die Autorisierungscode-Anforderung fehlschlägt, wird den Benutzern eine Fehlermeldung angezeigt. Weitere Informationen zu diesen Nachrichten und deren Verhinderung finden Sie in der Autorisierungsreferenz .

Exchange-Autorisierungscode für ein Zugriffstoken

Der letzte Schritt beim Erhalt eines Zugriffstokens besteht darin, dass Ihr Produkt unter Verwendung des soeben erworbenen Autorisierungscodes nach einem solchen fragt. Dies erfolgt durch eine HTTP-POST-Anforderung "x-www-form-urlencoded".

Nehmen Sie die folgenden Parameter in die Anfrage auf. Alle vier Parameter sind erforderlich.

Parameter Beschreibung
Kunden ID Die Client-ID in Schritt 1
client_secret Das Kundengeheimnis in Schritt 1
Code Der in Schritt 2 erhaltene Autorisierungscode
grant_type Der Wert dieses Feldes sollte immer sein: authorization_code

Holen Sie sich vor jedem POST-Aufruf einen neuen Autorisierungscode. Laden Sie dazu Ihre Autorisierungs-URL neu. Dann wird der POST ändern code Parameter den neuen Autorisierungscode enthalten.

Codebeispiele (auth)

Siehe Beispiele in verschiedenen Sprachen .

Postbotenbeispiel (auth)

Postman bietet eine einfache Möglichkeit, OAuth-Anfragen zu testen.

Stellen Sie auf der Registerkarte Header sicher, dass Content-Type = application/x-www-form-urlencoded .

POST-Header zum Abrufen des Zugriffstokens

Fügen Sie auf der Registerkarte Body den folgenden Schlüssel ein: Wertepaare.

POST-Body, um Zugriffstoken zu erhalten

Zugriff auf Token-Antwort

Eine erfolgreiche Anforderung gibt ein JSON-Objekt zurück, das die folgenden Felder enthält:

  • access_token - Das Zugriffstoken für den Benutzer. Dieser Wert muss sicher aufbewahrt werden.
  • expires_in - Die Anzahl der verbleibenden Sekunden ab dem Zeitpunkt der Anforderung, bevor das Token abläuft.

Zugriff auf Token-Fehlermeldungen

Wenn die Anforderung fehlschlägt, erhalten Sie einen Fehler in Form eines HTTP-Statuscodes. Weitere Informationen zu diesen Fehlern und deren Vermeidung finden Sie in der Autorisierungsreferenz .

Stellen Sie authentifizierte Anfragen

Nachdem ein Produkt ein Zugriffstoken erhalten hat, sendet es das Token an eine Nest-API in einem HTTP-Autorisierungsheader. Es ist möglich, Token als URI-Abfragezeichenfolgenparameter zu senden, wir empfehlen dies jedoch nicht, da URI-Parameter in Protokolldateien enden können, die nicht vollständig sicher sind.

Zugriffstoken sind nur für die im Bereich der Tokenanforderung beschriebenen Vorgänge und Ressourcen gültig. Wenn beispielsweise ein Zugriffstoken für die Nest-Thermostat-API ausgestellt wird, wird kein Zugriff auf die Nest-Kamera-API gewährt.

Codebeispiele (Lesen / Schreiben)

Postbotenbeispiel (Lesen / Schreiben)

Postman bietet eine einfache Möglichkeit, API-Aufrufe mit Content-Type = application/json zu testen.

GET, um Daten zu lesen

Ungültige Token

Wenn Sie einen API-Aufruf mit einem ungültigen Token ausführen, erhalten Sie vom Server eine nicht autorisierte Antwort zurück. Ein Token kann ungültig sein und muss neu generiert werden, weil:

  • Es ist abgelaufen
  • Der Benutzer hat die Berechtigung widerrufen, die er ursprünglich für Ihr Produkt erteilt hat

Es ist wichtig, dass Sie Ihr Produkt so codieren, dass ein nicht autorisierter 401-Fehler ordnungsgemäß behandelt wird, indem Sie den Benutzer zum Start des Autorisierungsworkflows zurückleiten.

Funktioniert mit geschlossener Nest-Verbindung

Wenn ein Benutzer eine Works with Nest-Verbindung entfernt , erhält Ihr Produkt ein auth_revoked Ereignis und die Verbindung wird geschlossen.