Аутентификация в навыке умного дома

Навык умного дома обязательно должен связывать пользователя навыка с аккаунтом в системе управления умным домом. Для этого в Яндекс.Диалогах вы можете настроить связки аккаунтов — наборы настроек OAuth-приложения, которые следует использовать для запроса токенов доступа.

Реализация OAuth 2.0

Чтобы реализовать авторизацию в Яндекс.Диалогах, вам нужно определить параметры OAuth-протокола и создать связку аккаунтов.

Если вы не владеете каким-либо компонентом схемы, обратитесь к документации сервиса, чтобы узнать:

  • Реализован ли протокол OAuth 2.0 в сервере авторизации.
  • Поддерживает ли авторизационный сервер «authorization code grant».
  • Как зарегистрировать OAuth-приложение на авторизационном сервере.
  • Какие URI следует использовать для запросов авторизации и запросов OAuth-токенов.
    Примечание. В качестве redirect_uri необходимо использовать адрес:
    https://social.yandex.net/broker/redirect

    Сервер авторизации должен перенаправлять OAuth-приложение на этот URI, передавая необходимые авторизационные данные. Подробнее о redirect_uri см. в спецификации к OAuth 2.0.

  • Как правильно вызывать API сервиса, чтобы обращаться к данным конкретного пользователя навыка.

Схема взаимодействия

Чтобы реализовать авторизацию пользователей, Яндекс.Диалоги взаимодействуют с навыками и системами умного дома по протоколу OAuth 2.0, с помощью кодов авторизации. Авторизационный сервер может являться частью системы умного дома, или использоваться как сервис.

Последовательность авторизации:

  1. Пользователь навыка находит нужный навык умного дома в приложении Яндекс и нажимает кнопку Подключить. Приложение открывает страницу авторизации по URI, который был указан при настройке связки аккаунтов.
  2. Пользователь входит в свой аккаунт умного дома.
  3. Если пользователь авторизуется успешно, авторизационный сервер генерирует код для получения токена.
  4. Авторизационный сервер вызывает URI Яндекс.Диалогов (этот URI должен быть указан в redirect_uri). В запросе передаются параметры:
    • code — код авторизации, полученный на предыдущем этапе;
    • state — состояние авторизации. Формируется Диалогами, чтобы отслеживать процесс авторизации конкретного пользователя.
  5. Диалоги используют полученный код, чтобы получить OAuth-токен и refresh-токен для аккаунта пользователя.
  6. Диалоги связывают полученные токены с аккаунтом пользователя навыка в Яндексе: связывание аккаунта на этом этапе можно считать успешным.
  7. Впоследствии с каждым запросом пользователя к навыку Диалоги добавляют к телу запроса свойство access_token, которое содержит токен для доступа к данным пользователя. Чтобы использовать токен для доступа к стороннему API из навыка, укажите его в заголовке запроса:

    Authorization: Bearer <access_token>

Создание связки аккаунтов

Откройте страницу Связка аккаунтов и нажмите кнопку Добавить связку аккаунтов:
  • Название — понятное вам название связки.
  • Идентификатор приложения — идентификатор OAuth-приложения на сервере авторизации системы умного дома (например, 4760187d41bc4b7799476b42b5103213).

    Примечание. Если ваш сервис также предоставляет возможность авторизации с аккаунтом Яндекса, укажите идентификатор приложения на Яндекс.OAuth в поле Идентификатор OAuth приложения ниже.
  • Секрет приложения — пароль OAuth-приложения на сервере авторизации системы умного дома (например, f25bebr991ff419893db655428e4e1de).
  • URL авторизации — страница, на которой должен авторизоваться пользователь, чтобы разрешить навыку доступ к своему аккаунту (например, https://example-smart-home.com/login).
  • URL для получения токена — адрес, на который следует отправить запрос с авторизационным кодом, чтобы получить OAuth-токен доступа (например, https://oauth-server.com/token).
  • URL для обновления токена — адрес для обновления полученного OAuth-токена (например, https://oauth-server.com/refresh).
  • Идентификатор группы действий — список разрешений в системе умного дома, которые следует выдавать для запрашиваемых OAuth-токенов (например, home:lights).
  • Идентификатор OAuth приложения — идентификатор приложения в Яндекс.OAuth, которое также позволяет авторизоваться в системе умного дома.
После создания связки ее можно будет выбрать в блоке Связка аккаунтов в настройках навыка умного дома.