Управление Ideco Client

Настройка авторизации через Ideco Client

Получение настроек авторизации

GET /agent_backend/agent-server/state

Ответ на успешный запрос:

{
    "enabled": "boolean"
}

enabled - если true, то авторизация через Ideco Client включена, false - выключена.

Изменение настроек авторизации

PATCH /agent_backend/agent-server/state

Json-тело запроса:

{
    "enabled": "boolean"
}

enabled - true для включения авторизации через Ideco Client, false для выключения.

Ответ на успешный запрос: 200 OK

Настройки авторизации Ideco Client

Получение настроек авторизации Ideco Client

GET /agent_backend/agent-server/setting

Ответ на успешный запрос:

{
    "auth_domain": "string" | "null",
    "local_tunnel": "boolean",
    "device_vpn": "boolean",
    "trusted_ca_cert": "string" | "null"
}

• auth_domain - домен/IP-адрес, в котором будет происходить аутентификация;

• local_tunnel - включено или выключено построение туннеля WireGuard для подключений из локальных сетей;

• device_vpn - включено или выключено подключение в режиме Device VPN;

• trusted_ca_cert - доверенный сертификат в формате .pem для проверки подлинности устройства, подключаемого в режиме Device VPN.

Изменение настроек авторизации Ideco Client

PATCH /agent_backend/agent-server/setting

Json-тело запроса:

{
    "auth_domain": "string" | "null",
    "local_tunnel": "boolean",
    "device_vpn": "boolean",
    "trusted_ca_cert": "string" | "null"
}

• auth_domain - домен/IP-адрес, в котором будет происходить аутентификация;

• local_tunnel - включено или выключено построение туннеля WireGuard для подключений из локальных сетей;

• device_vpn - включено или выключено подключение в режиме Device VPN;

• trusted_ca_cert - доверенный сертификат в формате .pem для проверки подлинности устройства, подключаемого в режиме Device VPN. Обязательно для заполнения, если разрешены подключения в режиме Device VPN.

Ответ на успешный запрос: 200 OK

Протокол подключения и авторизации Ideco Client

Сообщения WebSocket с типом TEXT от Ideco Client принимаются бэкендом и после обработки посылается ответное сообщение с типом TEXT, за исключением обмена информацией для ZTNA. Принимаемые и ответные сообщения содержат информацию в формате JSON.

Процесс подключения и авторизации должен проходить в несколько этапов обмена сообщениями:

1. Подключение и запрос соответствия версии Ideco Client

После установления соединения через WebSocket Ideco Client должен сделать запрос со своей версией и типом операционной системы, чтобы Ideco NGFW удостоверился в соответствии версии Ideco Client и при необходимости обновления передал ссылку на скачивание новой версии.

Если версия Ideco Client не совпадает с той, что требует NGFW, нужно скачать дистрибутив, разорвать соединение и установить уже с актуальной версии.

Json-тело запроса

{
    "type": "version",
    "major": "integer",
    "minor": "integer",
    "build": "integer",
    "os": "windows" | "macos" | "linux"
}

• type - команда;

• major - мажорная версия;

• minor - минорная версия;

• build - версия сборки;

• os - тип ОС Ideco Client.

Ответ на успешный запрос

{
    "type": "update",
    "need_update": "boolean",
    "download_url": "string"| "null",
    "version": {
        "major": "integer",
        "minor": "integer",
        "build": "integer",
        "os": "windows" | "macos" | "linux"
    }
}

• need_update - требование обновления: true - необходимо, false - не требуется;

• download_url - путь для скачивания дистрибутива актуальной версии Ideco Client для требуемой ОС (пример: :14765/IdecoAgent_x64.msi). Если обновление не требуется, то значение поля будет null;

• version - версия дистрибутива Ideco Client на Ideco NGFW. Значения полей аналогичны описанным в запросе. Если обновление не требуется, поле будет отсутствовать.

2. Авторизация

Если версия Ideco Client совпадает с требуемой Ideco NGFW, то Ideco Client будет разрешено иницировать авторизацию на NGFW и при необходмости установить туннельное соединение WireGuard, если подключение идет из внешних сетей. Доступно два варианта авторизации: по логину и паролю или через SSO.

Авторизация по логину и паролю

Json-тело запроса:

{
    "type": "authorize",
    "login": "string",
    "password": "string"
}

• login - логин пользователя, может также содержать домен;

• password - пароль.

Ответ на успешный запрос:

