Google jest zaangażowany w promowanie równości rasowej dla społeczności czarnych. Zobacz jak.
Ta strona została przetłumaczona przez Cloud Translation API.
Switch to English

Uwierzytelnianie i autoryzacja OAuth 2.0

Nest API używa protokołu OAuth 2.0 do uwierzytelniania i autoryzacji.

Zanim Twój produkt będzie mógł uzyskać dostęp do prywatnych danych za pomocą Nest API, musi uzyskać token dostępu, który przyznaje dostęp do tego API. Pojedynczy token dostępu może zapewniać różne stopnie dostępu do wielu sekcji interfejsu API.

Sekwencja autoryzacji rozpoczyna się, gdy produkt przekierowuje przeglądarkę do adresu URL Nest z parametrami zapytania wskazującymi żądany dostęp. Nest obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika. Rezultatem jest kod autoryzacyjny, który Twój produkt może wymienić na token dostępu. Twój produkt może następnie używać tokenu dostępu do wywoływania interfejsu API Nest.

Przepływ OAuth 2.0
Przepływ OAuth 2.0

Skonfiguruj swój Works z klientem Nest

Aby znaleźć poświadczenia OAuth 2.0 dla swojego klienta, przejdź na kartę Przegląd na stronie klienta.

Przekierowanie URI lub autoryzacja na podstawie kodu PIN?

Podczas konfigurowania klienta zostanie wyświetlony monit o wprowadzenie identyfikatora URI przekierowania lub pozostawienie pól URI przekierowania pustych, aby użyć autoryzacji opartej na numerze PIN.

Jeśli Twój produkt to urządzenie, które nie ma skojarzonej aplikacji ani strony internetowej (na przykład monitor aktywności, urządzenie lub panel bezpieczeństwa), pozostaw pola URI przekierowania puste.

Jeśli Twój produkt ma składnik przeglądarki, najlepszym rozwiązaniem jest dołączenie identyfikatora URI przekierowania.

Poproś o uprawnienia

Konfiguracja klienta obejmuje zestaw uprawnień (zwanych także zakresami). Uprawnienie to zmienny parametr kontrolujący zestaw zasobów i operacji, na które zezwala token dostępu. Na ogół najlepiej jest żądać uprawnień stopniowo, gdy wymagany jest dostęp, a nie z góry.

Wynik

Po zapisaniu konfiguracji klientowi zostanie przypisany unikalny identyfikator klienta i klucz tajny klienta. Ponadto klientowi jest przypisany adres URL autoryzacji.

Adres URL autoryzacji zawiera parametr stanu, którego można użyć do przetestowania pod kątem możliwych ataków polegających na fałszowaniu żądań między lokacjami (CSRF). Zobacz Test ataków CSRF .

Szczegóły protokołu OAuth

Poproś o kod autoryzacyjny

Po skonfigurowaniu klienta możesz zażądać kodu autoryzacyjnego (czasami nazywanego kodem PIN). Kod autoryzacji nie jest ostatnim tokenem używanym do wykonywania połączeń z Nest. Jest używany w następnym kroku przepływu OAuth 2.0 do wymiany na rzeczywisty token dostępu. Ten krok zapewnia bezpośrednio od Nest do użytkownika, że ​​zezwolenie jest udzielane właściwemu produktowi z uzgodnionym dostępem.

Doświadczenie użytkownika

Prezentujemy stronę Works with Nest, która prosi użytkownika o przyznanie dostępu do Twojego produktu. Identyfikuje produkt i przedstawia określone uprawnienia użytkownika (zakresy), o które prosił Twój produkt. Słowa na ekranie pochodzą z konfiguracji klienta.

Aby to sprawdzić samodzielnie, załaduj adres URL autoryzacji z kroku 1 do przeglądarki. Powinieneś zobaczyć stronę z prośbą o dostęp do Works with Nest:

Działa z Nest

Śmiało i kliknij [AKCEPTUJ] siebie, aby zobaczyć, co widzi użytkownik. Klikając przycisk [AKCEPTUJ], użytkownik akceptuje prośbę Twojego produktu o dostęp do jego danych.

Doświadczenie z kodem PIN

Jeśli pozostawisz puste pola URI przekierowania w konfiguracji klienta, użytkownik zostanie przekierowany do strony Nest, która wyświetla kod PIN (kod autoryzacji). Interfejs użytkownika urządzenia powinien następnie monitować użytkownika o ręczne wprowadzenie kodu PIN.

Kod PIN

Doświadczenie z identyfikatorem URI przekierowania

Jeśli umieścisz przekierowany identyfikator URI w konfiguracji klienta, użytkownik zostanie przekierowany na stronę w Twojej chmurze (lub na lokalnym hoście), a Nest automatycznie wyśle ​​kod autoryzacji do urządzenia użytkownika.

Testuj pod kątem ataków CSRF

Przed zaakceptowaniem kodu autoryzacji produkt powinien upewnić się, że wartość zwrócona w parametrze state jest zgodna z wartością stanu z pierwotnego żądania autoryzacji. Gwarantuje to, że masz do czynienia z rzeczywistym użytkownikiem, a nie złośliwym skryptem. Jeśli wartości stanu nie są zgodne, w odpowiedzi należy zgłosić kod błędu 401 nieautoryzowanego błędu HTTP.

Atak CSRF to atak, który zmusza użytkownika końcowego do wykonania niechcianych działań w aplikacji internetowej, w której jest aktualnie uwierzytelniony.

Atak CSRF
Atak CSRF

Aby zapobiec atakom CSRF, zalecamy, aby podczas żądania autoryzacji zawsze podawać state , którego nie można użyć.

W ten sposób Twoja integracja Works with Nest może zweryfikować, czy kody dostępu uzyskane z chmury Nest są odpowiedzią na żądania wysyłane przez Twój produkt, a nie inny produkt.

