Google is committed to advancing racial equity for Black communities. See how.

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 unterschiedliche Zugriffsgrade auf mehrere Abschnitte der API 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, die Sitzungsauswahl und die Zustimmung des Benutzers. 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-Ablauf
OAuth 2.0-Ablauf

Konfigurieren Sie Ihren Works with Nest-Client

Um die OAuth 2.0-Anmeldeinformationen für Ihren Client zu finden, überprüfen Sie die Registerkarte Übersicht der Clientseite.

Umleitungs-URI oder PIN-basierte Autorisierung?

Beim Konfigurieren Ihres Clients werden Sie aufgefordert, einen Umleitungs-URI einzugeben oder die Felder für die Umleitungs-URI leer zu lassen, um die PIN-basierte Autorisierung zu verwenden.

Wenn es sich bei Ihrem Produkt um ein Gerät ohne zugehörige App oder Webseite handelt (z. B. ein Fitnesstracker, eine Appliance oder ein Sicherheitspanel), lassen Sie die Felder für die Weiterleitungs-URI leer.

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

Berechtigungen anfordern

Die Clientkonfiguration umfasst eine Reihe von Berechtigungen (auch als Bereiche bezeichnet). Eine Berechtigung ist ein variabler Parameter, der den Satz von Ressourcen und Operationen steuert, die ein Zugriffstoken zulässt. Es ist im Allgemeinen eine bewährte Methode, Berechtigungen inkrementell 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. Außerdem wird Ihrem Client eine Autorisierungs-URL zugewiesen.

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

OAuth-Details

Fordern Sie einen Autorisierungscode an

Nachdem Ihr Client konfiguriert wurde, können Sie einen Autorisierungscode (manchmal auch als PIN-Code bezeichnet) anfordern. 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 ein tatsächliches Zugriffstoken auszutauschen. Dieser Schritt gibt dem Nutzer 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 Nutzer aufgefordert wird, Zugriff auf Ihr Produkt zu gewähren. Dies identifiziert Ihr Produkt und skizziert die jeweiligen Benutzerberechtigungen (Umfänge), 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 der Zugriffsanfrage für Works with Nest sehen:

Funktioniert mit Nest

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

PIN-Erfahrung

Wenn Sie die Felder für die Weiterleitungs-URI in Ihrer Clientkonfiguration leer lassen, wird der Nutzer 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

Umleitungs-URI-Erfahrung

Wenn Sie eine Weiterleitungs-URI in Ihre Client-Konfiguration aufnehmen, wird der Nutzer zu einer Seite in Ihrer Cloud (oder Ihrem Localhost) umgeleitet und Nest sendet automatisch den Autorisierungscode an das Gerät des Nutzers.

Test auf CSRF-Angriffe

Bevor Sie den Autorisierungscode akzeptieren, sollte Ihr Produkt sicherstellen, dass der im state-Parameter zurückgegebene Wert mit dem state-Wert aus Ihrer ursprünglichen Autorisierungsanfrage übereinstimmt. Dadurch wird sichergestellt, dass Sie es mit dem tatsächlichen Benutzer und nicht mit einem bösartigen Skript zu tun haben. Wenn die Statuswerte nicht übereinstimmen, sollten Sie als Antwort einen 401 Unauthorized HTTP-Fehlercode ausgeben.

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 zu verhindern CSRF - Attacken, empfehlen wir , dass Sie immer einen nonguessable einreichen state , wenn die Autorisierung anfordert.

Auf diese Weise kann Ihre Works with Nest-Integration überprüfen, ob die von der Nest-Cloud abgerufenen Zugriffscodes auf Anfragen Ihres Produkts und nicht eines anderen Produkts reagieren.

Beispiel:

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

http://localhost:5000/callback

Lassen Sie sich auch sagen , dass Ihr Client den sendet 7tvPJiv8StrAqo9IQE9xsJaDso4 Zustand in der Genehmigung URL:

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

Der Benutzer stimmt der Anfrage zu.

