Авторизация

API ДЛЯ СЕРВИСНОЙ СЛУЖБЫ (ОДНОРАЗОВЫЕ ТОКЕНЫ)

API для сервисной службы - это специальный раздел API для автоматизации работы сервисных служб поддержки "умных домов".

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

Сотрудник сообщает специальный токен пользователю, которой он вводит в систему "умного дома". После этого сотрудник получает удаленный доступ к системе умного дома пользователя вне зависимости от типа подключения пользователя к Интернет провайдеру и наличия белого IP адреса.

В настоящий момент времени API реализовано в модуле VPNKI (функция QuickHelp) для системы Мажордомо.

 

Предварительные требования для аккаунта сервисной службы

  • Наличие бизнес-аккаунта сервисной службы в системе VPNKI (указывается при регистрации или напишите админу для смены типа аккаунта)
  • Активный тарифный план PLAN-BUSINESS-MYDEV или PLAN-BUSINESS-VIDEO или PLAN-BUSINESS-HDVIDEO
  • Приобретенные дополнительные туннели - TUN-RU-3 или TUN-RU-5 или TUN-RU-10 или TUN-RU-20
  • Приобретенные TCP порты - TCPPORT-RU-3 или TCPPORT-RU-5 или TCPPORT-RU-10 или TCPPORT-RU-20
  • Созданные туннели в личном разделе сайта по количеству приобретенных

 

Минимальная стоимость за 30 дней

  • Тарифный план PLAN-BUSINESS-MYDEV - 200 коинов
  • Три дополнительных туннеля TUN-RU-3 - 150 коинов
  • Три TCP порта TCPPORT-RU-3 - 30 коинов

 Итого: 380 коинов

 

Как это работает


1. Сервисная служба создает в VPNKI бизнес-аккаунт и информирует администрацию системы о необходимости работы аккаунта в режиме "сервисной службы". В это режиме появляется доступ к управлению токенами - временными идентификаторами, предназначенными для автоматизации различных действий

2. Сервисная служба приобретает в VPNKI дополнительные туннели и порты для работы. Эти туннели и порты будут работать не вполне обычным образом

3. Сотрудник сервисной службы заранее создает в системе VPNKI туннели по количеству приобретенных услуг

ВАЖНО! При этом два туннеля, входящих в базовый тариф, будут обычными, а остальные, будут работать только для услуги с токенами
Основное отличие в том, что туннели для работы с токенами изначально находятся в заблокированном состоянии и только при активации токена происходит разблокировка. Для сравнения - обычные туннели VPNKI разблокированы всегда.
После завершения работы по технической поддержке туннель блокируется, а пароль соединения автоматически изменяется.

4. Сотрудник сервисной службы на специальной странице сайта VPNKI создает токен и выбирает ранее созданный туннель. По умолчанию токен действует 24 часа с момента генерации. Все дальнейшие действия с токеном будут относиться к работе именно этого туннеля.
Этот токен сотрудник сервисной службы пересылает клиенту по почте. На скриншоте видно, что токен создан, но порты пока не назначены.

 token1

 

5. Пользователь, получив токен, копирует его в поле в модуле QH и, например, может получить по нему статус токена.


Статус токена


https://vpnki.ru/index.php?option=com_api&format=raw&app=webservices&resource=token&key=partner&token=<token>&action=status
 
Данные ответа могут быть следующими:
 
{"token":"not_exist","status":"not_exist"} - токен не существует, ошибка
{"token":"exist","status":"not_active"} - токен выписан, но не активирован пользователем
{"token":"exist","status":"active"} - токен выписан, активен и создан проброс порта TCP
{"token":"exist","status":"deleted"} - токен был удален или истек срок его работы


6. Затем пользователь в модуле QuickHelp указывает какую службу он хочет использовать (ssh или web). И выбранный номер порта (здесь порт 80) вставляется в запрос на активацию токена.


Активация токена


https://vpnki.ru/index.php?option=com_api&format=raw&app=webservices&resource=token&key=partner&token=<token>&port=<port>&action=activate
 
В качестве порта указывается требуемый порт пользовательской системы. Это может быть, например,  порт 80 для доступа к http интерфейсу умного дома, или порт 23 для ssh. На скриншоте видно, что в интерфейсе сотрудника сервисной службы назначилсь внешний порт системы VPNKI (26041) и внутренний порт системы пользовтаеля (80).
 
 token2


7. В ответе на активацию токена модулю QuickHelp поступят следующие данные:

{"token":"oF7xRw",
"status":"activated",
"username":"user75993",
"password":"TQvtLhV1",
"end_datetime":"2019-02-09 02:12:01",
"external_ip":"193.232.49.4",
"external_port":"26072",
"internal_ip":"172.16.26.165",
"internal_port":"80"}
 
Этих данные используются модулем QuickHelp для установления VPN туннеля с username и password. Прочие параметры используются как справочные. Параметр end_datetime - это дата деактивации токена.
После активации токена на сервере vpnki активируется функция "Проброса TCP порта" 26041 адреса 193.232.49.4 на устройство пользователя с адресом 172.16.26.165 и портом 80.
Активация проброса TCP порта в vpnki будет создана в течение 5 минут.

8. В случае необходимости использования второго порта, (например для ssh) сотруднику сервисной службы необходимо завести второй токен и также сообщить его пользователю
Максимальное количество созданных токенов равно количеству купленных TCP портов в аккаунте Сервисной службы.

9. После завершения работы по техподдержке пользователя модуль QH должен отключить туннель и удалить (деактивировать) токен командой удаления
 

Удаление токена

 
https://vpnki.ru/index.php?option=com_api&format=raw&app=webservices&resource=token&key=partner&token=<token>&action=delete

10. Токен может быть принудительно отозван сотрудником сервисной службы. Для этого необходим периодически (раз в пять минут) проверять статус токена командой из п.3.
В случае обнаружения "status":"deleted" необходимо оборвать соединение и больше не пытаться его установить.

После отзыва или истечения срока действия токена:
- туннель на сервере переходит в заблокированное состояние (отображается красным цветом в списке туннелей) 
- изменяется пароль туннеля для будущего подключения
- удаляются трансляции TCP порта

 
ВАЖНО! API для сервисной службы находится в режиме тестирования с 10.02.2019.

 

ДОПОЛНИТЕЛЬНО ПО ТЕМЕ

  • Про VPN и протоколы можно почитать здесь