{
    "type": "auth_state",
    "authorized": "boolean",
    "need_tunnel": "boolean",
    "timeout": "integer",
    "message": "string"
}

• authorized - состояние авторизации: true - авторизован, false - не авторизован;

• need_tunnel - требуется ли установить туннель WireGuard;

• timeout - время до повторной попытки авторизации в секундах в случае возникновения ошибок в процессе авторизации. Если повторная попытка авторизации не требуется, то значение будет равно 0;

• message - сообщение о состоянии авторизации.

Авторизация с использованием SSO

Авторизация SSO возможна только с локальных сетей Ideco NGFW. При попытке авторизации с внешних сетей сразу произойдет отказ.

Авторизация проходит в несколько обменов пакетами:

1. Запрос на доступность SSO:

Json-тело запроса:

{
    "type": "sso",
    "token": "null",
    "session_token": "null",
    "domain": "string"
}

• token - SSO токен Kerberos или NTLM, для данного запроса должен быть null;

• session_token - идентификатор сессии авторизации, для данного запроса должен быть null;

• domain - домен ActiveDirectory.

Ответ на успешный запрос:

{
    "type": "sso",
    "status": "not_authorized" | "challenge",
    "session_token": "null",
    "access_token": "null",
    "computer_name": "string",
    "error": "string" | "null"
}

• status - статус авторизации для домена: not_authorized - недоступна; challenge - доступна, необходимо передать токен для авторизации;

• session_token - токен сессии авторизации;

• access_token - ответный токен доступа SSO;

• computer_name - имя сервера контроллера домена. Если status = "not_authorized", поле будет отсутствовать;

• error - сообщение об ошибке/причине недоступности SSO авторизации для домена: null, status = "challenge".

2. Запрос на авторизацию SSO:

Json-тело запроса:

{
    "type": "sso",
    "token": "string",
    "session_token": "string" | "null",
    "domain": "string"
}

• token - должнен содержать соответствующий токен;

• session_token - идентификатор сессии, если это вторая или более итерация запроса на авторизацию;

• domain - домен ActiveDirectory.

Если авторизация SSO еще выполняется и нужно отправить еще один запрос на авторизацию SSO (повторить этот же этап обмена пакетами), ответ на успешный запрос:

{
    "type": "sso",
    "status": "in_progress",
    "session_token": "string",
    "access_token": "string",
    "error": "null"
}

Назначение полей аналогично первому ответу (см. выше), только session_token и access_token содержат соответствующие значения.

Если авторизациая завершилась, то в ответ NGFW отправит:

{
    "type": "auth_state",
    "authorized": "boolean",
    "need_tunnel": "boolean",
    "timeout": "integer",
    "message": "string"
}

• authorized - состояние авторизации: true - авторизован, false - не авторизован;

• need_tunnel - требуется ли установить туннель WireGuard;

• timeout - время до повторной попытки авторизации в секундах в случае возникновения ошибок в процессе авторизации. Если повторная попытка авторизации не требуется, то значение будет равно 0;

• message - сообщение о состоянии авторизации.

Протокол обмена информацией для ZTNA

Запрос Ideco NGFW на получение информации от Ideco Client

Ideco NGFW отправляет запрос на сбор информации при подключении Ideco Client. В этом запросе указаны списки параметров, которые необходимо собрать, а также интервал, с которым Client должен собирать данные.

Json-тело запроса о сборе информации:

{
    "type": "ztna",
    "period": "integer",
    "test_list": [
      "os_type" | "os_version" | "domain" | "kb_list" | "av_active" | "av_name" | "av_version" |" av_update" | "av_scan" | "fw_active" | "fw_name" | "fw_version" | "processes" | "services" | "registry"
    ],
    "kb_list": [ "string"] ,
    "proc_list": [ "string" ],
    "service_list": [ "string" ],
    "reg_key_list": [ "string" ]
} 

• type - тип запроса (ztna);

• period - интервал в минутах, через который Ideco Client должен собирать и передавать информацию. Если указан интервал, равный 0, проверка и передача собранных параметров выполняется однократно;

