MULTIFACTOR Directory Sync Docker версия

Общая информация

В статье описывается настройка MULTIFACTOR DirectorySync – сервиса для синхронизации пользователей из вашего LDAP каталога в Личный Кабинет МУЛЬТИФАКТОР.

Вариант развертывания в Docker рекомендуется для Linux-серверов, где доступны Docker Engine и Docker Compose.

Компонент доступен вместе с исходным кодом, распространяется бесплатно.
Актуальная версия находится на :

Требования для установки компонента

• Минимальные требования для сервера: 2 CPU, 4 GB RAM, 40 GB HDD (обеспечивают работу ОС и адаптера для 100 одновременных подключений — примерно 1500 пользователей);
• Хост-сервер под управлением Linux с установленным Docker Engine.
• Установленный плагин Docker Compose (Docker Compose Plugin).
• Сетевой доступ со стороны сервера к Multifactor API ( https://api.multifactor.ru ).
• Сетевой доступ к вашему LDAP/LDAPS-серверу.
• Для безопасного подключения LDAPS — наличие корневого CA-сертификата LDAP-сервера.

Схема работы

• MULTIFACTOR Directory Sync обращается к ActiveDirectory используя учетные данные из настроек сервиса - они задаются при установке.
• Подключившись, сервис выгружает всех пользователей из указанной группы (также вложенных в неё групп) - настройка указывается в личном кабинете МУЛЬТИФАКТОР.
• Сервис ищет изменения атрибутов (логин, отображаемое имя,e-mail, телефон) пользователей в LDAP каталоге и передаёт изменения в личный кабинет МУЛЬТИФАКТОР.

Перед началом работы

• Убедитесь, что на сервере с MULTIFACTOR DirectorySync открыты порт 389 TCP (LDAP) и 636 TCP (LDAPS) для отправки запросов на сервер LDAP каталога;
• Серверу с установленным компонентом необходим доступ к хосту api.multifactor.ru по TCP порту 443 (TLS).

Настройка синхронизации в Личном кабинете

1. Зайдите в Личный кабинет, перейдите в раздел “Настройки” и на вкладке “Синхронизация УЗ” включите сервис.

2. На этой же вкладке настройте работу сервиса и сохраните изменения.

• Настройки во вкладке Синхронизация учётных записей:
• Управление сервисом DirectorySync – Включение/выключение сервиса синхронизации.
• API Key – Ключ для синхронизации с облаком МУЛЬТИФАКТОР.
• API Secret – Секрет для синхронизации с облаком МУЛЬТИФАКТОР.
• Периодичность запроса конфигурации из Облака, мин – Интервал запроса актуальной конфигурации из облака, в службу DirectorySync.
• Группы, в которые будут помещены новые пользователи – Необходимо указать группу(ы) из личного кабинета МУЛЬТИФАКТОР, в которую(ые) будут помещены пользователи из AD.
  

Важно

1) Перед установкой службы, внесите настройки в Личном Кабинете Мультифактор, иначе служба не установится.

2) Если планируете использовать группу "AllUsers", оставьте данное поле пустым, поскольку это группа по умолчанию.

• Периодичность поиска новых пользователей, мин – Интервал запроса актуального списка пользователей из AD.
• Периодичность обновления пользователей, мин – Интервал запроса актуального списка атрибутов пользователей из AD.
• Таймаут запроса в Active Directory, сек — задаёт значение таймаута (в секундах) для одного LDAP-запроса при подключении к Active Directory. По умолчанию используется значение 20 секунд
• GUID группы ActiveDirectory – Необходимо указать GUID группы, пользователи которой будут синхронизироваться с личным кабинетом МУЛЬТИФАКТОР. (можно указать только 1 группу)

Для поиска GIUD группы в ActiveDirectory, можете воспользоваться следующей командой в PowerShell:
Get-ADGroup "Domain Admins" | ft ObjectGUID

