Как устроена авторизация

  1. OAuth-авторизация и роли
  2. Сценарии разработки навыка с авторизацией
  3. Как происходит авторизация в навыке

Диалоги взаимодействуют с навыком и сервером авторизации по протоколу OAuth 2.0— с помощью кодов авторизации (authorization code grant).

Когда пользователь аутентифицируется на сервере авторизации, сервер отправляет Диалогам код для получения токена (code). С помощью этого кода Диалоги запрашивают OAuth-токен и refresh-токен, чтобы обновлять токен доступа, когда срок его жизни истекает.

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

OAuth-авторизация и роли

OAuth 2.0 определяет следующие роли:
  • Владелец ресурса (resource owner) — пользователь.
  • Ресурсный сервер (resource server) — сервер производителя умных устройств, который предоставляет доступ к данным об устройствах по токенам доступа.
  • Клиент (client) — приложение (навык), с помощью которого настраивается связь между пользователем и умными устройствами.
  • Сервер авторизации (authorization server) — проверяет подлинность информации, которую предоставил пользователь, а также выдает авторизационные токены. С их помощью клиент будет запрашивать доступ к данным об устройствах пользователя.

    Длина ответа ограничена 5000 символами, длина OAuth-токена и refresh-токена — 2048 символами. Время жизни токенов (свойство expires_in) должно быть целым числом от 1 до 4 294 967 296.

Ниже на примере сервиса Aqara показано, как понятие OAuth-ролей применяется в концепции навыков.

Роль в OAuth Роль в концепции навыков

Владелец ресурса

Пользователь, который хочет разрешить доступ навыку к своей учетной записи на сервисе Aqara.

Ресурсный сервер

 Сам сервис Aqara, который хранит данные об устройствах пользователя.

Клиент

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

Сервер авторизации

Сервер, который:

  • аутентифицирует пользователей навыка;
  • запрашивает подтверждение для доступа к данным на сервисе Aqara;
  • формирует токен.

Токен передается навыку, чтобы тот отправлял его в запросах к Aqara.
Роль в OAuth Роль в концепции навыков

Владелец ресурса

Пользователь, который хочет разрешить доступ навыку к своей учетной записи на сервисе Aqara.

Ресурсный сервер

 Сам сервис Aqara, который хранит данные об устройствах пользователя.

Клиент

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

Сервер авторизации

Сервер, который:

  • аутентифицирует пользователей навыка;
  • запрашивает подтверждение для доступа к данным на сервисе Aqara;
  • формирует токен.

Токен передается навыку, чтобы тот отправлял его в запросах к Aqara.

Сценарии разработки навыка с авторизацией

Вы сами разрабатываете ресурсный сервер и сервер авторизации

Вы самостоятельно реализуете сервер авторизации, который работает по протоколу OAuth 2.0. Сервер авторизации будет аутентифицировать пользователя, запрашивать разрешение на доступ к защищенным данным и выпускать токены.

Настройте взаимодействие между сервером авторизации и ресурсным сервером. Ресурсный сервер станет обрабатывать запросы от клиента, проверять валидность токенов и отдавать защищенный ресурс навыку.

Кроме собственного сервера авторизации, для аутентификации пользователей Яндекса подходит API Яндекс ID. Но помните, что использование авторизации через Яндекс ID недопустимо для официальных навыков.

Вы сами разрабатываете ресурсный сервер, но используете сторонний сервер авторизации

Сервер авторизации может быть частью вашего сервера с данными умных устройств, например сервиса Aqara. Либо сервер авторизации может использоваться как сторонний сервис. Например, для неофициальных навыков можно настроить внешнюю авторизацию через Яндекс.

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

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

Вам необязательно владеть сервером авторизации и ресурсным сервером (сервером с данными умных устройств).

Например, сделайте неофициальный навык для сервиса Aqara c внешним API. Навык будет подключаться к API, аутентифицировать пользователя и отправлять запросы от его имени согласно голосовым командам. Сервис должен поддерживать OAuth 2.0.

Если вы используете сторонние системы — узнайте в их документации:

  • Реализован ли протокол OAuth 2.0 в сервере авторизации.
  • Поддерживает ли сервер авторизации authorization code grant.
  • Как зарегистрировать OAuth-приложение на сервере авторизации.
  • Какие URI использовать для запросов авторизации и запросов OAuth-токенов.
  • Как вызывать API сервиса, чтобы обращаться к данным конкретного пользователя навыка.

Как происходит авторизация в навыке

  1. Когда пользователь нажимает кнопку Привязать к Яндексу, Диалоги перенаправляют его на страницу авторизации вашего сервиса (authorization endpoint). URL этой страницы вы указываете, когда создаете связку аккаунтов в консоли разработчика. В URL авторизации Диалоги передают параметры:
    • state — состояние авторизации. Формируется Диалогами, чтобы отслеживать процесс авторизации. Сервер авторизации должен вернуть Диалогам этот параметр с тем же значением.
    • redirect_uri — страница, куда перенаправляется авторизованный пользователь (redirect endpoint). В качестве redirect_uri указывайте URI Диалогов: https://social.yandex.net/broker/redirect.
    • response_type — тип авторизации. Принимает значение code.
    • client_id — идентификатор OAuth-приложения.
    • scope — список разрешений, которые следует выдавать для запрашиваемых OAuth-токенов (access token scope). Например, read, home:lights. Если разрешений несколько, то перечислите их через &.
  2. Пользователь вводит логин и пароль от аккаунта на вашем сервисе.
  3. Сервер авторизации проверяет данные, которые ввел пользователь. Если они верны — генерирует код для получения токена.
  4. Сервер авторизации вызывает URI Диалогов https://social.yandex.net/broker/redirect. В запросе сервер передает параметры code, state, client_id и scope. Сервер авторизации должен возвращать их с теми же значениями, которые Диалоги передали на URL авторизации (см. шаг 1).
  5. Диалоги используют код code, чтобы получить OAuth-токен и refresh-токен для аккаунта пользователя. Для этого Диалоги отправляют запросы на URL, которые вы указывали при создании авторизации в консоли разработчика (в полях URL для получения токена и URL для обновления токена).

    Длина ответа ограничена 5000 символами, длина OAuth-токена и refresh-токена — 2048 символами. Время жизни токенов (свойство expires_in) должно быть целым числом от 1 до 4 294 967 296.

  6. Диалоги сохраняют OAuth-токен и refresh-токен (если есть). Аккаунты успешно связаны.

Служба поддержки