LDAP-каталог

Обзор

Интеграция с LDAP решает две разные задачи, и их полезно различать с самого начала:

• Аутентификация — кто пользователь. Пароль проверяется не в Meridian, а в каталоге: Meridian выполняет bind от имени пользователя и не хранит его хеш.
• Синхронизация прав — что ему разрешено. Периодический обход каталога переводит членство в группах и значения атрибутов в привязки ролей Meridian (role bindings).

Возможность опциональна и аддитивна: без блока ldap в config.json ничего не меняется, а с ним локальные учётные записи продолжают работать ровно как раньше. Интеграция входит во все редакции — community, pro и enterprise — без отдельной лицензии и без флагов сборки.

Ключевые свойства:

• Единственный писатель. Права из каталога записывает только лидер кластера. Аутентифицировать может любой узел, но изменять учётные записи и привязки — один.
• Отказ в закрытую сторону. Недоступность каталога приводит к отказу входа и к неуспешному циклу синхронизации, но ничего не деактивирует: уже выданные сессии продолжают работать, локальные учётные записи не затрагиваются.
• Настройки подключения живут только в файле. Блок ldap никогда не попадает в хранилище конфигурации и не редактируется через API — он читается из config.json при старте. Пароль сервисной учётной записи, таким образом, не может утечь через экспорт конфигурации.
• Правила сопоставления, наоборот, живут в базе и редактируются в панели управления во время работы.

Подключение каталога

Минимальная рабочая конфигурация — семь полей. Всё остальное имеет разумные значения по умолчанию.

{
  "governance": {
    "auth_config": {
      "is_enabled": true,
      "admin_username": "admin",
      "admin_password": "env.MERIDIAN_ADMIN_PASSWORD",
      "ldap": {
        "enabled": true,
        "url": "ldaps://ldap.example.com:636",
        "bind_dn": "uid=meridian-svc,ou=people,dc=example,dc=com",
        "bind_password": "env.MERIDIAN_LDAP_BIND_PASSWORD",
        "user_base": "ou=people,dc=example,dc=com",
        "user_filter": "(&(objectClass=person)(uid=%s))"
      }
    }
  }
}

Основные параметры

Права сервисной учётной записи

Учётная запись из bind_dn только ищет и никогда не пишет в каталог. Достаточно доступа на чтение к поддереву пользователей, к поддереву групп (если включён group_search_enabled) и к вычислению фильтров на отдельных записях.

Предпочитайте ldaps://: и служебный bind, и bind самого пользователя передают пароль в открытом виде, поэтому обычный ldap:// допустим только в доверенном сегменте сети или в локальном тестовом стенде. skip_tls_verify — исключительно для разработки.

Как каталог превращается в роли

Одновременно работают три источника, и их результаты объединяются.

Метод A — группа каталога → (роль, область)

Правило связывает DN группы с парой «роль + область»:

cn=acme-admins,ou=groups,dc=example,dc=com  →  s.admin @ customer «Acme»

Сопоставление — точное совпадение строк в нижнем регистре, без шаблонов и без учёта вложенности поддерева. Одна группа может нести несколько правил, все они применяются. Это подходящий метод, когда модель доступа уже закодирована членством в группах и менять схему каталога не хочется.

Метод B — атрибут meridianScopeRole

Многозначный атрибут пользовательской записи несёт назначения напрямую:

Средняя часть — псевдоним, а не идентификатор. Данные каталога не должны нести UUID Meridian, поэтому псевдонимы регистрируются отдельно (вкладка Scope mappings) и разрешаются на каждом цикле синхронизации.

Некорректное значение пропускается с предупреждением и не влияет на остальные значения того же пользователя: неизвестная роль, неизвестный псевдоним, псевдоним не того типа, роль, не привязываемая к такой области. Каждый такой пропуск попадает в журнал синхронизаций отдельной строкой — с самим значением и причиной.

admin_filter

Самый короткий путь к первому администратору: один фильтр в config.json, без правил и без атрибутов. Все, кто ему соответствует, получают g.admin на глобальной области.

Это правило живёт в файле, а не в базе, поэтому в таблице сопоставлений оно показано закреплённой строкой с пометкой config.json и без кнопок редактирования — чтобы правило, выдающее административные права, было видно на той же странице, где перечислены остальные.

Панель управления

Раздел Settings → LDAP появляется, когда каталог настроен и аутентификация включена. Он доступен только глобальным ролям: справочник в кластере один, поэтому администратору отдельного клиента или команды здесь нечего делать.

Если блок ldap не настроен, страница показывает краткую справку о том, что настройки живут в config.json и применяются после перезапуска.

Groups mappings

Таблица правил метода A: DN группы, роль, область, дата создания. Есть поиск по DN, фильтры по роли, типу области и конкретной области, сортировка и постраничный вывод по 50 строк.

Создание и редактирование — в боковой панели: DN группы, роль (список фильтруется по выбранному типу области), тип области и сама область с поиском по мере ввода.

Scope mappings

Реестр псевдонимов метода B: псевдоним → клиент или команда. Псевдоним проверяется по шаблону ^[a-z0-9_-]{1,255}$ ещё до отправки формы.

Synchronizations

Состояние и история:

• Шапка состояния — включённость, хост каталога, интервал, текущий уровень журнала, статус последнего цикла, время последнего запуска и последнего успеха, счётчики. Ошибка последнего цикла показывается отдельным предупреждением.
• Кнопка Force sync — запустить обход немедленно, не дожидаясь таймера. В кластере запрос автоматически перенаправляется на узел-лидер, поэтому обращаться можно к любому узлу.
• Журнал синхронизаций — фильтры по уровню, коду события, идентификатору запуска и времени. У каждой строки есть копирование в YAML: полная запись со всеми деталями попадает в буфер обмена одним нажатием — удобно вставлять в тикет.

