LDAP
Вход через Active Directory или OpenLDAP — настройка подключения, проверка, первый вход и выдача прав.
Как это работает
Archepelag подключается к корпоративному каталогу напрямую, без Keycloak. Подключения настраиваются в самом приложении: Settings → LDAP.
На странице входа каждое активное подключение появляется отдельным провайдером. Провайдер Internal — локальные пользователи с паролем — доступен всегда.
Пользователь → вход через LDAP → core-service (search + bind)
→ создание пользователя (JIT) → Settings → Пользователи (роли)Настройка за 4 шага
Для создания и изменения подключений нужны права admin.
1. Создайте подключение
- Войдите в Archepelag под администратором.
- Откройте Settings → LDAP.
- Нажмите Добавить.
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:
(sAMAccountName=%USERNAME%)Фильтр для OpenLDAP:
(uid=%USERNAME%)3. Проверьте подключение
- Нажмите Проверить соединение — должен пройти service bind.
- Сохраните подключение.
- В блоке Тест поиска введите логин существующего пользователя и нажмите Найти пользователя. В ответе должны быть DN, email и имя.
Если пользователь не находится — проверьте Base DN, фильтр и Login attr. Если не приходит email — заполните атрибут mail в каталоге или укажите другой в Email attr.
4. Включите на странице входа
Отметьте Активно (показывать на логине) и сохраните. Название подключения появится в списке провайдеров на странице входа.
Пример: корпоративный Active Directory
| Поле | Пример |
|---|---|
| Protocol | ldaps |
| Port | 636 |
| Base DN | OU=Users,DC=company,DC=ru |
| Bind DN | CN=svc-archepelag,OU=Service,DC=company,DC=ru |
| Filter | (sAMAccountName=%USERNAME%) |
| Login attr | sAMAccountName |
| Email attr | mail |
| First / Last name | givenName / sn |
На странице входа пользователь вводит sAMAccountName (обычно короткий логин), а не email — так задано фильтром.
Рекомендации для production:
- используйте ldaps;
- не отключайте проверку сертификата (
rejectUnauthorized) без крайней необходимости; - ограничьте сетевой доступ от core-service до контроллеров домена.
Пример: OpenLDAP в Docker (стенд)
docker compose -f deploy/docker-compose.dev.yaml up -d openldap
# для prod compose: --profile ldap up -d openldapПараметры в Settings → LDAP:
| Поле | Значение |
|---|---|
| Protocol | ldap |
| Host | openldap из Docker-сети или 127.0.0.1 с хоста |
| Port | 1389 |
| Base DN | dc=appsec,dc=local |
| Bind DN | cn=admin,dc=appsec,dc=local |
| Bind password | adminpassword |
| Filter | (uid=%USERNAME%) |
| Login attr | uid |
| Email attr | mail |
Тестовые пользователи из deploy/openldap/ldifs/01-users.ldif:
| Username | Пароль | Роль на стенде | |
|---|---|---|---|
ldap-admin | ldap-admin@appsec.local | password123 | Кандидат в admin — роль выдаётся в Settings после входа |
team-alpha | team-alpha@appsec.local | password123 | Пользователь команды A |
team-beta | team-beta@appsec.local | password123 | Пользователь команды B |
При входе вводите uid (ldap-admin), а не email.
Первый вход и права
- Пользователь выбирает LDAP-провайдер и входит с логином и паролем из каталога.
- При первом успешном входе Archepelag создаёт локального пользователя (JIT) и привязывает к нему
Accountс DN из каталога. - Администратор открывает 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, где он шифруется.