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

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

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

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

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

  1. Пользователь запрашивает у навыка приватные данные, например баланс.
  2. Навык понимает, что для запроса требуется авторизация, и отправляет Диалогам ответ с командой start_account_linking.
  3. Приложение Яндекс показывает карточку с просьбой авторизоваться.
  4. Когда пользователь нажимает Авторизоваться, Диалоги перенаправляют его на страницу Яндекс ID. На ней пользователь вводит логин и пароль от аккаунта.

    Обратите внимание: использование авторизации через Яндекс ID недопустимо для официального навыка.

  5. После того как пользователь вошел с Яндекс ID, Диалоги перенаправляют его на страницу авторизации стороннего сервиса (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. Если разрешений несколько, то перечислите их через &.
  6. Пользователь вводит логин и пароль от аккаунта на стороннем сервисе.
  7. Сервер авторизации проверяет данные, которые ввел пользователь. Если они верны — генерирует код для получения токена.
  8. Сервер авторизации вызывает URI Диалогов https://social.yandex.net/broker/redirect. В запросе сервер передает параметры code, state, client_id и scope. Сервер авторизации должен возвращать их с теми же значениями, которые Диалоги передали на URL авторизации (см. шаг 4).
  9. Диалоги используют код code, чтобы получить OAuth-токен и refresh-токен для аккаунта пользователя. Для этого Диалоги отправляют запросы на URL, которые вы указывали при создании связки аккаунтов в консоли разработчика (в полях URL для получения токена и URL для обновления токена).

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

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

Что происходит после связывания аккаунтов

  1. С каждой репликой пользователя Диалоги передают навыку заголовок Authorization. Заголовок содержит OAuth-токен для доступа к данным.
    Authorization: Bearer <access_token>

    На случай если заголовки запроса до навыка не доходят (например, в сервисе облачных функций), токен также передается в теле запроса — в свойстве session.user.access_token.

  2. Чтобы получить доступ к защищенным данным, навык передает токен в запросах к ресурсному серверу.

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

    Если токен валиден, ресурсный сервер отдает навыку защищенные данные.

    Если нет — навык показывает карточку авторизации.