Описание взаимодействий SVA с публичной сетью Интернет #

Данный документ описывает взаимодействие платформы SVA в публичной сети интернет для общего понимания какие данные в рамках каких взаимодействий и по каким протоколам могут быть переданы из интернета в SVA и обратно. Документ НЕ раскрывает в деталях реализацию API, порядок вызова методов их формат и содержание. Целевой аудиторией являются архитекторы информационных систем, сетевые администраторы и специалисты по информационной безопасности.

Платформа SVA предназначена для размещения как в облачной, так и в локальной инфраструктурах, поэтому все методы API изначально доступны публично. При разворачивании локально, часть методов и интерфейсов может быть закрыта для доступа из сети интернет. Данный документ, в том числе, может помочь определить необходимость доступности тех или иных API и интерфейсов извне для вписывания в архитектурный ландшафт целевого решения.

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

Взаимодействия SVA в публичной сети интернет #

Платформа SVA должна быть подключена к сети интернет для нормального функционирования, которое включает:

Веб интерфейс Клиентов SVA с возможностью передачи и получения аудио-визуальных данных
АРМ агента SVA с возможностью передачи и получения ауди-визуальных данных (опционально может быть доступен только из внутренней сети)
АРМ супервизора и администратора (опционально может быть доступен только из внутренней сети)
Взаимодействия с внешними сервисами
- шлюзы для отправки сообщений (смс, мессенджеры, e-mail)
- публичные API геокодирования и картографических сервисов

Веб интерфейсы SVA являются статическими веб приложениями (html, css, javascript,images), которые осуществляют взаимодействия с платформой SVA через различные API сервисов SVA.

Методы API сервисов SVA делятся на публичные и приватные.

Публичные методы (public) - методы, необходимые для обслуживания взаимодействий с Клиентами SVA. Этим методы ДОЛЖНЫ быть доступны из публичной сети интернет
Частные методы (private) - методы, для административных интерфейсов и/или операций, не участвующие непосредственно при взаимодействиях с Клиентами. Эти методы могут быть закрыты для вызова из публичной сети интернет

Также методы API разделяются на открытые и закрытые:

открытые - методы, не требующие аутентификации
закрытые - методы, требующие аутентификации

Кроме указанных выше API, для работы SVA требуется доступ в интернет по стеку протоколов WebRTC с целью передачи аудио-визуальных и прочих данных Клиентам в режиме реального времени:

ICE: Interactive Connectivity Establishment (RFC 5245)
- STUN: Session Traversal Utilities for NAT (RFC 5389)
- TURN: Traversal Using Relays around NAT (RFC 5766)
SDP: Session Description Protocol (RFC 4566)
DTLS: Datagram Transport Layer Security (RFC 6347)
SCTP: Stream Control Transport Protocol (RFC 4960)
SRTP: Secure Real-Time Transport Protocol (RFC 3711)
TLS: Transport Layer Security Protocol (RFC 5246)
RTP: Real-Time Transport Protocol (RFC 3550)

В основном медиа-подключения работают по UDP транспорту (предпочтительный вариант), но также возможно и использование TCP соединений (если не удалось подключиться по UDP)

Открытые публичные взаимодействия #

Не требуют аутентификации, должны быть доступны из сети интернет

Разрешение сокращенной ссылки #

Клиент открывает полученную сокращенную ссылку, которую обрабатывает сервис vc-surl и возвращает полную ссылку на интерфейс (браузер мобильного приложения или браузер компьютера).

Веб интерфейсы #

Веб интерфейсы, представляющие собой статически скомпилированные веб приложения доступны для загрузки без авторизации (https):

административный интерфейс (console)
интерфейс агента (agent)
интерфейс клиента для мобильных браузеров (user)
интерфейс клиента для браузеров компьютеров (desktop_user)
вспомогательные статические html документы (страницы ошибок)

Брендирование #

Методы API vc-admin, для загрузки текстов и изображений (логотипов), персонализирующие вид интерфейсов.

Аутентификация Клиентов #

Для взаимодействия с API платформы SVA требуется JWT токен. Клиент запрашивает JWT токены (access, refresh), действующие в рамках одного взаимодействия у сервиса аутентификации vc-auth.

Открытые частные взаимодействия #

Не требуют авторизации, не требуются для взаимодействия с внешними клиентами

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

Методы получения (по данным учетной записи и паролю) и обновления JWT токенов сервиса аутентификации vc-auth.

Закрытые публичные взаимодействия #

Взаимодействия, которые ДОЛЖНЫ быть доступны из сети интернет и требующие авторизации (JWT access token).

websocket videochat #

Активные сессия Агента и сессия видеовызова Клиента требуют подключения по веб-сокету videochat к vc-server. Внутри веб сокета реализован API для управления сессиями и взаимодействиями и их данными.

websocket janus #

