Разделы документации

LDAP

Вход через Active Directory или OpenLDAP — настройка подключения, проверка, первый вход и выдача прав.

Как это работает

Archepelag подключается к корпоративному каталогу напрямую, без Keycloak. Подключения настраиваются в самом приложении: Settings → LDAP.

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

Код
Пользователь → вход через LDAP → core-service (search + bind)
  → создание пользователя (JIT) → Settings → Пользователи (роли)

Настройка за 4 шага

Для создания и изменения подключений нужны права admin.

1. Создайте подключение

  1. Войдите в Archepelag под администратором.
  2. Откройте Settings → LDAP.
  3. Нажмите Добавить.

2. Заполните параметры

ПолеЧто указать
НазваниеКак провайдер будет подписан на странице входа, например Corp AD
Протоколldaps для production (порт 636) или ldap для стендов (389 / 1389)
HostХост контроллера домена или LDAP-сервера
PortОбычно 636 для ldaps или 389 для ldap
Base DNКорень поиска пользователей, например DC=company,DC=ru
Service bind DNСервисная учётная запись с правом чтения каталога
Service passwordПароль сервисной учётки — хранится в БД в зашифрованном виде
User search filterФильтр поиска, обязательно содержит %USERNAME%
Login attrАтрибут логина: sAMAccountName, uid и т. п.
Email attrОбычно mail. Без email пользователь не будет создан
АктивноПоказывать ли провайдер на странице входа

Фильтр для Active Directory:

TEXT
(sAMAccountName=%USERNAME%)

Фильтр для OpenLDAP:

TEXT
(uid=%USERNAME%)

3. Проверьте подключение

  1. Нажмите Проверить соединение — должен пройти service bind.
  2. Сохраните подключение.
  3. В блоке Тест поиска введите логин существующего пользователя и нажмите Найти пользователя. В ответе должны быть DN, email и имя.

Если пользователь не находится — проверьте Base DN, фильтр и Login attr. Если не приходит email — заполните атрибут mail в каталоге или укажите другой в Email attr.

4. Включите на странице входа

Отметьте Активно (показывать на логине) и сохраните. Название подключения появится в списке провайдеров на странице входа.

Пример: корпоративный Active Directory

ПолеПример
Protocolldaps
Port636
Base DNOU=Users,DC=company,DC=ru
Bind DNCN=svc-archepelag,OU=Service,DC=company,DC=ru
Filter(sAMAccountName=%USERNAME%)
Login attrsAMAccountName
Email attrmail
First / Last namegivenName / sn

На странице входа пользователь вводит sAMAccountName (обычно короткий логин), а не email — так задано фильтром.

Рекомендации для production:

  • используйте ldaps;
  • не отключайте проверку сертификата (rejectUnauthorized) без крайней необходимости;
  • ограничьте сетевой доступ от core-service до контроллеров домена.

Пример: OpenLDAP в Docker (стенд)

Bash
docker compose -f deploy/docker-compose.dev.yaml up -d openldap
# для prod compose: --profile ldap up -d openldap

Параметры в Settings → LDAP:

ПолеЗначение
Protocolldap
Hostopenldap из Docker-сети или 127.0.0.1 с хоста
Port1389
Base DNdc=appsec,dc=local
Bind DNcn=admin,dc=appsec,dc=local
Bind passwordadminpassword
Filter(uid=%USERNAME%)
Login attruid
Email attrmail

Тестовые пользователи из deploy/openldap/ldifs/01-users.ldif:

UsernameEmailПарольРоль на стенде
ldap-adminldap-admin@appsec.localpassword123Кандидат в admin — роль выдаётся в Settings после входа
team-alphateam-alpha@appsec.localpassword123Пользователь команды A
team-betateam-beta@appsec.localpassword123Пользователь команды B

При входе вводите uid (ldap-admin), а не email.

Первый вход и права

  1. Пользователь выбирает LDAP-провайдер и входит с логином и паролем из каталога.
  2. При первом успешном входе Archepelag создаёт локального пользователя (JIT) и привязывает к нему Account с DN из каталога.
  3. Администратор открывает Settings → Пользователи и назначает роль или отдельные permissions.

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

Типичные ошибки

СимптомЧто проверить
«Проверить соединение» падаетHost, port, bind DN и пароль, сетевой доступ, ldaps и сертификат
Пользователь не находитсяBase DN, фильтр, наличие %USERNAME%, Login attr
«Invalid credentials» при входеПароль в каталоге; проходит ли user bind после поиска
«email already exists»Email занят Internal-пользователем — нужна явная привязка Account (DN)
Пользователь не создаётсяУ пользователя в каталоге нет email
Провайдера нет на странице входаФлаг Активно и сохранение; в dev Vite должен проксировать GET /auth/providers
Пользователь есть, доступа нетРоли в Settings → Пользователи

Чего делать не нужно

  • Настраивать LDAP federation в Keycloak ради входа в Archepelag — вход идёт через core-service.
  • Ждать, что роли подтянутся из LDAP-групп, — права выдаются только в Settings.
  • Хранить bind-пароль в документации или git — только в UI, где он шифруется.