• Атрибут логина – Указать какой атрибут LDAP каталога, будет использован в поле логин в личном кабинете МУЛЬТИФАКТОР.
• Атрибут имени – Указать какой атрибут LDAP каталога, будет использован в поле имя в личном кабинете МУЛЬТИФАКТОР.
• Атрибуты телефона, разделенные точкой с запятой – Указать какой атрибут LDAP каталога, будет использован в поле телефон в личном кабинете МУЛЬТИФАКТОР.
• Атрибуты почты, разделенные точкой с запятой – Указать какой атрибут LDAP каталога, будет использован в поле почта в личном кабинете МУЛЬТИФАКТОР.
• Отправлять новым пользователям на почту ссылку для настройки 2FA (первый по счету email) – Включение/выключение автоматической отправки ссылки на почту пользователей, если заполнено поле e-mail.
• Срок действия ссылки, мин – указать срок действия ссылки для настройки второго фактора. По умолчанию 25 минут.

3. Скопируйте ключ и секрет.

Подготовка Docker-сервера

Подготовка конфигурационного файла (.env)

Скопируйте шаблон файла конфигурации окружения:

cp deploy/docker/env/.env.prod.example deploy/docker/env/.env.prod

Откройте созданный файл deploy/docker/env/.env.prod на редактирование и заполните
переменные окружения:

DIRECTORYSYNC_IMAGE=ghcr.io/multifactorlab/directorysync:2.0.0
DIRECTORYSYNC_MULTIFACTOR__URL=https://api.multifactor.ru
DIRECTORYSYNC_MULTIFACTOR__KEY=<ключ из ЛК>
DIRECTORYSYNC_MULTIFACTOR__SECRET=<секрет из ЛК>
DIRECTORYSYNC_LDAP__PATH=ldaps://ldap.company.local:636
DIRECTORYSYNC_LDAP__USERNAME=COMPANY\svc-directorysync
DIRECTORYSYNC_LDAP__PASSWORD=<пароль>
DIRECTORYSYNC_STORAGE__DIRECTORY=/app/data
DIRECTORYSYNC_STORAGE__LITEDBFILENAME=storage.db
DIRECTORYSYNC_LOGGING__FILE__ENABLED=true
DIRECTORYSYNC_LOGGING__FILE__PATH=/app/logs/log-.txt
DIRECTORYSYNC_LOGGING__CONSOLE__ENABLED=true
DOTNET_ENVIRONMENT=Production
DOTNET_RUNNING_IN_CONTAINER=true
DIRECTORYSYNC_RUNTIME_MODE=Docker

Важно

Для производственной среды (Production) настоятельно рекомендуется жестко
фиксировать конкретную версию образа контейнера (например, 2.0.0 ), избегая использования
тега latest .

Настройка LDAPS-сертификатов

Если взаимодействие с каталогом осуществляется в защищенном режиме (LDAPS), необходимо
разместить доверенные CA-сертификаты в корневом каталоге развертывания:

mkdir -p certs
cp company-root-ca.crt certs/

Данный каталог автоматически монтируется внутрь контейнера в режиме только чтение по пути /
certs:ro .

Важно

Не помещайте в эту директорию приватные ключи сертификатов.

Установка сервиса

Онлайн-установка

Выполните следующие команды из каталога, где расположены папки deploy/ и certs/ :

# Загрузка актуальных образов
docker compose -f deploy/docker/compose/docker-compose.yml -f deploy/docker/compose/
docker-compose.prod.yml pull

# Запуск контейнера в фоновом режиме
docker compose -f deploy/docker/compose/docker-compose.yml -f deploy/docker/compose/
docker-compose.prod.yml up -d
Multifactor

Офлайн-установка

На рабочей станции, имеющей доступ к публичному реестру контейнеров (registry), скачайте и
экспортируйте образ:

docker pull ghcr.io/multifactorlab/directorysync:2.0.0
docker save ghcr.io/multifactorlab/directorysync:2.0.0 -o directorysync-2.0.0-image.tar

Скопируйте и перенесите на изолированный целевой сервер следующие файлы:

• Архив с образом контейнера: directorysync-2.0.0-image.tar
• Файл базовой структуры: deploy/docker/compose/docker-compose.yml
• Файл конфигурации продукт среды: deploy/docker/compose/docker-compose.prod.yml
• Сконфигурированный файл параметров: deploy/docker/env/.env.prod
• Директорию с сертификатами certs/ (если используется LDAPS).

На целевом закрытом сервере выполните импорт и запуск:

# Загрузка образа в локальный Docker
docker load -i directorysync-2.0.0-image.tar
# Запуск приложения
docker compose -f deploy/docker/compose/docker-compose.yml -f deploy/docker/compose/
docker-compose.prod.yml up -d

Проверка работоспособности и диагностика

Для первичной проверки успешного запуска выполните следующие команды:

# Проверка статуса контейнера
docker ps --filter name=directorysync
# Просмотр последних 100 строк логов
docker logs --tail 100 directorysync
# Проверка состояния healthcheck
docker inspect directorysync --format='{{json .State.Health}}'

Если контейнер успешно запущен, статус проверки здоровья (healthcheck) возвращает положительный
результат, а в логах отсутствуют сообщения об ошибках авторизации в Multifactor или подключения к
LDAP — интеграция выполнена успешно.

Инструменты мониторинга

Важно

При запуске в Docker-контейнере лог ранней инициализации startup.log не
сохраняется на диск сервера. Все стартовые ошибки следует отслеживать через стандартный
вывод командного потока docker logs.

Сопоставление групп между LDAP каталогом и Личным Кабинетом

Схема продемонстрирована на примере Active Directory.

Дальнейшее обозначение:
AD-группа – группа безопасности в Active Directory.

MFA-группа – группа в Личном Кабинете, связанная с AD-группой.

AllUsers – cистемная группа в ЛК, включающая всех пользователей системы.

Функционал сопоставления групп, который включает в себя следующие сценарии поведения:

1. Создание нового пользователя в ЛК

Условие:

Пользователь отсутствует в ЛК, но добавлен в первую отслеживаемую группу AD.

Действия системы:

1. В ЛК автоматически создаётся запись пользователя.
2. Пользователю назначаются МФ-группы, соответствующие его первой AD-группе.
3. Пользователь включается в системную группу AllUsers.

Если AD-группа не имеет сопоставленной MFA-группы, пользователь всё равно создаётся в ЛК и попадает в AllUsers.

2. Добавление пользователя в дополнительные группы AD

Условие:

Пользователь уже существует в ЛК и добавляется во вторую (или последующую) AD-группу.

Действия системы:

1. Членство в AllUsers остаётся без изменений.
2. Пользователь получает доступ к MFA-группам, связанным с новой AD-группой.
3. Сохраняются все ранее назначенные МФ-группы.

3. Удаление пользователя из одной из групп AD

Условие:

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

Действия системы:

1. Членство в AllUsers сохраняется.
2. Пользователь теряет доступ к MFA-группам, связанными с исключаемой AD-группой.
3. Учётная запись в ЛК не удаляется, так как пользователь остаётся в других AD-группах.

4.Полное удаление пользователя из системы

Условие:

Пользователь исключён из последней отслеживаемой группы AD (или отключён/удалён в каталоге).

Действия системы:

1. Учётная запись исчезает из ЛК, так как более не актуальна.
2. Пользователь удаляется из всех связанных MFA-групп.

Если пользователь позже будет добавлен в любую AD-группу, он создаётся в ЛК заново.

Удаление группы из синхронизации

Поведение системы:

1. Пользователи удалённой группы:
   • Не удаляются из ЛК.
   • Сохраняют членство в системной группе All Users.
   • Остаются в целевых группах, с которыми были синхронизированы ранее.
2. Дальнейшая синхронизация:
   • Новые пользователи из удалённой AD-группы не добавляются в ЛК.
   • Существующие пользователи не теряют доступ, если они состоят в других синхронизированных группах.

Рекомендации:

Сброс базы данных синхронизации (временное решение)

Если требуется полный сброс данных синхронизации, выполните следующие шаги:

1. Остановка службы синхронизации.
2. Удаление файла базы данных
   • Перейдите в директорию: C:WindowsSystem32configsystemprofileAppDataLocal[Имя_учетной_записи_службы]Directory Sync
   • Удалите файл: storage.db
3. Перезапуск службы

Автоматизация процесса управления синхронизацией

В последующем релизе планируется реализация автоматического механизма очистки устаревших данных синхронизации.

Мультидоменность (trusted)

Требования к среде:

Для корректной работы службы в мультидоменной среде с доверенными доменами необходимо:

1. Наличие настроенного доверия между доменами

• Домен(ы), из которых требуется получать данные, должны иметь настроенное доверие (trust relationship) с root-доменом:
  • Это может быть parent-child trust или external trust.
• Без доверия доступ к данным будет невозможен
  

2. Учетная запись с достаточными правами

Аккаунт, под которым работает служба, должен иметь права на чтение групп и их членов:

• В основном (root) домене.
• Во всех дочерних доменах, где расположены необходимые группы.
• В доверенных (external trust) доменах, если требуется получать данные из них.

3. Настроенные DNS-разрешения для доверенных доменов

На хосте службы должны быть корректно настроены локальные сопоставления DNS → IP-адресов для всех доверенных доменов. Это обеспечит успешное разрешение имён контроллеров доменов при подключении.

Сценарии, обрабатываемые службой

1. Поиск групп

Служба осуществляет поиск групп в следующих доменных зонах:

• Root domain – основной домен, указанный в конфигурации подключения.
• Дочерние домены (child domains) root-домена.
• External trusted domains – внешние домены, имеющие доверительные отношения с root-доменом.
• Дочерние домены external trusted доменов.

Примечание: поиск в external trusted доменах возможен только при корректной настройке доверия и наличии прав учетной записи службы.

2. Рекурсивный поиск членов групп 

Служба выполняет рекурсивный обход членов групп для всех доменов, начиная с указанного корневого домена, включая его дочерние домены и доверенные домены. При этом рекурсивный поиск вложенных групп поддерживается:

• между доменами и их дочерними доменами (trust type=parent-child);
• внутри external trust (trust type=forest) доменов и их дочерних доменов.

Рекурсивный поиск вложенных групп не выполняется между лесами при forest trust, так как Active Directory не поддерживает вложение групп между лесами для Universal Groups, а использование Global Group возможно только в Domain Local Group другого леса без вложенности.

3. Отслеживание доменов членов групп

В процессе обхода групп:

• Служба сохраняет список доменов, в которых были найдены члены групп.
  Это необходимо для оптимизации дальнейшей обработки и ограничения области поиска при синхронизации атрибутов.

4. Использование списка доменов при синхронизации

При синхронизации атрибутов членов групп:

• Используется список доменов, собранный в ходе предыдущего этапа (п.3).
• Это позволяет контролировать глубину и область поиска, минимизируя нагрузку на LDAP и сетевую инфраструктуру.

Сравнение данных и кэширование

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

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

Для кэширования используется база данных LiteDb. В Docker-версии файлы базы данных (включая storage.db) по умолчанию сохраняются внутри контейнера в директории /app/data/. Чтобы данные не терялись при перезапуске контейнера, эту директорию обычно монтируют на хост-систему как Volume.

Добавление пользователей

При добавлении пользователей при помощи сервиса MULTIFACTOR Directory Sync, к пользователям, добавленным через синхронизацию, будет добавлена «планка» LDAP.

Сервис поддерживает вложенные группы, необходимо выбрать одну группу для синхронизации, далее помещать в неё пользователей или группы.

Удаление/отключение пользователей

Для удаления пользователей из личного кабинета МУЛЬТИФАКТОР, необходимо заблокировать или удалить необходимых вам пользователей или группу пользователей в ActiveDirectory. В случае включения, пользователь вновь появится в личном кабинете МУЛЬТИФАКТОР, но без настроенных методов аутентификации.

Отправка ссылки для настройки второго фактора

