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.
Эта страница была переведа с помощью Cloud Translation API.
Switch to English

Аутентификация и авторизация OAuth 2.0

Nest API использует протокол OAuth 2.0 для аутентификации и авторизации.

Прежде чем ваш продукт сможет получить доступ к личным данным с помощью API Nest, он должен получить токен доступа, который предоставляет доступ к этому API. Один токен доступа может предоставлять различные степени доступа к нескольким разделам API.

Последовательность авторизации начинается, когда ваш продукт перенаправляет браузер на URL-адрес Nest с параметрами запроса, указывающими запрошенный доступ. Nest обрабатывает аутентификацию пользователя, выбор сеанса и согласие пользователя. В результате получается код авторизации, который ваш продукт может обменять на токен доступа. Затем ваш продукт может использовать токен доступа для вызова API Nest.

Поток OAuth 2.0
Поток OAuth 2.0

Сконфигурируйте ваши работы с клиентом Nest

Чтобы найти учетные данные OAuth 2.0 для своего клиента, откройте вкладку «Обзор» на странице клиента.

Перенаправить URI или авторизацию на основе PIN?

При настройке клиента вам предлагается ввести URI перенаправления или оставить поля URI перенаправления пустыми, чтобы использовать авторизацию на основе PIN-кода.

Если ваш продукт - это устройство, у которого нет связанного приложения или веб-страницы (например, фитнес-трекер, устройство или панель безопасности), оставьте поля Redirect URI пустыми.

Если в вашем продукте есть компонент браузера, рекомендуется включить URI перенаправления.

Запросить разрешения

Конфигурация клиента включает в себя набор разрешений (также называемых областями). Разрешение - это переменный параметр, который управляет набором ресурсов и операций, которые разрешает токен доступа. Как правило, рекомендуется запрашивать разрешения постепенно, в то время, когда требуется доступ, а не заранее.

результат

При сохранении конфигурации вашему клиенту назначается уникальный идентификатор клиента и секрет клиента. Кроме того, вашему клиенту назначен URL авторизации.

URL-адрес авторизации включает параметр состояния, который можно использовать для проверки на возможные атаки подделки межсайтовых запросов (CSRF). См. Тест на CSRF-атаки .

OAuth подробности

Запросить код авторизации

После того, как ваш клиент настроен, вы можете запросить код авторизации (иногда называемый PIN-кодом). Код авторизации не является окончательным токеном, который вы используете для звонков в Nest. Он используется на следующем шаге потока OAuth 2.0 для обмена на фактический токен доступа. Этот шаг дает гарантию непосредственно от Nest пользователю, что разрешение предоставляется для соответствующего продукта с согласованным доступом.

Пользовательский опыт

Мы представляем страницу Works with Nest, в которой пользователю предлагается предоставить доступ к вашему продукту. Это идентифицирует ваш продукт и определяет конкретные пользовательские разрешения (области), запрошенные вашим продуктом. Слова на экране происходят из конфигурации вашего клиента.

Чтобы проверить это самостоятельно, загрузите URL авторизации из шага 1 в браузер. Вы должны увидеть страницу запроса доступа к Works с:

Работает с Nest

Идем дальше и сами нажимаем [ПРИНЯТЬ], чтобы увидеть то, что видит пользователь. Нажав кнопку [ПРИНЯТЬ], пользователь подтверждает запрос вашего продукта на доступ к своим данным.

ПИН-код

Если вы оставите поля «Перенаправить URI» пустыми в конфигурации клиента, пользователь будет перенаправлен на страницу «Гнездо», на которой отображается PIN-код (код авторизации). Пользовательский интерфейс вашего устройства должен предложить пользователю ввести PIN-код вручную.

Пин-код

Опыт перенаправления URI

Если вы включите URI перенаправления в конфигурацию клиента, пользователь будет перенаправлен на страницу в вашем облаке (или localhost), и Nest автоматически отправит код авторизации на устройство пользователя.

Тест на CSRF-атаки

Перед принятием кода авторизации ваш продукт должен убедиться, что значение, возвращаемое в параметре состояния, соответствует значению состояния из вашего исходного запроса авторизации. Это гарантирует, что вы имеете дело с реальным пользователем, а не с вредоносным скриптом. Если значения состояния не совпадают, вы должны в ответ выдать 401 код ошибки Unauthorized HTTP.

CSRF-атака - это атака, которая заставляет конечного пользователя выполнять нежелательные действия в веб-приложении, в котором они в настоящий момент проходят проверку подлинности.

CSRF атака
CSRF атака

Чтобы помочь предотвратить атаки CSRF, мы рекомендуем всегда отправлять неопровержимое state при запросе авторизации.

