Narvelium Платформа
ПорталNarvelium Starter
Интеграции

Подключение корпоративных систем без правок под конкретного заказчика

Все значения ниже задаются в настройках конкретной установки. В репозиторий не должны попадать реальные пароли, ключи вебхуков, закрытые ключи удостоверяющего центра, IP-адреса заказчика и абсолютные пути на сервере.

В рабочем контуре используйте LDAPS с проверкой сертификата. Обычный LDAP на порту 389 на стендах и в рабочем контуре запрещён настройками.

AD_ENABLED=true
AD_LDAPS_HOST=ad.company.internal
AD_LDAPS_PORT=636
AD_BASE_DN=DC=company,DC=internal
AD_BIND_DN=CN=Narvelium LDAP,CN=Users,DC=company,DC=internal
AD_BIND_PASSWORD=<secret storage>
AD_TLS_VALIDATE=true
AD_CA_CERT_FILE=/app/certs/company-root-ca.pem
  • Учётную запись для подключения (Bind DN) берите из каталога, а не собирайте из логина.
  • Имя в AD_LDAPS_HOST должно совпадать с именем в сертификате (SAN).
  • Корневой сертификат подключается только для чтения в /app/certs.
  • Служебной учётной записи выдавайте минимальные права только на чтение.

2. Keycloak / OIDC проверка на стороне заказчика

Narvelium использует поток Authorization Code Flow с PKCE S256, защиту от повторного запроса (state/nonce), проверку издателя, получателя и ключей JWKS, а также связывание учётной записи в Keycloak с учётной записью в портале.

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://sso.company.internal/realms/narvelium
OIDC_CLIENT_ID=narvelium-portal
OIDC_CLIENT_SECRET=<secret storage, если confidential client>
OIDC_CLIENT_AUTH_MODE=client_secret_post
OIDC_REDIRECT_URI=https://portal.company.ru/lms/api/auth/oidc/callback
OIDC_SCOPES=openid profile email
OIDC_REQUIRE_EMAIL_VERIFIED=true
OIDC_AUTO_PROVISION=false
SSL_CERT_FILE=/app/certs/company-ca-bundle.pem

Если Keycloak связан с AD через федерацию, проверяйте отдельно вход по LDAP и вход по OIDC. Не отключайте проверку TLS ради собственного удостоверяющего центра: добавьте его сертификат в доверенный набор.

3. Bitrix24 только чтение данных

Адрес вебхука хранится только в защищённых настройках. Для чтения данных сначала проверьте минимальные права и первую выгрузку, затем отдельно передачу событий и повторную доставку.

BITRIX24_WEBHOOK_URL=https://company.bitrix24.ru/rest/<user-id>/<secret-token>/
  • Не публикуйте адрес вебхука в репозитории, документации или задачах.
  • Не выдавайте права на CRM, Диск и другие разделы, если соединитель их не использует.
  • Первая выгрузка данных и передача событий проверяются отдельно.
  • При смене адреса вебхука старый ключ должен быть отозван.

4. 1С / OData требуется лицензированная 1С

Важно: бесплатная «Версия для обучения программированию» не поддерживает клиент-серверный режим, поэтому она не подходит как основа клиент-серверного стенда OData для Narvelium. Для бесплатного стенда разработки и тестирования используйте платформу 8.3.23+ с developer/community license. Для рабочего контура — 1С с коммерческой лицензией.
ONEC_ENABLED=true
ONEC_ODATA_URL=https://onec.company.internal/onec/odata/standard.odata
ONEC_USERNAME=<integration user>
ONEC_PASSWORD=<secret storage>
ONEC_VERIFY_TLS=true
ONEC_CA_CERT_FILE=/app/certs/company-root-ca.pem
ONEC_ALLOWED_ENTITIES=Catalog_Employees,Catalog_Departments
ONEC_ALLOW_INSECURE_HTTP=false

Соединитель работает только на чтение: доступные сущности перечисляются в списке разрешённых. Не используйте произвольную запись через OData до отдельного согласования условий.

Как подготовить стенд 1С к проверке

  1. Для бесплатного стенда разработки и тестирования обновите платформу до 8.3.23+ и активируйте developer/community license.
  2. Если версия платформы ниже 8.3.23, для клиент-серверного режима нужна коммерческая или тестовая лицензия, имеющаяся у вас на законных основаниях.
  3. После лицензирования отдельно проверьте веб-сеанс, описание сущностей OData, чтение разрешённого ресурса и цепочку сертификатов TLS.
  4. Не считайте ответ HTTP 404 доказательством именно лицензионной проблемы: сначала проверьте лицензию, публикацию .vrd, обработчик веб-сервера и адрес.

5. SMTP и одноразовые коды включается явной настройкой

EMAIL_AUTH_ENABLED=true
SMTP_HOST=smtp.company.ru
SMTP_PORT=587
SMTP_USER=<account>
SMTP_PASSWORD=<secret storage>
SMTP_FROM=noreply@company.ru
SMTP_STARTTLS=true
SMTP_VALIDATE_CERTS=true

Проверяйте доставку из того же контейнера, в котором работает приложение. На стендах и в рабочем контуре проверку сертификатов отключать нельзя.

6. Минимальная приёмка

ИнтеграцияЧто считать подтверждением
ADПодключение по LDAPS, поиск пользователя, верные подразделение и должность, отключённые учётные записи не допускаются.
OIDCЧтение настроек издателя и ключей JWKS, вход с PKCE, связывание учётной записи, отклонение повторного запроса и неверного state/nonce.
Bitrix24Чтение профиля, первая выгрузка, передача событий, проверка выданных прав, смена ключа.
1СВеб-сеанс с действующей лицензией, описание сущностей OData, чтение разрешённой сущности, проверка TLS, отказ для неразрешённой сущности.
SMTPДоставка одноразового кода, срок жизни и ограничение числа попыток, отказ для неверного кода, проверка TLS.

7. Типовые проблемы

Разбор реальных проблем и их решений хранится в основном репозитории: docs/INTEGRATION_ISSUES.md. Файл не содержит частных адресов, секретов и путей конкретных заказчиков.

Если средство защиты сайта (WAF/ModSecurity) блокирует страницу из-за технического слова, не подменяйте термин. Исправляйте конкретное ложное срабатывание правила или делайте узкое исключение для проверенного статического файла.