Интеграция LDAP / Active Directory с PanDev Metrics on-prem
Кратко. Гайд подключает on-prem PanDev Metrics к LDAP или Active Directory примерно за 20 минут. К концу процедуры сотрудники входят с корпоративными кредами, новые пользователи провижинятся при первом входе, IDE-плагины переиспользуют ту же identity. Аудитория: администратор.
Что понадобится
- PanDev Metrics on-prem установлен и доступен
- Достижимый LDAP или AD-сервер с TLS на порту 636 (LDAPS) — plain
ldap://на 389 тоже работает, но не рекомендуется - Сервисный аккаунт в каталоге с правом читать пользовательские записи — bind DN и пароль
- Base DN, где живут пользователи (например,
ou=Users,dc=example,dc=com) - Атрибут поиска, под которым пользователи логинятся — обычно
sAMAccountNameдля Active Directory илиmail/uidдля OpenLDAP
LDAP — единственный SSO, поддерживаемый в on-prem PanDev Metrics на сегодня. SAML, OIDC и Google sign-in в on-prem недоступны. Закладывайте LDAP под любое требование single sign-on.
Шаг 1 — Решите, где настраивать LDAP
Есть два варианта: настроить LDAP через админ-UI после первого входа или задать env-переменные в .env ещё до первого старта. Оба пути приходят в одну точку — env-переменные перекрывают значения UI при рестарте backend.
UI-вариант рекомендуется для уже работающей инсталляции — кнопка Test connection даёт мгновенный фидбек. Env-вариант предпочтителен, когда конфигурация хранится в infrastructure-as-code.
Шаг 2 — Настройте LDAP через env-переменные
Добавьте переменные ниже в .env на application-хосте. Подставьте значения вашего каталога:
LDAP_INTEGRATION_ENABLED=true
LDAP_URL=ldaps://ldap.example.com:636
LDAP_USER_SEARCH_BASE=ou=Users,dc=example,dc=com
LDAP_USER_SEARCH_ATTRIBUTE=sAMAccountName
LDAP_ADMIN_USERNAME=cn=svc-pandev,ou=Service Accounts,dc=example,dc=com
LDAP_ADMIN_PASSWORD=<STRONG_SERVICE_PASSWORD>
| Переменная | Назначение | Пример |
|---|---|---|
LDAP_INTEGRATION_ENABLED | Главный переключатель | true |
LDAP_URL | URL каталога со схемой и портом | ldaps://ldap.example.com:636 |
LDAP_USER_SEARCH_BASE | Base DN для поиска пользователей | ou=Users,dc=example,dc=com |
LDAP_USER_SEARCH_ATTRIBUTE | Атрибут, под которым пользователи логинятся | sAMAccountName, mail, uid |
LDAP_ADMIN_USERNAME | Bind DN read-only сервисного аккаунта | cn=svc-pandev,ou=Service Accounts,dc=example,dc=com |
LDAP_ADMIN_PASSWORD | Пароль bind DN | <STRONG_SERVICE_PASSWORD> |
Примените изменения:
docker compose up -d --force-recreate pandev-metrics
Шаг 3 — Настройте LDAP через UI
Войдите как администратор и откройте Настройки → Основные настройки → Ldap.
Заполните каждое поле теми же значениями, что и в env-переменных шага 2:
| Поле | Что вводить |
|---|---|
| LDAP URL | ldaps://ldap.example.com:636 (или ldap:// для plain LDAP) |
| LDAP search base | Base DN для поиска пользователей |
| LDAP search attribute | Атрибут, под которым пользователи логинятся (sAMAccountName, mail, uid) |
| LDAP admin username | Bind DN сервисного аккаунта |
| Password | Пароль сервисного аккаунта |
Нажмите Test connection and save. PanDev Metrics свяжется через сервисный аккаунт, прогонит пробный поиск и сохранит настройки только после успеха.
Шаг 4 — Проверьте интеграцию
Выйдите из админской сессии и войдите под LDAP-аккаунтом, который существует в указанной search base. Первый вход создаст запись пользователя автоматически — новый пользователь появится в Настройки → Пользователи без назначенной роли.
Проверьте, что health endpoint actuator после изменения остаётся UP:
curl -fsS http://localhost:9090/actuator/health | jq '.status'
# → "UP"
Роли не назначаются автоматически. Администратор должен выдать роль (Owner, Maintainer или Viewer), прежде чем новый пользователь сможет работать в продукте.
Решение проблем
Test connection падает с Cannot connect to LDAP server
Backend-контейнер не достучался до каталога. Проверьте три вещи:
- Hostname URL резолвится из контейнера:
docker exec pandev-metrics-app getent hosts ldap.example.com. - Порт открыт из контейнера:
docker exec pandev-metrics-app nc -vz ldap.example.com 636. - Цепочка сертификатов LDAP-сервера валидна, или вы используете plain
ldap://для теста.
Test connection падает с Invalid credentials (LDAP result code 49)
Неверны bind DN или пароль. Уточните DN сервисного аккаунта в инструменте управления каталогом — DN должен быть полным путём, а не просто username. Проверьте bind с другой машины через ldapsearch, чтобы локализовать проблему (PanDev или каталог).
Вход пользователя падает с user not found in LDAP
Пользователь существует в каталоге, но вне LDAP_USER_SEARCH_BASE, или LDAP_USER_SEARCH_ATTRIBUTE не совпадает с тем, что пользователь вводит. Проверьте запросом к каталогу: ldapsearch -b "ou=Users,dc=example,dc=com" "(sAMAccountName=<USER>)".
Пользователь вошёл, но видит экран «access denied»
Пользователь провижинен в PanDev Metrics, но у него нет роли. Администратор должен открыть Настройки → Пользователи, найти пользователя и назначить роль (Owner, Maintainer или Viewer).
LDAPS-подключение падает с ошибкой TLS-сертификата
TLS-сертификату каталога не доверяет Java-truststore backend. Либо положите вашу CA-цепочку в контейнер backend, либо терминируйте TLS на reverse proxy перед LDAP-сервером и подключайтесь по ldap:// через внутреннюю сеть.
FAQ
Поддерживает ли PanDev Metrics on-prem SAML или OIDC?
Нет. На сегодня LDAP — единственный SSO в on-prem PanDev Metrics. SAML и OIDC недоступны. Если ваш identity provider не отдаёт LDAP, обычно его можно завернуть в directory-прокси (FreeIPA, Authentik), который умеет LDAP — но это работа на вашей стороне, а не в PanDev Metrics.
А Google sign-in?
Google sign-in — только Cloud. В on-prem-дистрибутиве его нет. Оставьте GOOGLE_AUTH_ENABLE=false в .env — это значение для on-prem по умолчанию.
Синхронизирует ли PanDev Metrics группы из LDAP?
PanDev Metrics аутентифицирует пользователей через LDAP, но автоматическую синхронизацию групп пока не делает. Привязка к департаментам и командам делается внутри PanDev Metrics после провижининга пользователя. Маппинг групп на роли — в roadmap.
Что произойдёт с пользователем, отключённым в каталоге?
Пользователь больше не сможет залогиниться — LDAP-bind упадёт. Запись пользователя в Настройки → Пользователи останется, пока администратор не заархивирует её. Архивация сохраняет историческую атрибуцию метрик.
Можно ли подключить несколько LDAP-серверов?
On-prem PanDev Metrics подключается к одному каталогу за раз. Если у вас несколько форестов, используйте directory-прокси или реплицируйте пользователей в одну search base.
Пароль bind хранится в зашифрованном виде?
Пароль bind хранится в зашифрованной таблице конфигурации backend. К .env относитесь так же бережно — держите chmod 600 и вне репозитория.
Дальнейшие шаги
- Управление пользователями и ролями — назначение ролей провижиненным через LDAP пользователям
- Сеть и порты — проверьте LDAP-egress с application-хоста
- Установка PanDev Metrics on-prem — для свежих инсталляций, которые сразу настраиваются с LDAP
Связанные материалы
- Reference: Системные требования
- Концепция: Архитектура on-prem