Przykład:

Powiedzmy, że w konfiguracji klienta określasz adres URI przekierowania:

 http://localhost:5000/callback
 

Załóżmy również, że Twój klient wysyła stan 7tvPJiv8StrAqo9IQE9xsJaDso4 w adresie URL autoryzacji:

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

Użytkownik wyraża zgodę na żądanie.

Chmura Nest zwraca parametr stanu jako część identyfikatora URI przekierowania:

 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 -
 

Twój produkt otrzymuje tę wartość stanu i powinien być zaprogramowany tak, aby akceptował tylko przekierowania o możliwym do zweryfikowania stanie.

Istnieje wiele sposobów generowania parametru stanu, którego nie można odgadnąć. Możesz podać losowe wartości stanu ze słownika przechowywanego w pamięci lub wartość możliwą do ponownego obliczenia. Aby obliczyć zaszyfrowaną wartość, można użyć klucza prywatnego z pewnymi łatwymi do zweryfikowania zmiennymi - na przykład identyfikatorem klienta i plikiem cookie sesji. Skutkuje to wartością bajtów, którą trudno odgadnąć bez klucza prywatnego. Inną sugestią jest zaszyfrowanie aktualnej daty i godziny. W takim podejściu aplikacja musi oszczędzać czas transmisji, aby ją zweryfikować, lub zezwalać na przesuwający się okres ważności (na przykład przy użyciu algorytmu hasła jednorazowego opartego na czasie [TOTP]).

Po obliczeniu kodu uwierzytelniania wiadomości z kluczem skrótu (HMAC) zakoduj go base-64 i przekaż do chmury Nest jako parametr stanu.

Oto przykład w Pythonie, który używa 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)
 

Komunikaty o błędach kodu autoryzacji

Jeśli żądanie kodu autoryzacji nie powiedzie się, użytkownicy zobaczą komunikat o błędzie. Więcej informacji na temat tych komunikatów i sposobów zapobiegania im można znaleźć w dokumentacji dotyczącej autoryzacji .

Wymień kod autoryzacyjny na token dostępu

Ostatnim krokiem w uzyskaniu tokena dostępu jest poproszenie o ten produkt za pomocą otrzymanego właśnie kodu autoryzacji. Odbywa się to poprzez wysłanie żądania HTTP POST „x-www-form-urlencoded”.

Uwzględnij poniższe parametry w żądaniu. Wymagane są wszystkie cztery parametry.

Parametr Opis
Identyfikator klienta Identyfikator klienta w kroku 1
client_secret Sekret klienta w kroku 1
kod Kod autoryzacyjny otrzymany w kroku 2
grant_type Wartość tego pola powinna zawsze wynosić: authorization_code

Przed każdym połączeniem POST uzyskaj nowy kod autoryzacyjny. Aby to zrobić, załaduj ponownie adres URL autoryzacji. Następnie zmień parametr code POST, aby zawierał nowy kod autoryzacji.

Przykłady kodu (autoryzacja)

Zobacz przykłady w różnych językach .

Przykład listonosza (autoryzacja)

Postman zapewnia łatwy sposób testowania żądań OAuth.

Na karcie Nagłówki upewnij się, że Content-Type = application/x-www-form-urlencoded .

Nagłówek POST, aby uzyskać token dostępu

Na karcie ciała, obejmują następujące kluczowe: par wartości.

POST, aby uzyskać token dostępu

Odpowiedź tokena dostępu

Pomyślne żądanie zwraca obiekt JSON zawierający następujące pola:

  • access_token - token dostępu dla użytkownika. Ta wartość musi być bezpieczna.
  • expires_in - Liczba sekund pozostałych od momentu zażądania, zanim token wygaśnie.

Komunikaty o błędach tokena dostępu

Jeśli żądanie nie powiedzie się, pojawi się błąd w postaci kodu stanu HTTP. Aby uzyskać więcej informacji na temat tych błędów i sposobów zapobiegania im, zobacz dokumentację dotyczącą autoryzacji .

Wysyłaj uwierzytelnione żądania

Gdy produkt uzyska token dostępu, wysyła go do Nest API w nagłówku autoryzacji HTTP. Możliwe jest wysyłanie tokenów jako parametrów ciągu zapytania URI, ale nie zalecamy tego, ponieważ parametry URI mogą trafiać do plików dziennika, które nie są całkowicie bezpieczne.

Tokeny dostępu są ważne tylko dla zbioru operacji i zasobów opisanych w zakresie żądania tokena. Na przykład, jeśli token dostępu zostanie wystawiony dla interfejsu Nest Thermostat API, nie zapewni on dostępu do interfejsu Nest Camera API.

Przykłady kodu (odczyt / zapis)

Przykład listonosza (odczyt / zapis)

Postman zapewnia łatwy sposób testowania wywołań API przy użyciu Content-Type = application/json .

GET, aby odczytać dane

Nieprawidłowe tokeny

Jeśli wykonasz wywołanie interfejsu API przy użyciu nieprawidłowego tokenu, otrzymasz zwrotną odpowiedź 401 nieautoryzowanej odpowiedzi z serwera. Token może być nieprawidłowy i wymagać regeneracji, ponieważ:

  • Wygasła
  • Użytkownik cofnął uprawnienie, które początkowo nadał Twojemu produktowi

Ważne jest, aby zakodować produkt tak, aby poprawnie obsługiwał błąd 401 Nieautoryzowany, przekierowując użytkownika z powrotem na początek przepływu pracy autoryzacji.

Działa z zamkniętym połączeniem Nest

Jeśli użytkownik usunie połączenie Works with Nest , produkt otrzyma zdarzenie auth_revoked i połączenie zostanie zamknięte.