MULTIFACTOR Directory Sync Linux версия

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

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

Сервис развернут в ОС Linux Ubuntu и настроен как системный демон под управлением systemd. Решение обеспечивает автоматическую синхронизацию и передачу пользовательских данных из домена Active Directory (через протоколы LDAP/LDAPS) в консоль управления Мультифактор.

Важно

Для остальных Linux ОС рекомендуется вариант развертывания в Docker, где доступны Docker Engine и Docker Compose.

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

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

• Операционная система: Ubuntu 22.04 LTS / 24.04 LTS (архитектура x86_64 или arm64).
• Права доступа: Административный доступ со свойствами суперпользователя ( root ).
• Сетевые доступы:
  • Исходящий доступ к Multifactor API: https://api.multifactor.ru (порт 443).
  • Исходящий доступ к контроллерам домена LDAP (порт 389) или LDAPS (порт 636).
  • Для LDAPS — CA-сертификат LDAP-сервера.
• Минимальные требования для сервера: 2 CPU, 4 GB RAM, 40 GB HDD (обеспечивают работу ОС и адаптера для 100 одновременных подключений — примерно 1500 пользователей);

Схема работы

• 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. Скопируйте ключ и секрет.

Подготовка сервера Ubuntu

Установите необходимые системные библиотеки:

sudo apt-get update
sudo apt-get install -y libldap-2.5-0 libldap-common libsasl2-2 libsasl2-modules unzip

Настройте соответствие IP-адреса и имени контроллера домена в /etc/hosts:

sudo nano /etc/hosts

192.168.1.100 domain.local dc01.domain.local

Распаковка архива

Создайте рабочие папки и распакуйте установщик:

mkdir -p /home/username/certs
mkdir -p /home/username/offline-install
tar -xzf /home/username/directorysync_2.0.0_linux-x64-offline.tar.gz -C /home/username/offline-install/
cd /home/username/offline-install/

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

Создайте runtime-файл переменных окружения службы. Файл должен быть размещен в безопасном месте до
момента установки демона.

nano /home/username/directorysync.env

Внесите в файл следующие параметры, заменив демонстрационные значения на ваши актуальные данные:

# Параметры интеграции с API Мультифактор
DIRECTORYSYNC_MULTIFACTOR__URL=https://api.multifactor.ru
DIRECTORYSYNC_MULTIFACTOR__KEY=ds_your_source_key_here
DIRECTORYSYNC_MULTIFACTOR__SECRET=your_source_secret_here

# Настройки подключения к службе каталогов (LDAP / LDAPS)
DIRECTORYSYNC_LDAP__PATH=ldaps://ldap.company.local:636
DIRECTORYSYNC_LDAP__USERNAME=COMPANY\svc-directorysync
DIRECTORYSYNC_LDAP__PASSWORD=your_secure_password_here

# Системные пути хранения данных и файлов журналов
DIRECTORYSYNC_STORAGE__DIRECTORY=/var/lib/directorysync/data
DIRECTORYSYNC_LOGGING__FILE__PATH=/var/log/directorysync/log-.txt

# Параметры запуска контейнера/сервиса .NET
DOTNET_ENVIRONMENT=Production
DIRECTORYSYNC_RUNTIME_MODE=LinuxSystemd

Важно

Ограничьте права доступа к файлу конфигурации, содержащему критические
секреты интеграции и пароль учетной записи LDAP:

chmod 600 /home/username/directorysync.env

Строку подключения к LDAP можно указывать в стандартной форме, в том числе с контейнером.

Подготовка к работе с LDAPS

Если вы используете протокол LDAPS (порт 636), необходимо настроить доверие к корневому сертификату (Root CA) вашего контроллера домена:

Экспорт сертификата:

• На контроллере домена Windows откройте mmc и добавьте оснастку «Сертификаты» (для учетной записи компьютера).
• Перейдите в Trusted Root Certification Authorities → Certificates.
• Экспортируйте ваш Root CA в формате Base-64 encoded X.509 (.CER).

Размещение на сервере:

• Создайте директорию на Linux-сервере (например, /home/username/certs/) и сохраните туда полученный файл сертификата.

Конфигурация:

• В файле directorysync.env добавьте следующие параметры:

# Настройки безопасности OpenLDAP для LDAPS
LDAPTLS_CACERTDIR=/home/username/certs
LDAPTLS_REQCERT=demand

• Убедитесь, что в DIRECTORYSYNC_LDAP__PATH указан путь с использованием протокола ldaps:// и порта 636.

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

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

• Перед началом установки загрузите из соответствующего релиза следующие элементы:
• Скрипт install.sh
• Каталог lib/
• Скрипт uninstall.sh (рекомендуется скачать для возможности последующего удаления системы)

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

sudo bash install.sh \
  --version v2.0.0 \
  --env-file-path ./directorysync.env \
  --validate-config strict \
  --unattended

LDAPS версия:

sudo bash install.sh \
  --version v2.0.0 \
  --env-file-path ./directorysync.env \
  --cert-dir ./certs \
  --validate-config strict \
  --unattended

Устранение ошибок зависимостей

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

