Что такое связка аккаунтов

Общие сведения

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

Например, у оператора сотовой связи «PhonOn» есть онлайн-сервис — через него пользователи могут узнавать о тарифах и акциях, искать ближайшие отделения. В личном кабинете пользователи могут проверить баланс, подключить услугу или пополнить счет. Для каждого пользователя сервис сохраняет конфиденциальную информацию: паспортные данные, платежные сведения, используемый тариф.

Предположим, вы хотите разработать навык для сервиса «PhonOn». Через навык пользователи смогут уточнить адреса отделений, проверить баланс или изменить тариф.

Чтобы навык мог работать с конфиденциальными данными, у него должен быть доступ к учетной записи пользователя в приложении «PhonOn». Необходимо связать навык с аккаунтом пользователя в «PhonOn».

Чтобы идентифицировать пользователей навыка, Диалоги используют сервис API Паспорта. Поэтому, чтобы реализовать авторизацию в навыке, необходимо связать аккаунты: аккаунт пользователя на Яндексе + аккаунт пользователя на стороннем сервисе (например, «PhonOn»).

Связка аккаунтов реализуется по протоколу OAuth 2.0.

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

С точки зрения разработчика, настройка связки аккаунтов выглядит следующим образом:

  1. Разработчик программирует логику навыка, реализует авторизацию, настраивает взаимодействие между сервером авторизации и ресурсным сервером (подробнее см. в разделе OAuth авторизация и роли).
  2. Регистрирует навык в консоли разработчика. В настройках навыка разработчик создает связку аккаунтов и указывает параметры для сервера авторизации (URL авторизации, URL для получения токена и т. д.).
  3. Проверяет на странице "Тестирование", что авторизация работает.
  4. Отправляет черновик навыка на модерацию. Модераторы проверяют название навыка, описание, приветственную фразу, а также сценарий работы авторизации.
  5. После одобрения модераторами разработчик отправляет навык на публикацию.

Связка аккаунтов в разных типах навыков

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

Тип навыка

Навыки общего типа

Навыки общего типа можно запускать и общаться с ними без связки аккаунтов. Например, с навыком «PhonOn» пользователь может общаться, не авторизуясь — спрашивать про тарифы, искать отделения.

Если ваш навык будет с авторизацией, вам необходимо продумать сценарий — в какой момент навык будет запрашивать авторизацию у пользователя. Возможные сценарии:

  • Авторизация запрашивается сразу при запуске навыка. Когда пользователь открывает навык, показывается карточка авторизации.
  • Авторизация запрашивается по ходу работы с навыком, когда пользователь спросил конфиденциальную информацию. Например, пользователь запросил свой баланс — навык ответил карточкой авторизации.

Подробнее см. в разделе Связка аккаунтов в навыках общего типа.

Навыки умного дома

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

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

При обработке запросов от пользователя, вам не нужно проверять, авторизован ли пользователь — эта проверка выполняется на стороне Диалогов. Если пользователь вышел из аккаунта, запросы к устройствам автоматически перестанут отправляться. Алиса попросит пользователя авторизоваться.

Подробнее см. в разделе Связка аккаунтов в навыках умного дома.

Тип навыка

Навыки общего типа

Навыки общего типа можно запускать и общаться с ними без связки аккаунтов. Например, с навыком «PhonOn» пользователь может общаться, не авторизуясь — спрашивать про тарифы, искать отделения.

Если ваш навык будет с авторизацией, вам необходимо продумать сценарий — в какой момент навык будет запрашивать авторизацию у пользователя. Возможные сценарии:

  • Авторизация запрашивается сразу при запуске навыка. Когда пользователь открывает навык, показывается карточка авторизации.
  • Авторизация запрашивается по ходу работы с навыком, когда пользователь спросил конфиденциальную информацию. Например, пользователь запросил свой баланс — навык ответил карточкой авторизации.

Подробнее см. в разделе Связка аккаунтов в навыках общего типа.

Навыки умного дома

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

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

При обработке запросов от пользователя, вам не нужно проверять, авторизован ли пользователь — эта проверка выполняется на стороне Диалогов. Если пользователь вышел из аккаунта, запросы к устройствам автоматически перестанут отправляться. Алиса попросит пользователя авторизоваться.

Подробнее см. в разделе Связка аккаунтов в навыках умного дома.

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

Связка аккаунтов реализуется по протоколу OAuth 2.0. Для настройки авторизации в навыке ознакомьтесь со спецификацией к протоколу.

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

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

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

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

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

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

Сам сервис «PhonOn», который хранит защищенную информацию пользователей и по токенам отдает нужные данные.

Клиент

Ваш навык. Будет отправлять запросы на ресурсный сервис «PhonOn», чтобы получить защищенные данные.

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

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

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

Сформированный токен передается навыку, чтобы тот отправлял его в запросах к «PhonOn».

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

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

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

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

Сам сервис «PhonOn», который хранит защищенную информацию пользователей и по токенам отдает нужные данные.

Клиент

Ваш навык. Будет отправлять запросы на ресурсный сервис «PhonOn», чтобы получить защищенные данные.

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

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

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

Сформированный токен передается навыку, чтобы тот отправлял его в запросах к «PhonOn».

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

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

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

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

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

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

Сервер авторизации может являться частью ресурсного сервера, например частью сервиса «PhonOn». Либо, сервер авторизации может использоваться как сторонний сервис — например, для сервиса «PhonOn» можно настроить внешнюю авторизацию через Яндекс.

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

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

Вы как разработчик навыка можете не владеть ни сервером авторизации, ни ресурсным сервером (сервером с пользовательскими данными).

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

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

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

Выход из аккаунта

Чтобы выйти из аккаунта в навыке, пользователю достаточно выполнить одно из действий:

  • Выйти из аккаунта на сервере авторизации. Например, если в качестве сервера авторизации используется Яндекс.OAuth, пользователю достаточно выйти из аккаунта на Яндексе через приложение Алисы. Кроме того, если используется авторизация Яндекса, разлогиниться в навыке можно со страницы Доступ внешних приложений.
  • Вызвать соответствующую команду в навыке. Команду для выхода из аккаунта вам необходимо реализовать самостоятельно. Когда пользователь вызовет эту команду, навык должен отозвать токен.
  • Нажать кнопку Выйти из навыка — кнопка находится в описании навыка в каталоге.

  • Вы как автор можете разлогиниться в навыке через консоль разработчика. Откройте вкладку «Тестирование», нажмите на поле Вы авторизованы и выберите Выйти из навыка.

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