Активные сессии Агента и сессия видеовызова Клиента требуют подключения по веб-сокету janus к vc-server. Внутри веб сокета реализованы протоколы управления Janus media gateway, которые отвечают за установку и управление соединением между сторонами вызова, а также доставку событий об изменении состояний взаимодействия и его участников. vc-server выступает в роли прокси и балансировщика между медиа-шлюзами. Также отвечает за авторизацию, валидацию запросов, нормализацию соединений в случае их разрывов или переключений.

Передача файлов #

Для передачи файлов в чатах, сохранения и передачи скриншотов, получения файлов из чата требуется доступ к vc-fileserver API из интерфейсов Агента и Клиента.

Восстановление истории чата #

Доступ к vc-history API из интерфейсов Агента и Клиента, для восстановления сообщений в рамках одного взаимодействия в случае разрывов соединений, перезагрузки страницы или переключения активной сессии в другой браузер или на другое устройство.

Опрос после вызова #

Для сохранения результатов поствызовного опроса (NPS) требуется доступ из интерфейсов Клиента к interaction API vc-server

WebRTC соединение #

WebRTC соединения устанавливается между браузером Агента и медиа-шлюзом Janus, а также между браузером Клиента и медиа-шлюзом. Медиа-шлюз отвечает за согласование и сигнализацию WebRTC подключений, трансляцию медиа потоков между участниками вызова без транскодинга, а также ведет запись взаимодействия.

Установка #

В процессе установки WebRTC соединения согласование настроек медиа-потоков (SDP) и обмен ICE кандидатами происходит в веб сокете janus. Медиа-шлюз Janus, имеющий постоянный публичный IP адрес, анонсирует его, как кандидата. Клиентские браузеры собирают кандидатов также с участием STUN/TURN сервера, для обхода ограничений NAT. В процессе обмена кандидатами стороны пробуют установить соединения (STUN connectivity check) между парами кандидатов.

Активное соединение #

В зависимости от сетевого расположения участника взаимодействия трафик ОТ медиа-шлюза Janus К участнику может идти напрямую (если удалось “пробить” NAT). В противном случае клиент подключается к TURN серверу и анонсирует адрес TURN сервера как своего ICE кандидата, шлюз подключается по этому адресу к TURN серверу, который выступает в роли прокси.

Трафик ОТ клиента К шлюзу всегда идет напрямую к шлюзу, имеющему публичный статический IP

Подключение может быть установлено как с UDP транспортом, так и с TCP. Аудио и видео потоки передаются по SRTP+DTLS, дата-канал - SCTP+DTLS При подключении к TURN серверу по защищенному TLS порту, в сегменте TURN сервер - клиент медиа может передаваться внутри TLS соединения.

Количество подключений клиента к медиа-шлюзу в рамках одного вызова может варьироваться от одного (все медиа потоки мультиплексируются в подключение одной пары ICE кандидатов), до 6, когда каждый медиа канал передается внутри своей пары ICE кандидатов.

Закрытые частные взаимодействия #

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

Интерфейс Агента #

Интерфейс оператора SVA также требует:

доступ к vc-admin API для смены пароля
доступ к vc-auth API для выхода из системы и отзыва JWT токена
доступ к interaction API vc-server для управления взаимодействиями:
- создание
- подключение
- завершение
- изменение данных
- запрос отложенных и текущих взаимодействий

Административный интерфейс #

Используется администраторами и супервизорами SVA для управления настройками, доступа к статистике взаимодействий и их данным.

vc-admin API для управления настройками SVA
vc-auth API для выхода из системы и отзыва JWT токена
vc-stat API для получения исторических данных о совершенных взаимодействиях
vc-history API для получения истории сообщений в чатах
vc-fileserver API для получения метаданных сохраненных и переданных в рамках взаимодействий файлов, а также для выгрузки записей вызовов

Взаимодействие с внешними сервисами #

Платформе SVA могут потребоваться взаимодействия с внешними (расположенными в сети интернет) сервисами.

Отправка сообщений #

В SVA реализована возможность отправки сообщений (короткой ссылки клиенту для подключения к взаимодействию) используя различные сервисы. Часть из них проприетарные и работают внутри сети, часть публичные (SMSC.ru, отправка по email, отправка сообщений в Telegram). Конкретные требуемые доступы зависят от реализации конкретного решения. За отправку сообщений от SVA отвечает сервис vc-msg.

Некоторые сервисы имеют возможность отправлять изменения или конечный статус отправки/доставки сообщения. За получение и обработку этих событий также отвечает сервис vc-msg.

Геокодирование #

Сервис геокодирования позволяет преобразовывать географические координаты в текстовые адреса. В SVA реализована возможность использовать ряд таких сервисов. В зависимости от настройки провайдера географических данных, необходимо разрешить трафик от сервиса SVA vc-geo к интерфейсам API нужного сервиса геокодирования.