Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

fix(auth): support anonymous LDAP service binds (#7175)

Thomasc933e4ffa5ad
diff --git a/apps/docs/docs/advanced/single-sign-on/index.mdx b/apps/docs/docs/advanced/single-sign-on/index.mdx
index 7186575a3..85167f1c6 100644
--- a/apps/docs/docs/advanced/single-sign-on/index.mdx
+++ b/apps/docs/docs/advanced/single-sign-on/index.mdx
@@ -39,6 +39,8 @@ Roles are fetched from LDAP groups. Groups with the same name of Homarr will be
LDAP users whose distinguished names contain non-ASCII characters can sign in and have their groups resolved.
+If your directory allows anonymous searches, omit or leave empty both `AUTH_LDAP_BIND_DN` and `AUTH_LDAP_BIND_PASSWORD`. Users still sign in with their own LDAP passwords. For authenticated directory searches, set both bind variables together.
+
<details>
<summary>
Example Setup
@@ -47,7 +49,7 @@ LDAP users whose distinguished names contain non-ASCII characters can sign in an
In this setup we are using [lldap](https://github.com/lldap/lldap). Install your server using docker or [as a service](https://github.com/lldap/lldap/blob/main/example_configs/lldap.service).
- Minimal configuration requires 4 env variables, LDAP URI, base, user and password for querying data.
+ This lldap example uses four LDAP variables: the URI, base, service bind DN and service bind password.
There's more variables, but all have defaults corresponding to lldap defaults. These might need to be changed if you have different LDAP provider.
```
@@ -99,8 +101,8 @@ LDAP users whose distinguished names contain non-ASCII characters can sign in an
| --------------------------------------- | --------------------------------------------------------- | ------------------ |
| `AUTH_LDAP_URI` | URI of your LDAP server | --- |
| `AUTH_LDAP_BASE` | Base dn of your LDAP server | --- |
-| `AUTH_LDAP_BIND_DN` | User used for finding users and groups | --- |
-| `AUTH_LDAP_BIND_PASSWORD` | Password for bind user | --- |
+| `AUTH_LDAP_BIND_DN` | Optional service bind DN for finding users and groups | Empty (anonymous) |
+| `AUTH_LDAP_BIND_PASSWORD` | Optional password for the service bind DN | Empty (anonymous) |
| `AUTH_LDAP_USERNAME_ATTRIBUTE` | Attribute used for username | uid |
| `AUTH_LDAP_USER_MAIL_ATTRIBUTE` | Attribute used for mail field | mail |
| `AUTH_LDAP_GROUP_CLASS` | Class used for querying groups | groupOfUniqueNames |
diff --git a/packages/auth/env.ts b/packages/auth/env.ts
index 484db5531..ed6615bb5 100644
--- a/packages/auth/env.ts
+++ b/packages/auth/env.ts
@@ -55,8 +55,8 @@ export const env = createEnv({
...(authProviders.includes("ldap")
? {
AUTH_LDAP_URI: z.string().url(),
- AUTH_LDAP_BIND_DN: z.string(),
- AUTH_LDAP_BIND_PASSWORD: z.string(),
+ AUTH_LDAP_BIND_DN: z.string().default(""),
+ AUTH_LDAP_BIND_PASSWORD: z.string().default(""),
AUTH_LDAP_BASE: z.string(),
AUTH_LDAP_SEARCH_SCOPE: z.enum(["base", "one", "sub"]).default("base"),
AUTH_LDAP_USERNAME_ATTRIBUTE: z.string().default("uid"),
@@ -71,3 +71,7 @@ export const env = createEnv({
},
experimental__runtimeEnv: process.env,
});
+
+if (authProviders.includes("ldap") && Boolean(env.AUTH_LDAP_BIND_DN) !== Boolean(env.AUTH_LDAP_BIND_PASSWORD)) {
+ throw new Error("AUTH_LDAP_BIND_DN and AUTH_LDAP_BIND_PASSWORD must both be set or both be omitted.");
+}
diff --git a/packages/auth/providers/credentials/authorization/ldap-authorization.ts b/packages/auth/providers/credentials/authorization/ldap-authorization.ts
index 79a67d762..75ce78874 100644
--- a/packages/auth/providers/credentials/authorization/ldap-authorization.ts
+++ b/packages/auth/providers/credentials/authorization/ldap-authorization.ts
@@ -23,8 +23,8 @@ export const authorizeWithLdapCredentialsAsync = async (
const client = new LdapClient();
await client
.bindAsync({
- distinguishedName: env.AUTH_LDAP_BIND_DN,
- password: env.AUTH_LDAP_BIND_PASSWORD,
+ distinguishedName: env.AUTH_LDAP_BIND_DN ?? "",
+ password: env.AUTH_LDAP_BIND_PASSWORD ?? "",
})
.catch((error) => {
throw new CredentialsSignin("Failed to connect to LDAP server", { cause: error });
diff --git a/packages/auth/providers/test/ldap-env.spec.ts b/packages/auth/providers/test/ldap-env.spec.ts
new file mode 100644
index 000000000..6ae80c7e2
--- /dev/null
+++ b/packages/auth/providers/test/ldap-env.spec.ts
@@ -0,0 +1,35 @@
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+
+beforeEach(() => {
+ vi.resetModules();
+ vi.stubEnv("CI", undefined);
+ vi.stubEnv("SKIP_ENV_VALIDATION", undefined);
+ vi.stubEnv("NODE_ENV", "development");
+ vi.stubEnv("AUTH_PROVIDERS", "ldap");
+ vi.stubEnv("AUTH_LDAP_URI", "ldap://127.0.0.1:389");
+ vi.stubEnv("AUTH_LDAP_BASE", "dc=example,dc=com");
+ vi.stubEnv("AUTH_LDAP_BIND_DN", undefined);
+ vi.stubEnv("AUTH_LDAP_BIND_PASSWORD", undefined);
+});
+
+afterEach(() => vi.unstubAllEnvs());
+
+test.each([undefined, ""])(
+ "loads LDAP configuration with absent or empty service bind credentials: %s",
+ async (value) => {
+ vi.stubEnv("AUTH_LDAP_BIND_DN", value);
+ vi.stubEnv("AUTH_LDAP_BIND_PASSWORD", value);
+ const { env } = await import("@homarr/auth/env");
+
+ expect(env.AUTH_PROVIDERS).toEqual(["ldap"]);
+ },
+);
+
+test.each([
+ ["AUTH_LDAP_BIND_DN", "uid=service,dc=example,dc=com"],
+ ["AUTH_LDAP_BIND_PASSWORD", "fixture-service-password"],
+])("rejects an incomplete service bind when only %s is configured", async (name, value) => {
+ vi.stubEnv(name, value);
+
+ await expect(import("@homarr/auth/env")).rejects.toThrow(/AUTH_LDAP_BIND_DN.*AUTH_LDAP_BIND_PASSWORD/);
+});
diff --git a/packages/auth/providers/test/ldap-sign-in.spec.ts b/packages/auth/providers/test/ldap-sign-in.spec.ts
new file mode 100644
index 000000000..d5d42e822
--- /dev/null
+++ b/packages/auth/providers/test/ldap-sign-in.spec.ts
@@ -0,0 +1,115 @@
+import { Client, FilterParser, InvalidCredentialsError } from "ldapts";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+
+const userDn = "uid=alice,ou=people,dc=example,dc=com";
+const userPassword = "fixture-user-password";
+const directoryCredentials = new Map<string, string>();
+
+beforeEach(() => {
+ vi.resetModules();
+ vi.stubEnv("CI", undefined);
+ vi.stubEnv("SKIP_ENV_VALIDATION", undefined);
+ vi.stubEnv("NODE_ENV", "development");
+ vi.stubEnv("AUTH_PROVIDERS", "ldap");
+ vi.stubEnv("AUTH_LDAP_URI", "ldap://127.0.0.1:389");
+ vi.stubEnv("AUTH_LDAP_BASE", "dc=example,dc=com");
+ vi.stubEnv("AUTH_LDAP_BIND_DN", undefined);
+ vi.stubEnv("AUTH_LDAP_BIND_PASSWORD", undefined);
+ vi.stubEnv("AUTH_LDAP_SEARCH_SCOPE", "sub");
+ vi.stubEnv("AUTH_LDAP_USERNAME_ATTRIBUTE", "uid");
+ vi.stubEnv("AUTH_LDAP_USER_MAIL_ATTRIBUTE", "mail");
+ vi.stubEnv("AUTH_LDAP_GROUP_CLASS", "groupOfUniqueNames");
+ vi.stubEnv("AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE", "member");
+ vi.stubEnv("AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE", "dn");
+ vi.stubEnv("AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG", undefined);
+ vi.stubEnv("AUTH_LDAP_GROUP_FILTER_EXTRA_ARG", undefined);
+ directoryCredentials.clear();
+ directoryCredentials.set("", "");
+ directoryCredentials.set(userDn, userPassword);
+
+ const boundClients = new WeakSet<Client>();
+ vi.spyOn(Client.prototype, "bind").mockImplementation(async function (this: Client, dn, password) {
+ if (typeof dn !== "string" || !directoryCredentials.has(dn) || directoryCredentials.get(dn) !== password) {
+ throw new InvalidCredentialsError();
+ }
+ boundClients.add(this);
+ });
+ vi.spyOn(Client.prototype, "search").mockImplementation(async function (this: Client, _base, options = {}) {
+ if (!boundClients.has(this)) throw new InvalidCredentialsError();
+ const filter = FilterParser.parseString(String(options.filter));
+ const entries: ({ dn: string } & Record<string, string>)[] = [
+ { dn: userDn, uid: "alice", mail: "[email protected]", objectClass: "person" },
+ {
+ dn: "cn=homarr-users,ou=groups,dc=example,dc=com",
+ cn: "homarr-users",
+ objectClass: "groupOfUniqueNames",
+ member: userDn,
+ },
+ ];
+ return { searchEntries: entries.filter((entry) => filter.matches(entry)), searchReferences: [] };
+ });
+ vi.spyOn(Client.prototype, "unbind").mockResolvedValue(undefined);
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+});
+
+test("signs in through anonymous directory lookup when environment validation is skipped", async () => {
+ vi.stubEnv("SKIP_ENV_VALIDATION", "true");
+ const { createDb } = await import("@homarr/db/test");
+ const { createLdapConfiguration } = await import("../credentials/credentials-provider");
+ const provider = createLdapConfiguration(createDb());
+
+ const user = await provider.authorize({ name: "alice", password: userPassword });
+
+ expect(user).toMatchObject({ name: "alice", groups: ["homarr-users"] });
+});
+
+test.each([undefined, ""])(
+ "signs in through anonymous directory lookup with absent or empty credentials: %s",
+ async (value) => {
+ vi.stubEnv("AUTH_LDAP_BIND_DN", value);
+ vi.stubEnv("AUTH_LDAP_BIND_PASSWORD", value);
+ const { createDb } = await import("@homarr/db/test");
+ const { createLdapConfiguration } = await import("../credentials/credentials-provider");
+ const provider = createLdapConfiguration(createDb());
+
+ const user = await provider.authorize({ name: "alice", password: userPassword });
+
+ expect(user).toMatchObject({ name: "alice", groups: ["homarr-users"] });
+ },
+);
+
+test("still signs in when directory searches require configured service credentials", async () => {
+ const serviceDn = "uid=service,ou=people,dc=example,dc=com";
+ const servicePassword = "fixture-service-password";
+ vi.stubEnv("AUTH_LDAP_BIND_DN", serviceDn);
+ vi.stubEnv("AUTH_LDAP_BIND_PASSWORD", servicePassword);
+ directoryCredentials.delete("");
+ directoryCredentials.set(serviceDn, servicePassword);
+ const { createDb } = await import("@homarr/db/test");
+ const { createLdapConfiguration } = await import("../credentials/credentials-provider");
+ const provider = createLdapConfiguration(createDb());
+
+ const user = await provider.authorize({ name: "alice", password: userPassword });
+
+ expect(user).toMatchObject({ name: "alice", groups: ["homarr-users"] });
+});
+
+test("rejects an incorrect user password after anonymous directory lookup", async () => {
+ const { createDb } = await import("@homarr/db/test");
+ const { createLdapConfiguration } = await import("../credentials/credentials-provider");
+ const provider = createLdapConfiguration(createDb());
+
+ await expect(provider.authorize({ name: "alice", password: "incorrect" })).resolves.toBeNull();
+});
+
+test("rejects an empty user password when the directory allows anonymous lookup", async () => {
+ const { createDb } = await import("@homarr/db/test");
+ const { createLdapConfiguration } = await import("../credentials/credentials-provider");
+ const provider = createLdapConfiguration(createDb());
+
+ await expect(provider.authorize({ name: "alice", password: "" })).rejects.toThrow();
+});