Таким образом, ваша интеграция Works с Nest может проверить, что коды доступа, полученные из облака Nest, отвечают на запросы, сделанные вашим продуктом, а не каким-либо другим продуктом.

Пример:

Допустим, в вашем клиентском конфиге вы указываете URI перенаправления:

 http://localhost:5000/callback
 

Предположим также, что ваш клиент отправляет состояние 7tvPJiv8StrAqo9IQE9xsJaDso4 в URL авторизации:

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

Пользователь соглашается на запрос.

Облако Nest возвращает параметр состояния как часть URI перенаправления:

 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 -
 

Ваш продукт получает это значение состояния и должен быть запрограммирован на прием перенаправлений только с проверяемым состоянием.

Есть несколько способов создать неугаданный параметр состояния. Вы можете предоставить случайные значения состояния из словаря, хранящегося в памяти, или из повторно вычисляемого значения. Вы можете использовать закрытый ключ с некоторыми легко проверяемыми переменными - например, идентификатором клиента и файлом cookie сеанса - для вычисления хэшированного значения. Это приводит к значению байта, которое трудно угадать без закрытого ключа. Еще одно предложение - хешировать текущую дату и время. При таком подходе ваше приложение должно сэкономить время передачи, чтобы проверить его или разрешить скользящий период действия (например, используя алгоритм одноразового пароля на основе времени [TOTP]).

После вычисления кода аутентификации сообщения с хэш-ключом (HMAC) base-64 кодирует его и передает его в облако Nest в качестве параметра состояния.

Вот пример Python, который использует 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)
 

Сообщения об ошибках кода авторизации

Если запрос кода авторизации не выполняется, пользователи видят сообщение об ошибке. Для получения дополнительной информации об этих сообщениях и о том, как их предотвратить, см. Справочник по авторизации .

Код авторизации Exchange для токена доступа

Последний шаг в получении токена доступа для вашего продукта - запросить его, используя только что полученный код авторизации. Это делается с помощью запроса HTTP POST «x-www-form-urlencoded».

Включите следующие параметры в запрос. Все четыре параметра обязательны.

параметр Описание
ID клиента Идентификатор клиента на шаге 1
client_secret Секрет клиента на шаге 1
код Код авторизации, полученный на шаге 2
grant_type Значение этого поля всегда должно быть: authorization_code

Перед каждым вызовом POST получите новый код авторизации. Для этого перезагрузите ваш URL авторизации. Затем измените параметр code POST, чтобы включить новый код авторизации.

Примеры кода (аутентификация)

Смотрите примеры на разных языках .

Пример почтальона (аутентификация)

Почтальон предоставляет простой способ проверить OAuth-запросы.

На вкладке Заголовки убедитесь, что Content-Type = application/x-www-form-urlencoded .

POST-заголовок для получения токена доступа

На вкладке Body включите следующий ключ: пары значений.

Тело POST для получения токена доступа

Ответ токена доступа

Успешный запрос возвращает объект JSON, содержащий следующие поля:

  • access_token - токен доступа для пользователя. Это значение должно храниться в безопасности.
  • expires_in - количество секунд, оставшихся с момента запроса до истечения срока действия токена.

Доступ к сообщениям об ошибках токена

Если запрос не выполняется, вы получаете сообщение об ошибке в виде кода состояния HTTP. Для получения дополнительной информации об этих ошибках и о том, как их предотвратить, см. Справочник по авторизации .

Делать аутентифицированные запросы

После того, как продукт получает токен доступа, он отправляет токен Nest API в заголовке авторизации HTTP. Можно отправлять токены в виде параметров строки запроса URI, но мы не рекомендуем этого, поскольку параметры URI могут оказаться в файлах журнала, которые не являются полностью безопасными.

Токены доступа действительны только для набора операций и ресурсов, описанных в объеме запроса токена. Например, если выдан токен доступа для API Nest Thermostat, он не предоставляет доступ к API Nest Camera.

Примеры кода (чтение / запись)

Пример почтальона (чтение / запись)

Почтальон предоставляет простой способ протестировать вызовы API, используя Content-Type = application/json .

ПОЛУЧИТЕ читать данные

Неверные токены

Если вы делаете вызов API с использованием недопустимого токена, вы получаете 401 несанкционированный ответ от сервера. Токен может быть недействительным и нуждается в регенерации, потому что:

  • Истек
  • Пользователь отозвал разрешение, которое он изначально дал вашему продукту

Важно, чтобы вы кодировали свой продукт для правильной обработки несанкционированной ошибки 401, перенаправляя пользователя обратно в начало рабочего процесса авторизации.

Работает с закрытым соединением

Если пользователь удаляет соединение Works with Nest , ваш продукт получает событие auth_revoked и соединение закрывается.