Подключение корпоративных систем
Пошаговые инструкции по каждой интеграции: Active Directory / LDAP, Keycloak (SSO), Bitrix24, 1С по OData, SMTP. Всё написано по реальному опыту развёртывания демо-контура narvelium.ru — включая места, где мы спотыкались.
Все пароли и токены задаются только переменными окружения на сервере — они не вводятся в браузер и не хранятся в базе портала. В админке профиль интеграции хранит только адрес системы и имя переменной, в которой лежит секрет.
1. Active Directory / LDAP — источник сотрудников
Заведите в домене учётку для чтения каталога
Обычный пользователь с правами на чтение. Платформе нужны атрибуты: sAMAccountName, displayName, mail, department, title, memberOf. Ничего выдавать администратором не нужно.
Откройте LDAPS (порт 636)
Незашифрованный LDAP:389 платформа принципиально не использует. Если контроллер домена живёт в контейнере, просто пробросьте 636 наружу и откройте его в файрволе для тех подсетей, откуда будет ходить backend.
Пропишите переменные окружения
AD_LDAPS_HOST=ad.example.local
AD_LDAPS_PORT=636
AD_BIND_DN=CN=svc_narvelium_ldap,CN=Users,DC=example,DC=local
AD_BIND_PASSWORD=<пароль учётки>
AD_BASE_DN=DC=example,DC=local
AD_USER_GROUP=Нарвелиум Пользователи
AD_TLS_REQUIRE_CERT=true
AD_CA_CERT_FILE=/app/certs/ad-root-ca.pem
CN=Narvelium LDAP,CN=Users,.... Смотрите его через samba-tool user show или ADUC, а не выдумывайте по логину — иначе получите Invalid credentials при верном пароле и потратите час на поиск.Положите корневой сертификат домена
Сертификат контроллера подписан внутренним CA вашей сети, который платформа по умолчанию не знает. Выпишите корневой сертификат и смонтируйте его в контейнер backend (путь задаётся в AD_CA_CERT_FILE).
Перезапустите backend и запустите синхронизацию
Сотрудники появятся в разделе «Сотрудники»: ФИО, почта, отдел, должность. Дальше синхронизация идёт инкрементально — новые и уволенные подтягиваются автоматически.
extra_hosts) и ходите по имени.2. Keycloak — SSO через OIDC
Создайте realm и клиент
Отдельный realm под продукт. Клиент — confidential, redirect URI /api/auth/oidc/callback вашего домена. PKCE (S256) включите обязательно — платформа шлёт code_challenge всегда, и Keycloak отклонит запрос без него.
Настройте федерацию с доменом
User Storage Provider → LDAP: адрес ldaps://…:636, bind от учётки из шага 1, usersDn — корень домена, scope — Subtree, editMode — READ_ONLY. После настройки запустите синхронизацию пользователей.
Добавьте сертификат SSO в доверенные
Если Keycloak использует внутренний CA, корневой сертификат нужно добавить в доверенные и на стороне платформы (для проверки discovery-эндпоинта), и в сам Keycloak (для LDAP-соединения — полная цепочка, не только корень).
Включите OIDC на платформе
OIDC_ISSUER_URL=https://sso.example.com:18445/realms/narvelium
OIDC_CLIENT_ID=narvelium-portal
OIDC_CLIENT_SECRET=<секрет клиента>
На странице входа появится кнопка корпоративного входа. Первый вход доменным пользователем создаёт локальную учётку автоматически — кого пускать, контролируется списком разрешённых почтовых доменов.
3. Bitrix24 — задачи и пользователи
Создайте входящий вебхук
Битрикс24 → Разработчикам → Другое → Входящий вебхук. Права: Задачи, Пользователи, Рабочие группы. CRM, Диск и Телефонию не выдавайте — адаптер их всё равно не использует, а лишние права — лишний риск.
Проверьте вебхук руками
Откройте в браузере https://portal.bitrix24.ru/rest/1/ТОКЕН/profile.json. Если видите JSON со своим профилем — всё живое. Это самый быстрый способ понять, что проблема в вебхуке, а не в платформе.
Пропишите URL в окружении
# необязательно, для обратных событий:
BITRIX24_OUTGOING_TOKEN=<application_token>
CENTER_WEBHOOK_SECRET=<секрет обратных вызовов>
CENTER_BITRIX_WRITE_ENABLED=false
Запустите синхронизацию
Админка → Интеграции → Bitrix24 → «Проверить/синхронизировать». Сначала подтянутся пользователи — они сопоставляются с порталом по корпоративной почте, затем задачи.
События задач (по желанию)
Чтобы задачи обновлялись в реальном времени, в Б24 зарегистрируйте исходящие вебхуки OnTaskAdd / OnTaskUpdate / OnTaskDelete на адрес https://ваш-домен/api/center/integrations/bitrix/webhook?secret=СЕКРЕТ. Секрет живёт в переменной CENTER_WEBHOOK_SECRET на сервере.
4. 1С по OData
Поднимите сервер 1С и СУБД
Тут важно не сэкономить время на выборе СУБД: обычный постгрес не подойдёт — в нём нет типов mvarchar и функций fasttruncate/fulleq, и платформа откажется создавать базу. Нужна 1С-сборка Постгрес (в контейнерных образах расширения уже включены), плюс расширения надо явно включить в базе: create extension mchar; fasttrun; fulleq; — до первого подключения платформы.
Создайте ИБ в кластере
--name=onec_demo --dbms=PostgreSQL --db-server=<IP> \
--db-name=onec_demo --db-user=postgres --db-pwd=<пароль> --locale=ru_RU
Опубликуйте OData
Понадобится Apache с модулем wsap24 из ws-дистрибутива платформы (в server-поставке его нет — не удивляйтесь). Каталог публикации с default.vrd: base=/onec_demo, ib="Srvr="tcp://srv-1c";Ref="onec_demo"", блок standardOdata enable="true". На каталог публикации — SetHandler 1cws-process.
Заведите профиль в нарвелиуме
Админка → Интеграции → 1С: адрес публикации, HTTP Basic от технической учётки, направление read_only, ресурсы OData — только те, что реально нужны дашбордам. Учётные данные: ONEC_USERNAME / ONEC_PASSWORD на сервере.
5. SMTP-почта (OTP, уведомления)
Поднимите локальный релей
Postfix на хосте с маршрутом на корпоративный или внешний SMTP. Аутентификация SASL, и используйте «пароль приложения», а не основной пароль ящика.
Укажите платформе
SMTP_PORT=25
SMTP_FROM=noreply@ваш-домен
6. Типовые ошибки при подключении
Шпаргалка по тем местам, где чаще всего спотыкаются:
| Симптом | Проверить |
|---|---|
| LDAP: Invalid credentials | DN учётки соответствует записи в AD (CN строится по ФИО, не по логину) |
| LDAP: TLS hostname mismatch | AD_LDAPS_HOST совпадает с SAN сертификата контроллера |
| SSO: пользователь не найден | Федерация LDAP настроена с searchScope=Subtree |
| Б24: 401 на REST | Токен вебхука активен, формат rest/1/<токен>/ |
| 1С: публикация недоступна | Лицензия установлена на сервере, расширения СУБД включены в базе |
| OTP-письмо не пришло | Релей настроен, порт доступен из контейнера |
| Backend не видит SSO-сертификат | Корневой CA добавлен в доверенные и backend, и самого Keycloak |
| Порты недоступны между хостами | В файрволе открыты и LAN-подсеть, и docker-подсеть целевого хоста |
Конфигурационные файлы и compose-профили нашего стенда лежат в репозитории github.com/Haper-Forge/fb-training-lms, каталог deploy/ — можно брать как рабочий пример. Если что-то не подключается — пишите на info@narvelium.ru, поможем пройти по этим граблям вместе.