test(auth): preserve OIDC provider guard

apps/docs/docs/advanced/single-sign-on/index.mdx

@@ -202,9 +202,9 @@ Homarr supports multiple authentication options, from internal userbase (credent
     | ``AUTH_OIDC_CLIENT_NAME``   | Display name of provider (in login screen)                 | OIDC          |
     | ``AUTH_OIDC_AUTO_LOGIN``    | Automatically redirect to OIDC login                       | false         |
     | ``AUTH_OIDC_SCOPE_OVERWRITE`` | Overwrite default scopes (openid, profile, email)        | openid email profile groups           |
-    | ``AUTH_OIDC_GROUPS_ATTRIBUTE`` | Attribute used for groups (roles) claim                  | groups        |
+    | ``AUTH_OIDC_GROUPS_ATTRIBUTE`` | Attribute used for groups (roles) claim. Dot-separated paths such as `resource_access.homarr.roles` are supported. | groups        |
     | ``AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT`` | Stop syncing group memberships of OIDC users from the groups claim and manage them locally via the group members page instead | false |
-    | ``AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE`` | Overwrite name attribute. By default it will use preferred_username if it does not contain a `@` and otherwise name. | ---          |
+    | ``AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE`` | Overwrite name attribute. Dot-separated paths are supported. By default it will use preferred_username if it does not contain a `@` and otherwise name. | ---          |
     | ``AUTH_OIDC_FORCE_USERINFO`` | Force userinfo endpoint to be used for user information.    | false         |
     | ``AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING`` | Enable account linking for OIDC provider. This will link the OIDC accounts by email. Be sure that you have verified emails to prevent stealing accounts. | false |
     | ``AUTH_OIDC_ENABLE_DANGEROUS_CREDENTIALS_LINKING`` | Link an OIDC identity to an existing credentials user with the same email. The credentials login and existing user data are preserved. Requires the OIDC profile to contain `email_verified: true`. | false |

packages/auth/events.ts

@@ -9,7 +9,7 @@ import { groupMembers, groups, users } from "@homarr/db/schema";
 import { colorSchemeCookieKey, everyoneGroup } from "@homarr/definitions";
 
 import { env } from "./env";
-import { extractProfileName } from "./providers/oidc/oidc-provider";
+import { extractProfileName, getProfileValueByPath } from "./providers/oidc/profile";
 
 const logger = createLogger({ module: "authEvents" });
 
@@ -31,16 +31,11 @@ export const createSignInEventHandler = (db: Database): Exclude<NextAuthConfig["
     if (!dbUser) throw new Error("User not found");
 
     const groupsKey = env.AUTH_OIDC_GROUPS_ATTRIBUTE;
+    const profileGroups = profile ? getProfileValueByPath(profile, groupsKey) : undefined;
     // Groups from oidc provider are provided from the profile, it's not typed.
-    if (
-      !env.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT &&
-      dbUser.provider === "oidc" &&
-      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[]);
+    if (!env.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT && dbUser.provider === "oidc" && Array.isArray(profileGroups)) {
+      logger.debug(`Using profile groups (${groupsKey}): ${JSON.stringify(profileGroups)}`);
+      await synchronizeGroupsWithExternalForUserAsync(db, user.id, profileGroups as string[]);
     }
 
     // In ldap-authroization we return the groups from ldap, it's not typed.

packages/auth/providers/oidc/oidc-provider.ts

@@ -7,6 +7,7 @@ import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/h
 
 import { env } from "../../env";
 import { createRedirectUri } from "../../redirect";
+import { extractProfileName } from "./profile";
 import { assertVerifiedEmailForCredentialsLinking } from "./verified-email";
 
 export const OidcProvider = (headers: ReadonlyHeaders | null): OIDCConfig<Profile> => ({
@@ -76,12 +77,3 @@ export const OidcProvider = (headers: ReadonlyHeaders | null): OIDCConfig<Profil
   // @ts-expect-error `undici` has a `duplex` option
   [customFetch]: fetchWithTrustedCertificatesAsync,
 });
-
-export const extractProfileName = (profile: Profile) => {
-  if (!env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE) {
-    // Use the name as the username if the preferred_username is an email address
-    return profile.preferred_username?.includes("@") ? profile.name : profile.preferred_username;
-  }
-
-  return profile[env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE as keyof typeof profile] as string;
-};

packages/auth/providers/oidc/profile.ts

@@ -0,0 +1,23 @@
+import type { Profile } from "@auth/core/types";
+
+import { env } from "../../env";
+
+export const getProfileValueByPath = (profile: Profile, path: string): unknown => {
+  return path.split(".").reduce<unknown>((value, key) => {
+    if (typeof value !== "object" || value === null || !Object.hasOwn(value, key)) {
+      return undefined;
+    }
+
+    return (value as Record<string, unknown>)[key];
+  }, profile);
+};
+
+export const extractProfileName = (profile: Profile): string | undefined => {
+  if (!env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE) {
+    // Use the name as the username if the preferred_username is an email address
+    return (profile.preferred_username?.includes("@") ? profile.name : profile.preferred_username) ?? undefined;
+  }
+
+  const profileName = getProfileValueByPath(profile, env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE);
+  return typeof profileName === "string" ? profileName : undefined;
+};

packages/auth/providers/oidc/test/profile.spec.ts

@@ -0,0 +1,96 @@
+import type { Profile } from "@auth/core/types";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+const mockEnv = vi.hoisted(() => ({
+  AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE: undefined as string | undefined,
+}));
+
+vi.mock("../../../env", () => ({ env: mockEnv }));
+
+import { extractProfileName, getProfileValueByPath } from "../profile";
+
+afterEach(() => {
+  mockEnv.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE = undefined;
+});
+
+describe("getProfileValueByPath", () => {
+  const profile = {
+    sub: "user-id",
+    resource_access: {
+      homarr: {
+        roles: ["admins"],
+      },
+    },
+  } satisfies Profile;
+
+  test("returns a top-level claim", () => {
+    expect(getProfileValueByPath(profile, "sub")).toBe("user-id");
+  });
+
+  test("returns a nested claim", () => {
+    expect(getProfileValueByPath(profile, "resource_access.homarr.roles")).toEqual(["admins"]);
+  });
+
+  test("returns undefined when the path does not exist", () => {
+    expect(getProfileValueByPath(profile, "resource_access.missing.roles")).toBeUndefined();
+  });
+});
+
+describe("extractProfileName", () => {
+  test("uses preferred_username when overwrite is not set", () => {
+    const profile = {
+      sub: "user-id",
+      preferred_username: "johndoe",
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBe("johndoe");
+  });
+
+  test("uses name when preferred_username is an email", () => {
+    const profile = {
+      sub: "user-id",
+      preferred_username: "john@example.com",
+      name: "John Doe",
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBe("John Doe");
+  });
+
+  test("returns undefined when the fallback name is null", () => {
+    const profile = {
+      sub: "user-id",
+      preferred_username: "john@example.com",
+      name: null,
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBeUndefined();
+  });
+
+  test("returns undefined when preferred_username is missing", () => {
+    const profile = {
+      sub: "user-id",
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBeUndefined();
+  });
+
+  test("uses a nested name claim when configured", () => {
+    mockEnv.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE = "user.profile.display_name";
+    const profile = {
+      sub: "user-id",
+      user: { profile: { display_name: "Nested User" } },
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBe("Nested User");
+  });
+
+  test("returns undefined when the configured claim is not a string", () => {
+    mockEnv.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE = "user.profile";
+    const profile = {
+      sub: "user-id",
+      user: { profile: { display_name: "Nested User" } },
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBeUndefined();
+  });
+});

packages/auth/test/events.spec.ts

@@ -1,7 +1,7 @@
 import type { ResponseCookie } from "next/dist/compiled/@edge-runtime/cookies";
 import type { ReadonlyRequestCookies } from "next/dist/server/web/spec-extension/adapters/request-cookies";
 import { cookies } from "next/headers";
-import { describe, expect, test, vi } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { eq } from "@homarr/db";
 import type { Database } from "@homarr/db";
@@ -21,6 +21,12 @@ vi.mock("../env", () => {
     env: mockEnv,
   };
 });
+
+afterEach(() => {
+  mockEnv.AUTH_OIDC_GROUPS_ATTRIBUTE = "someRandomGroupsKey";
+  mockEnv.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT = false;
+});
+
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
 type HeadersExport = typeof import("next/headers");
 vi.mock("next/headers", async (importOriginal) => {
@@ -152,6 +158,30 @@ describe("createSignInEventHandler should create signInEventHandler", () => {
       });
       expect(dbGroupMembers?.groupId).toBe("1");
     });
+    test("should add missing group membership from a nested claim", async () => {
+      // Arrange
+      mockEnv.AUTH_OIDC_GROUPS_ATTRIBUTE = "resource_access.homarr.roles";
+      const db = createDb();
+      await createUserAsync(db, "oidc");
+      await createGroupAsync(db);
+      const eventHandler = createSignInEventHandler(db);
+
+      // Act
+      await eventHandler?.({
+        user: { id: "1", name: "test" },
+        profile: {
+          preferred_username: "test",
+          resource_access: { homarr: { roles: ["test"] } },
+        },
+        account: null,
+      });
+
+      // Assert
+      const dbGroupMembers = await db.query.groupMembers.findFirst({
+        where: eq(groupMembers.userId, "1"),
+      });
+      expect(dbGroupMembers?.groupId).toBe("1");
+    });
     test("should remove group membership", async () => {
       // Arrange
       const db = createDb();

pnpm-lock.yaml

@@ -25,11 +25,11 @@ catalogs:
       specifier: 0.14.9
       version: 0.14.9
     '@auth/core':
-      specifier: ^0.41.3
-      version: 0.41.3
+      specifier: ^0.41.2
+      version: 0.41.2
     '@auth/drizzle-adapter':
-      specifier: ^1.11.3
-      version: 1.11.3
+      specifier: ^1.11.2
+      version: 1.11.2
     '@babel/parser':
       specifier: ^7.29.7
       version: 7.29.7
@@ -520,8 +520,8 @@ catalogs:
       specifier: 16.3.1
       version: 16.3.1
     next-auth:
-      specifier: 5.0.0-beta.32
-      version: 5.0.0-beta.32
+      specifier: 5.0.0-beta.31
+      version: 5.0.0-beta.31
     next-intl:
       specifier: 4.13.1
       version: 4.13.1
@@ -1587,10 +1587,10 @@ importers:
     dependencies:
       '@auth/core':
         specifier: 'catalog:'
-        version: 0.41.3
+        version: 0.41.2
       '@auth/drizzle-adapter':
         specifier: 'catalog:'
-        version: 1.11.3
+        version: 1.11.2
       '@homarr/common':
         specifier: workspace:^0.1.0
         version: link:../common
@@ -1620,7 +1620,7 @@ importers:
         version: 16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0)
       next-auth:
         specifier: 'catalog:'
-        version: 5.0.0-beta.32(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7)
+        version: 5.0.0-beta.31(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7)
       react:
         specifier: 'catalog:'
         version: 19.2.7
@@ -1989,7 +1989,7 @@ importers:
     dependencies:
       '@auth/core':
         specifier: 'catalog:'
-        version: 0.41.3
+        version: 0.41.2
       '@homarr/common':
         specifier: workspace:^0.1.0
         version: link:../common
@@ -3346,12 +3346,12 @@ packages:
       react:
         optional: true
 
-  '@auth/core@0.41.3':
-    resolution: {integrity: sha512-sJ3JMHHkXMD3aOjopv7mOBTO1Ocw4b0fAEXJBz6k7YHLpYQI6C40jCUPc5fNvUKxXRXNE1/sRISA15UrwWJBTw==}
+  '@auth/core@0.41.2':
+    resolution: {integrity: sha512-Hx5MNBxN2fJTbJKGUKAA0wca43D0Akl3TvufY54Gn8lop7F+34vU1zA1pn0vQfIoVuLIrpfc2nkyjwIaPJMW7w==}
     peerDependencies:
       '@simplewebauthn/browser': ^9.0.1
       '@simplewebauthn/server': ^9.0.2
-      nodemailer: ^7.0.7 || ^8.0.5
+      nodemailer: ^7.0.7
     peerDependenciesMeta:
       '@simplewebauthn/browser':
         optional: true
@@ -3360,8 +3360,8 @@ packages:
       nodemailer:
         optional: true
 
-  '@auth/drizzle-adapter@1.11.3':
-    resolution: {integrity: sha512-TxqVasPVuf7LDAT1Yuu6bftpuet8o0tjdXW+mXpnXWdSRPQsomdzMoz9RsXkFN/JfdK+/DwdgOEmOTv1gbiFNw==}
+  '@auth/drizzle-adapter@1.11.2':
+    resolution: {integrity: sha512-VOuj7REI8jfJjpSbsYwDM/Zrn55T6lS9Yc+29V+EXMcel8eqG7x+7LodNfd1WHjakfkLYi+qsbYUHB3E6aDA4w==}
 
   '@babel/code-frame@7.29.0':
     resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
@@ -13685,13 +13685,13 @@ packages:
   neverpanic@0.0.8:
     resolution: {integrity: sha512-vVdkelrLxaow/fdWDumzNBO+jwm6X8bxeLJc34THtpj70u0C5QBkcV6CRCu2X726km7XD45N0A3QtYCla4RvKw==}
 
-  next-auth@5.0.0-beta.32:
-    resolution: {integrity: sha512-CGlChIEWZ6LltNVxrE5yiySMID+Idpmry47JYA5lLwgD8Sx02a8M65VL0TWVz9nbnOioS/tCW/rP/0+mE7Qp4Q==}
+  next-auth@5.0.0-beta.31:
+    resolution: {integrity: sha512-1OBgCKPzo+S7UWWMp3xgvGvIJ0OpV7B3vR4ZDRqD9a4Ch+OT6dakLXG9ivhtmIWVa71nTSXattOHyCg8sNi8/Q==}
     peerDependencies:
       '@simplewebauthn/browser': ^9.0.1
       '@simplewebauthn/server': ^9.0.2
       next: ^14.0.0-0 || ^15.0.0 || ^16.0.0
-      nodemailer: ^7.0.7 || ^8.0.5
+      nodemailer: ^7.0.7
       react: ^18.2.0 || ^19.0.0
     peerDependenciesMeta:
       '@simplewebauthn/browser':
@@ -17439,7 +17439,7 @@ snapshots:
       '@types/react': 19.2.17
       react: 19.2.7
 
-  '@auth/core@0.41.3':
+  '@auth/core@0.41.2':
     dependencies:
       '@panva/hkdf': 1.2.1
       jose: 6.2.3
@@ -17447,9 +17447,9 @@ snapshots:
       preact: 10.24.3
       preact-render-to-string: 6.5.11(preact@10.24.3)
 
-  '@auth/drizzle-adapter@1.11.3':
+  '@auth/drizzle-adapter@1.11.2':
     dependencies:
-      '@auth/core': 0.41.3
+      '@auth/core': 0.41.2
     transitivePeerDependencies:
       - '@simplewebauthn/browser'
       - '@simplewebauthn/server'
@@ -30001,9 +30001,9 @@ snapshots:
 
   neverpanic@0.0.8: {}
 
-  next-auth@5.0.0-beta.32(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7):
+  next-auth@5.0.0-beta.31(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7):
     dependencies:
-      '@auth/core': 0.41.3
+      '@auth/core': 0.41.2
       next: 16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0)
       react: 19.2.7
 

pnpm-workspace.yaml

@@ -14,8 +14,8 @@ catalog:
   "@codemirror/state": ^6.6.0
   "@codemirror/theme-one-dark": ^6.1.3
   "@codemirror/view": ^6.43.0
-  "@auth/core": ^0.41.3
-  "@auth/drizzle-adapter": ^1.11.3
+  "@auth/core": ^0.41.2
+  "@auth/drizzle-adapter": ^1.11.2
   "@ctrl/deluge": ^8.0.0
   "@ctrl/qbittorrent": ^9.14.0
   "@ctrl/transmission": ^7.4.0
@@ -174,7 +174,7 @@ catalog:
   maria2: ^0.4.1
   mysql2: 3.22.6
   next: 16.3.1
-  next-auth: 5.0.0-beta.32
+  next-auth: 5.0.0-beta.31
   next-intl: 4.13.1
   next-themes: ^0.4.6
   node-loader: ^2.1.0