Журнал синхронизаций

Строка состояния отвечает на вопрос «как каталог себя чувствует сейчас». Журнал отвечает на вопрос «что произошло в том цикле, который упал час назад» — и именно он превращает счётчик values_skipped: 5 в пять конкретных строк с значением, пользователем и причиной.

Уровни

sync_log_level — это лестница: каждый уровень включает всё, что записывает уровень ниже.

Один запуск ограничен 5000 событиями: по достижении лимита записывается одна строка events_suppressed, и остаток цикла в журнал не пишется. Записи старше sync_log_retention_days удаляются раз в два часа на узле-лидере.

Запись журнала — операция best-effort: её сбой попадает в лог узла и никогда не влияет на сам цикл синхронизации.

Метрики

Восемь серий Prometheus доступны на /metrics, все с меткой node_id (обход выполняет только лидер, а лидерство перемещается):

Все серии инициализируются нулями при старте, поэтому rate(ldap_sync_users_total{outcome="failed"}[15m]) > 0 корректно работает и на узле, который ещё не выполнил ни одного цикла. Если каталог не настроен, серии ldap_sync_* не публикуются вовсе.

Ограничение на число учётных записей

Число учётных записей из каталога ограничено редакцией:

Ограничение считает только учётные записи. Правила сопоставления, псевдонимы и привязки ролей не ограничены ничем.

Лимит действует в трёх местах:

• При обходе каталога — сколько записей обрабатывается за цикл. Если каталог вернул больше записей, чем разрешено, синхронизируются первые N в алфавитном порядке имён; остальные попадают в счётчик users_skipped. Никто при этом не деактивируется — превышение лимита не отзывает права у уже заведённых пользователей. В журнал пишется строка directory_size_limit_reached, а ldap_sync_directory_over_limit переходит в 1.
• При обходе каталога — сколько учётных записей становится активными. Цикл может создать (или снова включить) ровно столько записей, сколько остаётся до лимита: «лимит минус число активных учётных записей из каталога». Поэтому запись может попасть в первые N по алфавиту и всё равно получить отказ, если место уже занято — в журнал пишется одна строка directory_cap_reached за цикл. Запись, созданная сразу отключённой (ограниченная фильтром или группой), место не занимает; когда каталог снимает ограничение, её повторное включение расходует место так же, как создание. Если число учётных записей не удалось прочитать, за цикл не создаётся и не включается ничего, а в журнале появляется directory_count_failed — это сбой базы, а не достигнутый лимит.
• При первом входе нового пользователя. Если лимит уже достигнут, учётная запись не создаётся и вход отклоняется — с тем же ответом, что и при неверном пароле. Отказ виден в журнале как jit_create_refused.

Правильное решение при превышении — сузить user_filter, чтобы каталог возвращал только нужную аудиторию, либо перейти на старшую редакцию. Отключённая учётная запись освобождает место на следующем цикле.

Что происходит при входе

1. Meridian находит учётную запись и смотрит, кто отвечает за её пароль. Для local — прежняя проверка хеша, каталог не участвует вовсе.
2. Для ldap пустой пароль отклоняется до обращения к сети. Затем выполняется bind сервисной учётной записи, поиск пользователя по user_filter и bind уже от имени найденного DN.
3. Ноль совпадений или больше одного — отказ: неоднозначный каталог не угадывается.
4. Любая ошибка сводится к одному ответу, поэтому «нет такого пользователя», «неверный пароль» и «каталог недоступен» снаружи неразличимы.

Пользователь, которого обход ещё не завёл, может войти сразу: учётная запись создаётся на месте — пустая, без единой привязки. Права приходят со следующим циклом. Ограничения (restricted_user_filter, restricted_group_dns) на этом пути проверяются немедленно, потому что отвечать по флагу «отключён» ещё нечему.

Проверка Basic кешируется на 60 секунд для успеха и на 10 — для отказа, чтобы каждый вызов inference не превращался в обращение к каталогу. Сама запись пользователя перечитывается всегда, поэтому отключение учётной записи вступает в силу со следующего же запроса.

Отзыв доступа

Ручные привязки (source: manual) синхронизация не трогает никогда — она владеет только строками с source: ldap.

Предохранители

Опечатка в user_base превращает здоровый каталог в «ноль пользователей», а опечатка в attribute_username — в «записи, чьи имена нечитаемы», что по числу записей выглядит совершенно нормально. Без защиты любой из этих случаев отключил бы все LDAP-учётные записи установки разом.

• Пропорциональный клапан деактивации. Цикл, который отключил бы больше половины активных LDAP-аккаунтов (и больше двух), отклоняется, а сам цикл помечается неуспешным — молчаливый предохранитель не предохранитель. Обычное увольнение далеко ниже порога и обрабатывается как обычно. allow_deactivate_all: true — это осознанное заявление, что потерять большую часть каталога разом допустимо.
• Пустой обход групп — это отсутствие ответа, а не «никто ни в чём не состоит». В обратном режиме (group_search_enabled) цикл прерывается до записи чего бы то ни было, если обход не разрешил ни одного членства, а сопоставления групп или ограничивающие группы настроены.
• Неоднозначное имя не идентифицирует никого. Если две записи каталога дают одно имя пользователя, обе пропускаются с ошибкой, а имя помечается как увиденное — существующая учётная запись не деактивируется и сохраняет права, выданные последним однозначным циклом.
• Ошибка проверки — не приговор. Если фильтр не удалось вычислить или проверку области не удалось выполнить, запись оставляется полностью в покое: «не смог решить» никогда не приводит к отзыву прав.

Ограничения

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