• test_list - список ключевых слов, определяющий необходимость выполнения проверок заданного типа:

  • os_type - проверка типа операционной системы;

  • os_version - проверка версии операционной системы;

  • domain - проверка включенности в домен;

  • kb_list - проверка обновлений операционной системы (в объеме списка, указанного в параметре kb_list);

  • av_active - проверка, запущен ли антивирус;

  • av_name - проверка типа установленного антивируса;

  • av_version - проверка версии установленного антивируса;

  • av_update - проверка даты последнего обновления баз антивируса;

  • av_scan - проверка даты последнего антивирусного сканирования на наличие угроз;

  • fw_active - проверка, запущен ли межсетевой экран;

  • fw_name - проверка типа установленного межсетевого экрана;

  • fw_version - проверка версии установленного межсетевого экрана;

  • processes - проверка запущенных процессов (в объеме списка, указанного в параметре proc_list);

  • services - проверка списка запущенных служб (в объеме списка, указанного в параметре service_list);

  • registry - проверка наличия и значения ключей реестра Windows (в объеме списка, указанного в параметре key_list).

• kb_list - список обновлений для выполнения проверки, может быть пустым, если проверка не требуется;

• proc_list - список процессов для выполнения проверки, может быть пустым, если проверка не требуется;

• service_list - список служб для выполнения проверки, может быть пустым, если проверка не требуется;

• reg_key_list: - список ключей реестра для выполнения проверки: путь/имя, может быть пустым, если проверка не требуется.

Ответ Ideco Client с информацией о выполнении проверок

Ideco Client отправляет ответ с собранной информацией об устройстве в ответ на запрос проверок. Через определенный промежуток времени Ideco Client снова собирает информацию. Если с момента последней проверки ни один из параметров не изменился, то на NGFW ничего не отправляется.

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

Формат ответа с собранной в результате проверок информацией:

{
    "type": "ztna",
    "node_name": "string",
    "operation_system": {
      "type": "string",
      "version": "string",
      "domain": "string" 
    }, 
    "kb_list": [ "string" ],
    "antivirus": [
      {
        "active": "boolean",
        "name": "string", 
        "version": "string",
        "last_update": "integer" | "null",
        "last_scan": "integer" | "null",
      },
    ],
    "firewall": [
      {
        "active": "boolean",
        "name": "string",
        "version": "string",
      },
    ],
    "proc_list": [ "string" ],
    "service_list": [ "string" ],
    "reg_key_list": [
      {
        "key": "string",
        "value": "string",
      }
    ],
}

• type - тип сообщения (ztna);

• node_name - имя узла (собирается для отчетности, но не проходит никаких проверок);

• operation_system - результаты проверки ОС. Может отсутствовать, если в списке запрошенных проверок (поле test_list) отсутствуют ключевые слова os_type, os_version, domain:

  • type - тип операционной системы: Windows, Linux, MacOS (пустая строка, если проверка не выполнялась);

  • version - редакция и версия операционной системы (пустая строка, если проверка не выполнялась);

  • domain - имя домена (если проверка не выполнялась и в случае отсутствия домена - пустая строка).

• kb_list - результаты проверки установленных обновлений KB для Windows. Может отсутствовать, если в списке запрошенных проверок (поле test_list) отсутствует ключевое слово kb_list;

• antivirus - результаты проверок Антивируса. Может отсутствовать, если в списке запрошенных проверок (поле test_list);

• antivirus - список результатов проверок Антивирусов (по числу установленных антивирусных пакетов). Может отсутствовать, если в списке запрошенных проверок (поле test_list) отсутствуют ключевые слова av_active, av_name, av_version, av_update, av_scan:

  • active - если true - запущен, false - не запущен;

  • name - наименование продукта (пустая строка, если проверка не выполнялась);

  • version - версия продукта (пустая строка, если проверка не выполнялась);

  • last_update - количество полных дней, прошедших с последнего обновления баз (null, если проверка не выполнялась);

  • last_scan - количество полных дней, прошедших с последнего сканирования (null, если проверка не выполнялась или не проводилось сканирование).

• firewall - список результатов проверок межсетевых экранов (по числу установленных продуктов). Может отсутствовать, если в списке запрошенных проверок (поле test_list) отсутствуют ключевые слова fw_active, fw_name, fw_version:

  • active - если true - активен, false - не активен;

  • name - наименование продукта (пустая строка, если проверка не выполнялась);

  • version - версия продукта (пустая строка, если проверка не выполнялась).

• proc_list - список найденных процессов. Может отсутствовать или быть пустым списком, если в списке запрошенных проверок (поле test_list) отсутствует ключевое слово processes;

• service_list - список найденных служб Windows. Может отсутствовать, если в списке запрошенных проверок (поле test_list) отсутствует ключевое слово services;

• reg_key_list - список найденных ключей реестра. Может отсутствовать, если в списке запрошенных проверок (поле test_list) отсутствует ключевое слово registry;

  • key - ключ реестра (путь/имя);

  • value - значение параметра.