Идентификация через токен

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

N.B.

Данная статья содержит техническое описание сервиса токенизации, необходимого для безопасной авторизации и идентификации клиентов при взаимодействии с чат-сервисом Webim, без передачи персональных данных через открытую сеть.

Функциональные требования к сервису токенизации

Генерация временных токенов:

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

Хранение соответствия токенов и данных клиента:

Сервис должен хранить соответствие между токеном и внутренним ID клиента.
Необходимо предусмотреть механизм очистки устаревших токенов.
Рекомендуемое время жизни токена: от 30 минут до 24 часов.

API для внутреннего взаимодействия:

Метод получения токена по ID клиента.
Метод валидации токена и получения связанных данных клиента.

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

Авторизация пользователя

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

Генерация токена:

При переходе Пользователя на страницу с чатом сервер МП запрашивает токен у сервиса токенизации.
Сервис токенизации генерирует уникальный временный токен.
Токен связывается с внутренним ID клиента и его персональными данными (ФИО, телефон и т.д.).
Сервис токенизации возвращает сгенерированный токен серверу МП.

Передача данных в Webim через API:

Сервер МП вызывает метод API системы Webim provide_visitor_fields.
В запросе передаются временный токен (auth_token), ID Пользователя (id) и персональные данные Пользователя (ФИО, телефон и т.д.).
Система Webim сохраняет эти данные, связывая их с переданным токеном.
Важно: данный запрос выполняется внутри защищенной сети МП, персональные данные не передаются через интернет.

Инициализация чата

Токен передается на фронтенд в авторизованной зоне через JavaScript переменную: window.webim_auth_token = <auth_token>
Виджет чата на стороне Пользователя инициализирует сессию, передавая только токен (без персональных данных).
Система Webim получает запрос на создание чата с токеном.
Система Webim находит в своей базе данные Пользователя по переданному токену.
Создается сессия чата с предзаполненными данными Пользователя.
В интерфейсе оператора отображаются персональные данные клиента (ФИО, телефон).

Технические требования к реализации

Протоколы взаимодействия:

Все API-запросы должны использовать HTTPS. Также рекомендуется использовать взаимную аутентификацию (mutual TLS) между серверами.
Производительность:

Генерация токена должна происходить в течение не более 100 мс. При этом система должна поддерживать не менее 1000 запросов в секунду.
Отказоустойчивость:

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

Интеграция с Webim

Для интеграции с сервисом Webim необходимо использовать API:

Метод `provide_visitor_fields`

Итоговый URL: https://{hostname}/api/v2/rt/provide_visitor_fields
Тип запроса: POST
Content-Type: application/json
Формат тела запроса: JSON

Запрос позволяет провести полнофункциональную авторизацию Пользователя,зарегистрированного в Webim, из внешней (относительно Webim Server) системы c использованием токенизатора.

Важные замечания:

Программно-аппаратная часть (бэкенд) внешней системы должна уметь генерировать комбинации токенов и предоставленных полей Пользователя.
Пользовательский интерфейс (фронтенд) внешней системы должен содержать следующий JavaScript-код: window.webim_auth_token = <auth_token>;.
На страницах не должно быть объекта webim_visitor, который содержит идентифицирующие данные.
При успешном использовании метода у Пользователя не будет возможности ввести контактную информацию в виджете чата.
Фронтенд внешней системы должен иметь имплементированный обработчик для события ошибки: window.webimHandlers.onProvidedTokenNotFoundError.
Когда Пользователя выходит из системы, бэкенд должен отправить на сервер Webim POST-запрос в метод provide_visitor_fields с токеном и без visitor_fields, при этом комбинация токен-поля будет удалена.

Пример тела запроса:

{
    "auth_token": "40bbba7cd1fec39dd1aXXXXXXXXXXX",
    "visitor_fields": {
    "id": "a1e29384df",
    "display_name": "John Bull",
    "email": "john@webim.ru",
    "phone": "+7 123 123 123"
  }
}

Параметры запроса:

Имя	Тип	Описание
auth_token	str	Уникальный, псевдослучайный идентификатор (токен). Обязательное поле. Может быть любой строкой (например, UUID).
visitor_fields	Object	Структура с предоставленными полями посетителя. Необязательное поле. Если присутствует, добавляет/замещает комбинацию "токен-поля". Если отсутствует, комбинация удаляется из памяти.
id	str	Идентификатор посетителя в системе организации. Обязательное поле, если присутствует объект `visitor_fields.`
[Другие поля]	str	Любые персональные данные посетителя, которые нужно передать на сервер.

Возвращаемые значения:

200 – запрос выполнен успешно: { "result": "ok" }.
401 – авторизационные данные не прошли проверку: { "error": "unauthorized" }.
502 – сервер не готов обработать запрос (Bad Gateway).

Ошибки с кодом 200: { "error": "<error-name>" }. Возможные ошибки:

auth-token-is-not-string: Неверный тип данных в поле токена.
request-body-is-not-object: Неверный формат исходных данных.
request-body-is-not-valid-json: Недействительный JSON-объект.
mandatory-field-not-found: Не указан токен.
id-field-required: В visitor_fields отсутствует параметр id.
field-name-is-not-string: В visitor_fields имеется ключ/значение, указанное не строкой.