MULTIFACTOR Directory Sync поддерживает автоматическую отправку писем на почту, если они указаны в карточке ActiveDirectory. В настройках синхронизации, со стороны личного кабинета МУЛЬТИФАКТОР, необходимо выставить бегунок: «Отправлять новым пользователям на почту ссылку для настройки 2FA (первый по счету email)»  

Изменение настроек сервиса MULTIFACTOR Directory Sync

Вы можете изменить настройки в файле: MultifactorDirectory Syncappsettings.json

Секция, отвечающая за логирование:

"Logging": {
"File": {
"RollingInterval": "Day",  //применим из: https://github.com/serilog/serilog-sinks-file/blob/dev/src/Serilog.Sinks.File/RollingInterval.cs
"FileSizeLimitBytes": 500000,  // Размер 1 файла логов
"RetainedFileCountLimit": 20,  //лимит кол-ва сохраняемых файлов
"MinimalLevel": "Debug",  //применим из: https://github.com/serilog/serilog-sinks-file/blob/dev/src/Serilog.Sinks.File/RollingInterval.cs
"Template": ""

где:

• "RollingInterval": "Day" — применим из: https://github.com/serilog/serilog-sinks-file/blob/dev/src/Serilog.Sinks.File/RollingInterval.cs
• "FileSizeLimitBytes": 500000 — размер 1 файла логов
• "RetainedFileCountLimit": 5 — лимит кол-ва сохраняемых файлов
• "MinimalLevel": "Debug" — уровень логирования может быть Info, Error, Warning, Debug

Удаление сервиса MULTIFACTOR Directory Sync

Чтобы остановить и удалить контейнер с сохранением всех накопленных локальных данных и логов,
выполните:

docker compose \
  -f deploy/docker/compose/docker-compose.yml \
  -f deploy/docker/compose/docker-compose.prod.yml \
  down

Для полного удаления контейнера вместе со всеми ассоциированными томами (volumes) очистки
данных выполните:

docker compose \
  -f deploy/docker/compose/docker-compose.yml \
  -f deploy/docker/compose/docker-compose.prod.yml \
  down -v

Используемые Docker Volumes::

• directorysync-data — данные приложения;
• directorysync-logs — логи приложения.

Обновление сервиса MULTIFACTOR Directory Sync

Для обновления сервиса MULTIFACTOR Directory Sync, его необходимо удалить, далее поставить новую версию сервиса:

Откройте файл конфигурации параметров deploy/docker/env/.env.prod .
Отредактируйте значение переменной DIRECTORYSYNC_IMAGE, указав новую целевую версию
(например: ghcr.io/multifactorlab/directorysync:2.0.1 ):

DIRECTORYSYNC_IMAGE=ghcr.io/multifactorlab/directorysync:2.0.1

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

docker compose \
  -f deploy/docker/compose/docker-compose.yml \
  -f deploy/docker/compose/docker-compose.prod.yml \
  pull

docker compose \
  -f deploy/docker/compose/docker-compose.yml \
  -f deploy/docker/compose/docker-compose.prod.yml \
  up -d

Вопросы и ответы

Распространенные проблемы и причины ошибок

Важно

При запуске в Docker-контейнере лог ранней инициализации startup.log не
сохраняется на диск сервера. Все стартовые ошибки следует отслеживать через стандартный
вывод командного потока docker logs.

• Стоит проверить заполнены ли поля со стороны личного кабинета.
• Указано неверное или несуществующее имя/тег образа в переменной DIRECTORYSYNC_IMAGE.
• Отсутствуют или некорректно заполнены параметры API-доступа:
  DIRECTORYSYNC_MULTIFACTOR__KEY или DIRECTORYSYNC_MULTIFACTOR__SECRET.
• Неверно сформирована строка подключения к каталогу в DIRECTORYSYNC_LDAP__PATH.
• Отсутствует сетевая связность (маршрутизация/правила файрволла) до LDAP/LDAPS серверов.
• Корневой CA-сертификат цепочки не был скопирован в директорию или не смонтирован по пути /certs.
• Файл параметров .env.prod отсутствует, переименован или расположен вне ожидаемой Docker директории.