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

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

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

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

Ниже рассмотрен процесс авторизации в навыке:

  1. Пользователь запрашивает у навыка приватные данные — например, хочет проверить баланс.
  2. Навык понимает, что для данного запроса требуется авторизация, и отправляет Диалогам ответ с командой start_account_linking.
  3. Приложение Алисы (поисковое приложение) отображает пользователю карточку с просьбой авторизоваться.
  4. Когда пользователь нажимает кнопку Авторизоваться, Диалоги перенаправляют его на страницу Яндекс.Паспорта. На ней пользователю необходимо ввести логин и пароль от учетной записи на Яндексе.
  5. После того как пользователь авторизовался на Яндексе, Диалоги перенаправляют его на страницу авторизации в стороннем сервисе (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 для обновления токена).
  10. Диалоги сохраняют полученные OAuth-токен и refresh-токен (если используется). Связывание аккаунтов на этом этапе можно считать успешным.
  11. Впоследствии, с каждой репликой пользователя Диалоги передают навыку заголовок Authorization. Заголовок содержит OAuth-токен для доступа к данным пользователя.
    Authorization: Bearer <access_token>
  12. Чтобы получить доступ к защищенным данным, навык должен передавать токен в запросах к ресурсному серверу.

  13. Прежде чем отправить защищенные данные навыку, ресурсный сервер должен проверить токен на валидность. Для этого нужно отправить запрос на сервер авторизации, который должен подтвердить корректность токена.
  14. Если токен валиден, ресурсный сервер отдает навыку защищенный ресурс. В противном случае, навык должен ответить пользователю карточкой авторизации.