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

Навык умного дома обязательно должен связывать пользователя навыка с аккаунтом в системе управления умным домом. Для этого в Яндекс Диалогах вы можете настроить связки аккаунтов — наборы настроек 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

    В качестве redirect_uri необходимо использовать адрес:

    `https://social.yandex.net/broker/redirect`

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

    ). В запросе передаются параметры:

    • 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).