Feature/ldap auth

.gitignore

@@ -8,3 +8,5 @@ test/node_modules
 */node_modules
 docker/dev/dnsrouter-config.json.tmp
 docker/dev/resolv.conf
+backend/package-lock.json
+package-lock.json

README.md

@@ -35,6 +35,47 @@ so that the barrier for entry here is low.
 - Access Lists and basic HTTP Authentication for your hosts
 - Advanced Nginx configuration available for super users
 - User management, permissions and audit log
+- **LDAP / Active Directory authentication** with JIT user provisioning and group-based access control
+
+## LDAP / Active Directory Authentication
+
+NPM supports LDAP authentication, allowing your team to log in with their existing directory credentials.
+
+**Key features:**
+- Works with **Active Directory**, **OpenLDAP**, **FreeIPA**, and compatible servers
+- **Group-based access control** — map LDAP groups to NPM admin / user roles
+- **Just-in-time provisioning** — NPM accounts are created automatically on first login
+- **Environment variable configuration** — ideal for Docker and Kubernetes deployments
+- Supports **LDAPS** and **STARTTLS** for encrypted connections
+- **Sync Now** button to force-refresh all LDAP user permissions
+
+**Quick start (Docker):**
+
+```yaml
+services:
+  app:
+    image: 'docker.io/jc21/nginx-proxy-manager:latest'
+    environment:
+      LDAP_ENABLED: "true"
+      LDAP_SERVER_URL: "ldap://your-ldap-server:389"
+      LDAP_BIND_DN: "cn=service,dc=example,dc=com"
+      LDAP_BIND_PASSWORD: "service-password"
+      LDAP_SEARCH_BASE: "dc=example,dc=com"
+      LDAP_USER_ATTR: "uid"                     # use sAMAccountName for Active Directory
+      LDAP_ADMIN_GROUP: "cn=npm-admins,ou=Groups,dc=example,dc=com"
+      LDAP_USER_GROUP: "cn=npm-users,ou=Groups,dc=example,dc=com"
+```
+
+📖 **Full documentation:** [docs/ldap-authentication.md](docs/ldap-authentication.md)
+
+Covers:
+- [Active Directory setup guide](docs/ldap-authentication.md#active-directory-setup)
+- [OpenLDAP setup guide](docs/ldap-authentication.md#openldap-setup)
+- [FreeIPA setup guide](docs/ldap-authentication.md#freeipa-setup)
+- [Group-based access control](docs/ldap-authentication.md#group-based-access-control)
+- [TLS / STARTTLS configuration](docs/ldap-authentication.md#tls-and-starttls)
+- [Troubleshooting](docs/ldap-authentication.md#troubleshooting)
+- [Environment variable reference](docs/ldap-authentication.md#environment-variable-reference)
 
 ::: warning
 `armv7` is no longer supported in version 2.14+. This is due to Nodejs dropping support for armhf. Please

backend/__mocks__/bcrypt.js

@@ -0,0 +1,17 @@
+/**
+ * Stub for bcrypt — replaces the native addon-based package when
+ * node-gyp-build or native bindings are unavailable in the test env.
+ *
+ * Tests that exercise real password hashing should use the real module;
+ * for all other tests the models are fully mocked anyway.
+ */
+const FAKE_HASH = "$2b$10$TESTHASHfakevalueusedinstubonlyXXXXXXXXXXXXXXXXXX";
+
+export default {
+	hash:        async (_data, _saltOrRounds) => FAKE_HASH,
+	hashSync:    (_data, _saltOrRounds) => FAKE_HASH,
+	compare:     async (_data, _hash) => true,
+	compareSync: (_data, _hash) => true,
+	genSalt:     async (_rounds) => "$2b$10$TESTSALTfakevalueXXXXXXXXXX",
+	genSaltSync: (_rounds) => "$2b$10$TESTSALTfakevalueXXXXXXXXXX",
+};

backend/__mocks__/config.js

@@ -0,0 +1,42 @@
+/**
+ * Stub for backend/lib/config.js — used in Jest ESM test environment.
+ * Provides no-op implementations of configuration helpers so that models
+ * can be imported without triggering real file-system or key-generation
+ * side-effects.
+ */
+
+export const configure              = () => {};
+export const isSqlite               = () => false;
+export const isMysql                = () => false;
+export const isPostgres             = () => false;
+export const isCI                   = () => false;
+export const isDebugMode            = () => false;
+export const configGet              = (_key) => ({});
+export const configHas              = (_key) => false;
+export const getKeys                = () => ({ private: "", public: "" });
+export const getPrivateKey          = () => "";
+export const getPublicKey           = () => "";
+export const generateKeys           = async () => {};
+export const getConfig              = () => ({});
+export const getSetting             = () => null;
+export const useLetsencryptStaging  = () => false;
+export const useLetsencryptServer   = () => "https://acme-v02.api.letsencrypt.org/directory";
+
+export default {
+	configure,
+	isSqlite,
+	isMysql,
+	isPostgres,
+	isCI,
+	isDebugMode,
+	configGet,
+	configHas,
+	getKeys,
+	getPrivateKey,
+	getPublicKey,
+	generateKeys,
+	getConfig,
+	getSetting,
+	useLetsencryptStaging,
+	useLetsencryptServer,
+};

backend/__mocks__/db.js

@@ -0,0 +1,7 @@
+/**
+ * Stub for backend/db.js — used in Jest ESM test environment
+ * to avoid loading knex and its transitive dependencies.
+ */
+
+const db = () => null;
+export default db;

backend/__mocks__/lodash.js

@@ -0,0 +1,74 @@
+/**
+ * ESM stub for lodash — used in Jest ESM test environment.
+ * The real lodash is CJS and may not resolve correctly through Jest's ESM resolver.
+ */
+
+const noop = () => {};
+
+const _ = {
+	isArray:    Array.isArray,
+	isString:   (v) => typeof v === "string",
+	isObject:   (v) => v !== null && typeof v === "object",
+	isFunction: (v) => typeof v === "function",
+	isNumber:   (v) => typeof v === "number",
+	isUndefined:(v) => v === undefined,
+	isNull:     (v) => v === null,
+	isNil:      (v) => v == null,
+	isEmpty:    (v) => !v || (Array.isArray(v) ? v.length === 0 : typeof v === "object" ? Object.keys(v).length === 0 : false),
+	merge:      (target, ...sources) => Object.assign(target ?? {}, ...sources),
+	omit:       (obj, keys) => {
+		const result = { ...obj };
+		const ks = Array.isArray(keys) ? keys : [keys];
+		for (const k of ks) delete result[k];
+		return result;
+	},
+	pick:       (obj, keys) => {
+		const result = {};
+		const ks = Array.isArray(keys) ? keys : [keys];
+		for (const k of ks) if (k in obj) result[k] = obj[k];
+		return result;
+	},
+	clone:      (v) => Array.isArray(v) ? [...v] : typeof v === "object" && v ? { ...v } : v,
+	cloneDeep:  (v) => JSON.parse(JSON.stringify(v)),
+	assign:     Object.assign,
+	forEach:    (collection, fn) => {
+		if (Array.isArray(collection)) { collection.forEach(fn); }
+		else if (collection && typeof collection === "object") { Object.entries(collection).forEach(([k, v]) => { fn(v, k); }); }
+	},
+	map:        (collection, fn) => {
+		if (Array.isArray(collection)) return collection.map(fn);
+		if (collection && typeof collection === "object") return Object.entries(collection).map(([k, v]) => fn(v, k));
+		return [];
+	},
+	filter:     (arr, fn) => Array.isArray(arr) ? arr.filter(fn) : [],
+	find:       (arr, fn) => Array.isArray(arr) ? arr.find(fn) : undefined,
+	reduce:     (arr, fn, init) => Array.isArray(arr) ? arr.reduce(fn, init) : init,
+	some:       (arr, fn) => Array.isArray(arr) ? arr.some(fn) : false,
+	every:      (arr, fn) => Array.isArray(arr) ? arr.every(fn) : true,
+	keys:       Object.keys,
+	values:     Object.values,
+	entries:    Object.entries,
+	get:        (obj, path, def) => {
+		if (!obj) return def;
+		const parts = typeof path === "string" ? path.split(".") : path;
+		let cur = obj;
+		for (const p of parts) { if (cur == null) return def; cur = cur[p]; }
+		return cur === undefined ? def : cur;
+	},
+	set:        (obj, path, val) => {
+		const parts = typeof path === "string" ? path.split(".") : path;
+		let cur = obj;
+		for (let i = 0; i < parts.length - 1; i++) { if (!cur[parts[i]]) cur[parts[i]] = {}; cur = cur[parts[i]]; }
+		cur[parts[parts.length - 1]] = val;
+		return obj;
+	},
+	has:        (obj, key) => Object.hasOwn(obj ?? {}, key),
+	defaults:   (obj, ...sources) => { for (const src of sources) for (const [k, v] of Object.entries(src)) if (obj[k] === undefined) obj[k] = v; return obj; },
+	flatten:    (arr) => arr.flat(),
+	flatMap:    (arr, fn) => arr.flatMap(fn),
+	uniq:       (arr) => [...new Set(arr)],
+	sortBy:     (arr, fn) => [...arr].sort((a, b) => { const va = typeof fn === "function" ? fn(a) : a[fn]; const vb = typeof fn === "function" ? fn(b) : b[fn]; return va < vb ? -1 : va > vb ? 1 : 0; }),
+	noop,
+};
+
+export default _;

backend/__mocks__/moment.js

@@ -0,0 +1,32 @@
+/**
+ * Minimal stub for moment.js.
+ * Provides the API surface used by lib/helpers.js (parseDatePeriod).
+ */
+
+const momentObj = {
+	add:      function() { return this; },
+	subtract: function() { return this; },
+	toDate:   () => new Date(),
+	toISOString: () => new Date().toISOString(),
+	isValid:  () => true,
+	valueOf:  () => Date.now(),
+};
+
+function moment(input) {
+	return {
+		...momentObj,
+		clone: () => moment(input),
+	};
+}
+
+moment.duration = (_value, _unit) => ({
+	asMilliseconds: () => 86400000,
+	toISOString:    () => "P1D",
+});
+
+moment.isMoment   = (obj) => obj && typeof obj.toDate === "function";
+moment.utc        = (input) => moment(input);
+moment.unix       = (ts) => moment(new Date(ts * 1000));
+moment.ISO_8601   = "ISO_8601";
+
+export default moment;

backend/__mocks__/node-rsa.js

@@ -0,0 +1,15 @@
+/**
+ * Minimal stub for node-rsa — used when the real package's dependencies
+ * (asn1, etc.) are not installed in the test environment.
+ */
+export default class NodeRSA {
+	// biome-ignore lint/complexity/noUselessConstructor: mock stub
+	constructor() {}
+	generateKeyPair() { return this; }
+	exportKey() { return "-----BEGIN RSA KEY-----\nMOCK\n-----END RSA KEY-----"; }
+	importKey() { return this; }
+	sign() { return Buffer.from("mock-signature"); }
+	verify() { return true; }
+	encrypt() { return Buffer.from("mock-encrypted"); }
+	decrypt() { return Buffer.from("mock-decrypted"); }
+}

backend/__mocks__/objection.js

@@ -0,0 +1,56 @@
+/**
+ * Minimal stub for the objection.js ORM — used only when the real package
+ * is not installed in the test environment.
+ *
+ * biome-ignore: `this` in static methods is intentional for query-builder chaining.
+ */
+
+// biome-ignore lint/complexity/noStaticOnlyClass: mock mirrors Objection.js Model API
+export class Model {
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static query() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static where() { return this; }
+	static first() { return Promise.resolve(null); }
+	static findById() { return Promise.resolve(null); }
+	static insertAndFetch() { return Promise.resolve({}); }
+	static patch() { return Promise.resolve(1); }
+	static patchAndFetchById() { return Promise.resolve({}); }
+	static insert() { return Promise.resolve({}); }
+	static delete() { return Promise.resolve(1); }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static count() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static andWhere() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static orWhere() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static allowGraph() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static withGraphFetched() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static groupBy() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static orderBy() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static whereIn() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static limit() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static offset() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static select() { return this; }
+	static knex(_db) { return null; }
+	static raw(sql, ...bindings) { return { sql, bindings, toKnexRaw: () => sql }; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static relatedQuery() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static for() { return this; }
+	// biome-ignore lint/complexity/noThisInStatic: intentional for chaining
+	static modify() { return this; }
+}
+
+// objection helper functions used in queries
+export const ref = (expr) => ({ expression: expr });
+export const raw = (sql, ...bindings) => ({ sql, bindings });
+export const fn = { now: () => new Date() };

backend/__mocks__/signale.js

@@ -0,0 +1,40 @@
+/**
+ * Manual stub for the `signale` logging library.
+ *
+ * Used via moduleNameMapper so it must NOT reference jest globals.
+ * Provides the Signale class and default logger methods as no-ops.
+ */
+
+const noop = () => {};
+
+const makeLogger = () => ({
+	debug:    noop,
+	info:     noop,
+	warn:     noop,
+	error:    noop,
+	log:      noop,
+	fatal:    noop,
+	trace:    noop,
+	start:    noop,
+	success:  noop,
+	await:    noop,
+	note:     noop,
+	pause:    noop,
+	complete: noop,
+	pending:  noop,
+	star:     noop,
+	watch:    noop,
+});
+
+class Signale {
+	constructor(_opts) {
+		Object.assign(this, makeLogger());
+	}
+}
+
+const defaultLogger = makeLogger();
+
+export default {
+	Signale,
+	...defaultLogger,
+};

backend/__mocks__/tarn.js

@@ -0,0 +1,14 @@
+/**
+ * Minimal stub for tarn (connection pool library, transitive dep of knex).
+ */
+export class Pool {
+	// biome-ignore lint/complexity/noUselessConstructor: mock stub accepts opts
+	constructor(_opts) {}
+	acquire() { return { promise: Promise.resolve({}) }; }
+	release() {}
+	destroy() { return Promise.resolve(); }
+	numUsed() { return 0; }
+	numFree() { return 0; }
+	numPendingAcquires() { return 0; }
+	numPendingCreates() { return 0; }
+}

backend/__tests__/README.md

@@ -0,0 +1,16 @@
+# Backend Unit Tests
+
+Tests use **Jest** with ESM support. Run from `backend/`:
+
+```bash
+NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPattern="__tests__/ldap"
+```
+
+| File | Module under test | Coverage |
+|------|-------------------|----------|
+| `ldap/ldap-client.test.js` | `lib/ldap-client.js` | Connection, bind, search, pool, TLS, error mapping |
+| `ldap/ldap-internal.test.js` | `internal/ldap.js` | testConnection, searchUser, authenticateUser, normalizeUser |
+| `ldap/ldap-sync.test.js` | `internal/ldap-sync.js` | JIT provisioning, group sync, account disable, syncAllUsers |
+| `ldap/ldap-env.test.js` | `lib/ldap-env.js` | Env var overrides, boolean parsing, rowToLdapClientConfig |
+| `ldap/objectguid.test.js` | `internal/ldap.js` | objectGUID parsing, LDAP filter encoding, UTF-8 regression |
+| `validator/api-validator.test.js` | `lib/validator/api.js` | Validation error formatting |