feat: add local group support for OIDC users (#5952)

This commit is contained in:
Louis Bailleau authored and GitHub committed 2026-06-16 13:45:44 +02:00
1 parent 4692e7ce3a
commit fb18b975b2
15 files changed
+540 -191

No files matched your search

+1
View File
@@ -37,6 +37,7 @@ export const env = createEnv({
AUTH_OIDC_AUTO_LOGIN: createBooleanSchema(false),
AUTH_OIDC_SCOPE_OVERWRITE: z.string().min(1).default("openid email profile groups"),
AUTH_OIDC_GROUPS_ATTRIBUTE: z.string().default("groups"), // Is used in the signIn event to assign the correct groups, key is from object of decoded id_token
AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT: createBooleanSchema(false), // When enabled, group memberships of oidc users are managed locally instead of synced from the groups claim
AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE: z.string().optional(),
AUTH_OIDC_FORCE_USERINFO: createBooleanSchema(false),
AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING: createBooleanSchema(false),
+6 -1
View File
@@ -31,7 +31,12 @@ export const createSignInEventHandler = (db: Database): Exclude<NextAuthConfig["
const groupsKey = env.AUTH_OIDC_GROUPS_ATTRIBUTE;
// Groups from oidc provider are provided from the profile, it's not typed.
if (profile && groupsKey in profile && Array.isArray(profile[groupsKey])) {
if (
!env.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT &&
profile &&
groupsKey in profile &&
Array.isArray(profile[groupsKey])
) {
logger.debug(`Using profile groups (${groupsKey}): ${JSON.stringify(profile[groupsKey])}`);
await synchronizeGroupsWithExternalForUserAsync(db, user.id, profile[groupsKey] as string[]);
}
+48
View File
@@ -1,9 +1,57 @@
import type { SupportedAuthProvider } from "@homarr/definitions";
import { supportedAuthProviders } from "@homarr/definitions";
import { env } from "../env";
export type GroupMemberManagementType = "local" | "mixed" | "external";
export const isProviderEnabled = (provider: SupportedAuthProvider) => {
// The question mark is placed there because isProviderEnabled is called during static build of about page
// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
return env.AUTH_PROVIDERS?.includes(provider);
};
/**
* Whether a single provider's group memberships are managed locally (manually via UI/API).
* True for credentials users, and for oidc users when AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT is enabled.
*/
export const isGroupMembershipManagedLocally = (provider: SupportedAuthProvider): boolean => {
switch (provider) {
case "credentials":
return true;
case "oidc":
return env.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT;
default:
// ldap + any provider added later: externally managed (synced, not editable
// here) until explicitly given a case above. New providers safe-by-default.
return false;
}
};
export const getEnabledProviders = (): SupportedAuthProvider[] => supportedAuthProviders.filter(isProviderEnabled);
/**
* The enabled providers whose group memberships can be managed locally.
*/
export const getLocallyManageableProviders = (): SupportedAuthProvider[] =>
getEnabledProviders().filter(isGroupMembershipManagedLocally);
/**
* Classifies group-member management across all enabled providers:
* - "local": every enabled provider is managed locally (no member is synced externally)
* - "external": no enabled provider is managed locally (every member is synced externally)
* - "mixed": some are managed locally, some externally (only a subset of members is editable here)
*/
export const getGroupMemberManagementType = (): GroupMemberManagementType => {
const enabled = getEnabledProviders();
const manageable = enabled.filter(isGroupMembershipManagedLocally);
if (manageable.length === enabled.length) return "local";
if (manageable.length === 0) return "external";
return "mixed";
};
/**
* Whether group memberships can be managed locally for at least one enabled provider.
*/
export const canManageGroupMembersLocally = (): boolean => getLocallyManageableProviders().length > 0;
@@ -0,0 +1,105 @@
import { beforeEach, describe, expect, test, vi } from "vitest";
import type { SupportedAuthProvider } from "@homarr/definitions";
import * as env from "../../env";
import {
canManageGroupMembersLocally,
getGroupMemberManagementType,
getLocallyManageableProviders,
isGroupMembershipManagedLocally,
} from "../check-provider";
const mockEnv = (providers: SupportedAuthProvider[], oidcLocalManagement = false) => {
vi.spyOn(env, "env", "get").mockReturnValue({
AUTH_PROVIDERS: providers,
AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT: oidcLocalManagement,
} as never);
};
beforeEach(() => {
vi.restoreAllMocks();
});
describe("isGroupMembershipManagedLocally", () => {
test("credentials is always managed locally", () => {
mockEnv(["credentials"]);
expect(isGroupMembershipManagedLocally("credentials")).toBe(true);
});
test("oidc follows AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT", () => {
mockEnv(["oidc"], true);
expect(isGroupMembershipManagedLocally("oidc")).toBe(true);
mockEnv(["oidc"], false);
expect(isGroupMembershipManagedLocally("oidc")).toBe(false);
});
test("ldap is never managed locally", () => {
mockEnv(["ldap"]);
expect(isGroupMembershipManagedLocally("ldap")).toBe(false);
});
});
describe("getGroupMemberManagementType", () => {
test("credentials only is local", () => {
mockEnv(["credentials"]);
expect(getGroupMemberManagementType()).toBe("local");
});
test("credentials + oidc with local management is local", () => {
mockEnv(["credentials", "oidc"], true);
expect(getGroupMemberManagementType()).toBe("local");
});
test("credentials + oidc without local management is mixed", () => {
mockEnv(["credentials", "oidc"], false);
expect(getGroupMemberManagementType()).toBe("mixed");
});
test("credentials + ldap is mixed", () => {
mockEnv(["credentials", "ldap"]);
expect(getGroupMemberManagementType()).toBe("mixed");
});
test("ldap only is external", () => {
mockEnv(["ldap"]);
expect(getGroupMemberManagementType()).toBe("external");
});
test("oidc only without local management is external", () => {
mockEnv(["oidc"], false);
expect(getGroupMemberManagementType()).toBe("external");
});
});
describe("getLocallyManageableProviders", () => {
test("returns only the enabled, locally managed providers", () => {
mockEnv(["credentials", "oidc", "ldap"], true);
expect(getLocallyManageableProviders()).toEqual(["credentials", "oidc"]);
mockEnv(["credentials", "oidc", "ldap"], false);
expect(getLocallyManageableProviders()).toEqual(["credentials"]);
mockEnv(["ldap"]);
expect(getLocallyManageableProviders()).toEqual([]);
});
});
describe("canManageGroupMembersLocally", () => {
test("is true when at least one enabled provider is managed locally", () => {
mockEnv(["credentials", "ldap"]);
expect(canManageGroupMembersLocally()).toBe(true);
mockEnv(["oidc"], true);
expect(canManageGroupMembersLocally()).toBe(true);
});
test("is false when every enabled provider is external", () => {
mockEnv(["ldap"]);
expect(canManageGroupMembersLocally()).toBe(false);
mockEnv(["oidc"], false);
expect(canManageGroupMembersLocally()).toBe(false);
});
});
+8 -1
View File
@@ -1,4 +1,11 @@
export { hasQueryAccessToIntegrationsAsync } from "./permissions/integration-query-permissions";
export { getIntegrationsWithPermissionsAsync } from "./permissions/integrations-with-permissions";
export { isProviderEnabled } from "./providers/check-provider";
export {
isProviderEnabled,
isGroupMembershipManagedLocally,
getLocallyManageableProviders,
getGroupMemberManagementType,
canManageGroupMembersLocally,
} from "./providers/check-provider";
export type { GroupMemberManagementType } from "./providers/check-provider";
export { createSessionCallback, createSessionAsync } from "./callbacks";
+29 -3
View File
@@ -12,11 +12,13 @@ import { colorSchemeCookieKey, everyoneGroup } from "@homarr/definitions";
import { createSignInEventHandler } from "../events";
vi.mock("next-auth", () => ({}));
const mockEnv = vi.hoisted(() => ({
AUTH_OIDC_GROUPS_ATTRIBUTE: "someRandomGroupsKey",
AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT: false,
}));
vi.mock("../env", () => {
return {
env: {
AUTH_OIDC_GROUPS_ATTRIBUTE: "someRandomGroupsKey",
},
env: mockEnv,
};
});
// eslint-disable-next-line @typescript-eslint/consistent-type-imports
@@ -198,6 +200,30 @@ describe("createSignInEventHandler should create signInEventHandler", () => {
});
expect(dbGroupMembers?.groupId).toBe("1");
});
test("should not synchronize groups when AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT is enabled", async () => {
// Arrange
mockEnv.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT = true;
const db = createDb();
await createUserAsync(db);
await createGroupAsync(db);
const eventHandler = createSignInEventHandler(db);
// Act
await eventHandler?.({
user: { id: "1", name: "test" },
profile: { preferred_username: "test", someRandomGroupsKey: ["test"] },
account: null,
});
// Assert
const dbGroupMembers = await db.query.groupMembers.findFirst({
where: eq(groupMembers.userId, "1"),
});
expect(dbGroupMembers).toBeUndefined();
// Cleanup
mockEnv.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT = false;
});
});
test.each([
["ldap" as const, { name: "test-new" }, undefined],