Die Nest-Cloud gibt den Zustandsparameter als Teil des Weiterleitungs-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 es nur Weiterleitungen mit einem überprüfbaren Status akzeptiert.

Es gibt mehrere Möglichkeiten, einen nicht schätzbaren Zustandsparameter zu generieren. Sie können randomisierte Zustandswerte aus einem im Speicher gehaltenen Wörterbuch oder einen neu berechenbaren Wert bereitstellen. Sie können einen privaten Schlüssel mit einigen leicht überprüfbaren Variablen – beispielsweise der Client-ID und einem Sitzungscookie – verwenden, um einen Hash-Wert zu berechnen. Dies führt zu einem Byte-Wert, der ohne den privaten Schlüssel schwer zu erraten ist. Ein anderer Vorschlag ist, das aktuelle Datum und die aktuelle Uhrzeit zu hashen. Bei diesem Ansatz muss Ihre Anwendung den Zeitpunkt der Übermittlung speichern, um sie zu überprüfen oder eine gleitende Gültigkeitsdauer zuzulassen (z.

Nachdem Sie den Keyed-Hash Message Authentication Code (HMAC) berechnet haben, codieren Sie ihn mit Base-64 und übergeben ihn als Zustandsparameter an die Nest-Cloud.

Hier ist ein Python - Beispiel , das verwendet 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)

Fehlermeldungen zum Autorisierungscode

Wenn die Autorisierungscode-Anforderung fehlschlägt, wird den Benutzern eine Fehlermeldung angezeigt. Weitere Informationen zu diesen Meldungen und wie sie verhindern, finden Sie in der Autorisierungs - Referenz .

Autorisierungscode für ein Zugriffstoken austauschen

Der letzte Schritt zum Erhalten eines Zugriffstokens besteht darin, dass Ihr Produkt mit dem gerade erworbenen Autorisierungscode einen solchen anfordert. Dies geschieht durch eine HTTP-POST-Anfrage "x-www-form-urlencoded".

Fügen Sie die folgenden Parameter in die Anfrage ein. Alle vier Parameter sind erforderlich.

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

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

Codebeispiele (Authentifizierung)

Siehe Beispiele in verschiedenen Sprachen .

Beispiel für Postbote (auth)

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

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

POST-Header zum Abrufen des Zugriffstokens

Auf dem Körper Registerkarte umfasst die folgenden Schlüssel: Wert - Paare.

POST-Text, um Zugriffstoken zu erhalten

Antwort auf Zugriffstoken

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

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

Fehlermeldungen für Zugriffstoken

Schlägt die Anfrage fehl, erhalten Sie einen Fehler in Form eines HTTP-Statuscodes. Weitere Informationen zu diesen Fehler und wie sie verhindern, finden Sie in der Autorisierungs - Referenz .

Stellen Sie authentifizierte Anfragen

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

Zugriffstoken sind nur für die im Umfang der Tokenanforderung beschriebenen Operationen und Ressourcen gültig. Wenn beispielsweise ein Zugriffstoken für die Nest Thermostat API ausgestellt wird, gewährt es keinen Zugriff auf die Nest Camera API.

Codebeispiele (lesen/schreiben)

Beispiel Postbote (Lesen/Schreiben)

Postbote liefert zu Test - API - Aufrufen eine einfache Möglichkeit , Content-Type = mit application/json .

GET, um Daten zu lesen

Ungültige Token

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

  • Es ist abgelaufen
  • Der Benutzer hat die ursprünglich für Ihr Produkt erteilte Berechtigung widerrufen granted

Es ist wichtig, dass Sie Ihr Produkt codieren, um einen 401 Unauthorized-Fehler richtig zu behandeln, indem Sie den Benutzer zurück zum Start des Autorisierungsworkflows umleiten.

Funktioniert mit geschlossener Nest-Verbindung

Wenn ein Benutzer eine entfernt Works mit Nest Verbindung erhält Ihr Produkt ein auth_revoked Ereignis und die Verbindung schließt.