6.6 KiB
Техническое задание
Микросервис управления доверенными адресами клиентов (Белые списки IP)
1. Назначение
Клиенты облачного провайдера через личный кабинет управляют своими доверенными IPv4-адресами. Эти адреса исключаются из блокировки при DDoS-атаках.
Администраторы Нубеса могут просматривать и редактировать списки всех клиентов.
2. Авторизация
2.1. Вход
Пользователь входит через Keycloak (OIDC). После входа приложение запрашивает IAM API — сервис авторизации экосистемы Nubes.
IAM возвращает:
- email пользователя
- список компаний, к которым он принадлежит
- активную компанию
- флаг администратора (isAdmin)
2.2. Роли
| Роль | Возможности |
|---|---|
| Клиент | Видит и редактирует только записи своих компаний |
| Администратор Нубеса | Видит и редактирует записи всех компаний, меняет лимиты, смотрит аудит, выгружает списки |
Администратором считается пользователь с isAdmin = true в IAM и clientId = WZ01112. Если у пользователя несколько компаний, он переключается между ними.
2.3. Режим администратора
Пользователь Нубеса видит переключатель «Администратор». В обычном режиме интерфейс как у клиента. При включении — выпадающий список всех компаний, ссылки на аудит и управление лимитами.
3. Управление записями
3.1. Просмотр
Клиент видит таблицу записей своей компании. Администратор выбирает компанию из списка.
Для каждой записи показывается: адрес/подсеть, комментарий, кто добавил, даты создания и изменения. Удалённые записи отображаются зачёркнутыми и полупрозрачными, без кнопок редактирования. Кнопки «Изменить» и «Удалить» — в строке таблицы.
Счётчик: «X из N записей».
3.2. Добавление
Форма: IPv4-адрес или CIDR, комментарий (необязательно, до 255 символов).
Проверки:
- Формат: только IPv4, одиночный адрес или подсеть /22–/32
- Нормализация: хост-биты обнуляются, пользователь уведомляется
- Запрещённые диапазоны: 14 служебных подсетей (RFC1918, CGNAT, loopback и др.)
- Нет дубликатов и пересечений внутри компании
- Лимит компании (по умолчанию 15)
При превышении лимита — блокировка с сообщением.
3.3. Редактирование
Изменение адреса и комментария. Все проверки — как при добавлении.
3.4. Удаление
Логическое (soft delete): запись помечается удалённой, но физически сохраняется. Освобождает место в лимите. Исключается из выгрузки.
4. Лимиты
- По умолчанию: 15 записей на компанию
- Администратор задаёт индивидуальный лимит компании (больше или меньше)
- Снижение лимита не удаляет существующие записи, но блокирует новые
5. Экспорт
Администратор выгружает агрегированный список всех активных CIDR.
- По умолчанию — JSON:
{ cidrs: [...], count: N } ?format=txt— текстовый файл, одна подсеть на строку?company=<id>— выгрузка по конкретной компании
6. Аудит
Все изменения (создание, редактирование, удаление) пишутся в журнал. Записи неизменяемы.
Состав записи: кто сделал, когда, компания, действие, старое и новое значение.
При имперсонации добавляется поле «имперсонировал» — кто на самом деле совершил действие.
Журнал доступен только администратору. Фильтр по компании.
7. Имперсонация
Администратор IAM может «притворяться» другим пользователем или компанией. Приложение получает флаг is_impersonated из IAM.
При активной имперсонации:
- Жёлтый баннер: «Режим имперсонации — от имени Компания (вы: originalUserEmail)»
- CRUD идёт в контексте имперсонируемой компании
- Аудит:
created_by = имперсонируемый,impersonated_by = реальный админ
Без имперсонации impersonated_by = NULL.
8. Интерфейс
- Главная страница: таблица записей, форма добавления, переключатель компаний
- Аудит:
/audit— журнал с фильтром по компании - Лимиты:
/admin— список компаний с лимитами - Экспорт:
/export— выгрузка списка
Шапка: логотип, версия приложения, email пользователя, переключатель «Администратор», кнопка «Выйти».
9. Технологии
Node.js, Express, EJS, PostgreSQL, Keycloak OIDC, IAM API.