Feature/multi realm

[anishapant21]

Summary

Adds multi-realm architecture to the LDAP Gateway. A single gateway instance can now serve multiple directory backends, each with its own baseDN and authentication chain, while remaining fully backward compatible with existing single-realm deployments.

What Changed

Core Engine - LdapEngine now supports multiple realms, each with independent directory and auth providers. LDAP operations are routed by baseDN. Binds find the user across realms (first match wins) and authenticate against that realm. Searches query all matching realms in parallel and merge results with DN deduplication.

Per-User Auth Override - Users can override their realm default auth chain via an auth_backends database column. Backend names are resolved case-insensitively through a three-level registry (realm providers, realm-scoped key, global fallback). Unknown backends fail loudly.

Provider Options Passthrough - All backends (SQL, MongoDB, Proxmox, LDAP, Notification) now accept constructor options with env var fallback, enabling per-realm configuration without environment variable conflicts.

Configuration - New REALM_CONFIG env var points to a realms.json file (or inline JSON). Includes validation and structured error messages. When not set, legacy env vars work exactly as before.

Server Wiring - serverMain.js builds realm objects from config, instantiates per-realm providers, and populates the auth provider registry.

Backward Compatibility

When REALM_CONFIG is not set, the gateway behaves identically to before. Legacy env vars (AUTH_BACKENDS, DIRECTORY_BACKEND, LDAP_BASE_DN) are auto-wrapped into a single realm named "default". No client or configuration changes required for existing deployments.

Testing

• 931 lines of new unit tests for multi-realm routing, authentication, search, per-user override, and backward compatibility
• 193 lines of new unit tests for realm config loading and validation

Files Changed

• npm/src/LdapEngine.js - Multi-realm engine with baseDN routing
• server/serverMain.js - Realm instantiation and registry building
• server/config/configurationLoader.js - REALM_CONFIG loading and validation
• server/backends/*.js - Options passthrough for all providers
• docker/sql/init.sql - auth_backends column
• docs/MULTI-REALM-ARCHITECTURE.md - Feature documentation
• server/realms.example.json - Example configuration

[Copilot]

Pull request overview

Adds multi-realm support to the LDAP gateway so a single server can route binds/searches across multiple realm configurations (baseDN + directory backend + auth chain), with provider options override support for per-realm configuration.

Changes:

• Introduces multi-realm routing in @ldap-gateway/core (LdapEngine) for bind/search/RootDSE plus per-user auth-chain override support.
• Updates server configuration loading and provider instantiation to accept per-realm options (and adds realm config examples/tests).
• Refactors SQL backend Sequelize option building into a shared utility and updates backends/examples/tests for options-based configuration.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
server/utils/sqlUtils.js	New shared Sequelize options helper used by SQL providers.
server/test/unit/configurationLoader.realms.test.js	Unit tests for REALM_CONFIG loading/validation.
server/test/integration/auth/sqlite.auth.test.js	Adjusts auth integration test to satisfy multi-realm bind flow (directory stub + client cleanup).
server/test/integration/auth/postgres.auth.test.js	Uses directory stub to satisfy multi-realm bind flow.
server/test/integration/auth/mysql.auth.test.js	Uses directory stub to satisfy multi-realm bind flow.
server/services/notificationService.js	Allows overriding notification URL (used by notification auth backend options).
server/serverMain.js	Builds engine options for legacy vs multi-realm mode; constructs realms and auth provider registry.
server/realms.example.json	Example multi-realm configuration file.
server/providers.js	ProviderFactory now passes options into backend constructors.
server/config/configurationLoader.js	Loads/validates REALM_CONFIG (inline JSON or file path).
server/backends/template.js	Updates backend template to use options with env fallback.
server/backends/sql.directory.js	SQL directory provider now accepts options (sqlUri/queries/baseDn) and uses shared Sequelize options helper.
server/backends/sql.auth.js	SQL auth provider now accepts options (sqlUri/query) and uses shared Sequelize options helper.
server/backends/proxmox.directory.js	Proxmox directory provider now accepts options (paths/baseDn) and uses options-based DN building.
server/backends/proxmox.auth.js	Proxmox auth provider now accepts options (shadow cfg + optional directoryProvider).
server/backends/notification.auth.js	Notification auth provider now accepts options (notificationUrl) and passes it through.
server/backends/mongodb.directory.js	Mongo directory provider now accepts options (uri/db/baseDn).
server/backends/mongodb.auth.js	Mongo auth provider now accepts options (uri/db).
server/backends/ldap.auth.js	LDAP auth backend now supports options override for bind/auth base settings.
server/backends/custom-directory.example.js	Example directory backend updated to options + env fallback.
server/backends/custom-auth.example.js	Example auth backend updated to options + env fallback.
npm/test/unit/LdapEngine.realms.test.js	New unit tests covering multi-realm behavior, RootDSE namingContexts, and per-user auth override.
npm/test/fixtures/testData.js	Adds fixture user with auth_backends field for override tests.
npm/test/fixtures/mockProviders.js	Mock providers updated to call super(options).
npm/src/LdapEngine.js	Core multi-realm bind/search/RootDSE support and per-user auth override resolution.
npm/src/DirectoryProvider.js	Base class now stores constructor options.
npm/src/AuthProvider.js	Base class now stores constructor options.
nfpm/scripts/postinstall.sh	Fixes postinstall conditional syntax.
docker/sql/init.sql	Adds auth_backends column, fixes FK, and updates seeded passwords to bcrypt hashes.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

[runleveldev]

LGTM