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

Диалоги взаимодействуют с навыком и сервером авторизации по протоколу 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.

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


Роль в OAuth	Роль в концепции навыков
Владелец ресурса	Пользователь, который хочет разрешить доступ навыку к своим данным на сервисе PhonOn.
Ресурсный сервер	Сам сервис PhonOn, который хранит защищенную информацию пользователей и по токенам отдает данные.
Клиент	Ваш навык. Будет отправлять запросы на ресурсный сервис PhonOn, чтобы получить защищенные данные.
Сервер авторизации	Сервер, который: аутентифицирует пользователей навыка; запрашивает подтверждение для доступа к данным на сервисе PhonOn; формирует токен. Токен передается навыку, чтобы тот отправлял его в запросах к PhonOn.


Роль в OAuth	Роль в концепции навыков
Владелец ресурса	Пользователь, который хочет разрешить доступ навыку к своим данным на сервисе PhonOn.
Ресурсный сервер	Сам сервис PhonOn, который хранит защищенную информацию пользователей и по токенам отдает данные.
Клиент	Ваш навык. Будет отправлять запросы на ресурсный сервис PhonOn, чтобы получить защищенные данные.
Сервер авторизации	Сервер, который: аутентифицирует пользователей навыка; запрашивает подтверждение для доступа к данным на сервисе PhonOn; формирует токен. Токен передается навыку, чтобы тот отправлял его в запросах к PhonOn.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

С каждой репликой пользователя Диалоги передают навыку заголовок Authorization. Заголовок содержит OAuth-токен для доступа к данным.
```
Authorization: Bearer <access_token>
```
На случай если заголовки запроса до навыка не доходят (например, в сервисе облачных функций), токен также передается в теле запроса — в свойстве session.user.access_token.
Чтобы получить доступ к защищенным данным, навык передает токен в запросах к ресурсному серверу.
Ресурсный сервер отправляет запрос на сервер авторизации, чтобы проверить валидность токена.

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

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