sudo bash install.sh \
  --version v2.0.0 \
  --env-file-path ./directorysync.env \
  --install-deps \
  --validate-config strict \
  --unattended

LDAPS версия:

sudo bash install.sh \
  --version v2.0.0 \
  --env-file-path ./directorysync.env \
  --cert-dir ./certs \
  --install-deps \
  --validate-config strict \
  --unattended

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

• Подготовьте директорию directorysync-offline/, содержащую все необходимые файлы:
• install.sh и uninstall.sh
• Каталог lib/
• Архив с приложением:
  • Для архитектуры x64: directorysync_2.0.0_linux-x64.tar.gz
  • Для архитектуры ARM64: directorysync_2.0.0_linux-arm64.tar.gz
• checksums.txt (файл контрольных сумм)
• directorysync.env (файл конфигурации)
• Каталог certs/ с необходимыми сертификатами (например, company-root-ca.crt)

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

sudo bash install.sh \
  --tarball ./directorysync_2.0.0_linux-x64.tar.gz \
  --checksum-file ./checksums.txt \
  --env-file-path ./directorysync.env \
  --validate-config strict \
  --skip-checks \
  --allow-unverified \
  --reset-all-state \
  --unattended

LDAPS версия:

sudo bash install.sh \
  --tarball ./directorysync_2.0.0_linux-x64.tar.gz \
  --checksum-file ./checksums.txt \
  --env-file-path ./directorysync.env \
  --cert-dir ./certs \
  --validate-config strict \
  --skip-checks \
  --allow-unverified \
  --reset-all-state \
  --unattended

Важно

Если вы используете архитектуру ARM64, замените имя файла в параметре --tarball на directorysync_2.0.0_linux-arm64.tar.gz

Проверка статуса установки

После завершения процесса установки проверьте корректность работы службы:

systemctl status directorysync
journalctl -u directorysync -n 100 --no-pager

Установка считается успешно завершенной, если сервис находится в активном состоянии (active), запущен и успешно установил соединение с Multifactor и LDAP.

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

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

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

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

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

Сопоставление групп между 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, а файлы базы данных лежат в директории профиля учетной записи, от имени которой запущен сервис: %localappdata%MultifactorDirectory Sync
Кэширование нужно для того, чтобы не перегружать Облако МФ и ускорить работу сервиса.

Значение переменной %localappdata% зависит от того, от имени какой учетной записи запущен сервис:
- от имени системной учетной записи: C:WindowsSystem32configsystemprofileAppDataLocal
- от имени учетной записи локального пользователя: C:Users{имя пользователя}AppDataLocal
Запуск сервиса от имени определенной учетной записи настраивается во вкладке “Вход в систему” свойств сервиса:

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

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

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

Изменение логина пользователя

При изменении соответствующего атрибута логина пользователя в Active Directory, Directory Sync автоматически обновляет соответствующее поле в Личном кабинете.
При следующей итерации синхронизации система подтянет актуальный логин из Active Directory и применит его к существующей записи, сохраняя при этом все привязки пользователя.

Изменения вступают в силу после очередного цикла синхронизации Directory Sync. Дополнительных действий в Личном кабинете для этого не требуется.

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

Для удаления пользователей из личного кабинета МУЛЬТИФАКТОР, необходимо заблокировать или удалить необходимых вам пользователей или группу пользователей в 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

Для удаления самого сервиса с сохранением конфигурации, логов и пользовательских данных выполните::

sudo bash uninstall.sh --unattended

Для удаления сервиса вместе со всей конфигурацией, логами и данными используйте флаг --purge

sudo bash uninstall.sh --purge --unattended

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

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

Обновление в онлайн-режиме

Если сервер имеет доступ к репозиториям, выполните команду:

sudo bash install.sh \
  --version v2.0.1 \
  --env-file-path ./directorysync.env \
  --cert-dir ./certs \
  --unattended

Обновление в офлайн-режиме

Если сервер изолирован, заранее скачайте архив новой версии и файл контрольных сумм. Выполните команду:

sudo bash install.sh \
  --tarball ./directorysync_2.0.1_linux-x64.tar.gz \
  --checksum-file ./checksums.txt \
  --env-file-path ./directorysync.env \
  --cert-dir ./certs \
  --unattended

Важно

Перед обновлением убедитесь, что пути к файлу окружения (--env-file-path) и директории сертификатов (--cert-dir) указаны верно относительно текущего местоположения скрипта.

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

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

• Неверный LDAP path: проверьте правильность указанного пути к LDAP-серверу.
• неверный ключ или секрет Multifactor: убедитесь в корректности ключа (API Key) и секрета (API Secret).
• Сетевая доступность:
  • нет доступа к Multifactor API: Проверьте наличие доступа от сервера к Multifactor API.
  • нет доступа к LDAP/LDAPS: Проверьте наличие доступа от сервера к LDAP/LDAPS (порт, правила firewall).

• LDAPS-сертификат не добавлен: убедитесь, что LDAPS-сертификат корректно добавлен в доверенные или указан в конфигурации.
• env-файл недоступен сервисному пользователю: убедитесь, что файл конфигурации (.env) доступен для чтения системному пользователю, от имени которого запущен сервис.