feat: support SSO admin mapping

Adds OIDC admin-group mapping with role reconciliation, split-horizon discovery URL support, minimal docs/config, and backend tests.

Co-authored-by: BoxBoxJason <contact@boxboxjason.dev>
Co-authored-by: Zimeng Xiong <me@zimengxiong.com>

Author: BoxBoxJason

README.md

@@ -281,6 +281,9 @@ backend:
     - AUTH_MODE=oidc_enforced
     - OIDC_PROVIDER_NAME=Authentik
     - OIDC_ISSUER_URL=https://auth.example.com/application/o/excalidash/
+    # Optional split-horizon setup when backend reaches IdP via internal DNS.
+    # Keep OIDC_ISSUER_URL browser-routable; set OIDC_DISCOVERY_URL for backend-only access.
+    # - OIDC_DISCOVERY_URL=http://auth-internal:9000/application/o/excalidash/
     - OIDC_CLIENT_ID=your-client-id
     # Optional for public clients; required for confidential clients
     # - OIDC_CLIENT_SECRET=your-client-secret
@@ -290,6 +293,10 @@ backend:
     # - OIDC_ID_TOKEN_SIGNED_RESPONSE_ALG=HS256
     - OIDC_REDIRECT_URI=https://excalidash.example.com/api/auth/oidc/callback
     - OIDC_SCOPES=openid profile email
+    # Optional: path to groups/roles claim in ID token/user claims (supports dot path)
+    - OIDC_GROUPS_CLAIM=groups
+    # Optional: comma-separated group names that should be ADMIN in ExcaliDash
+    - OIDC_ADMIN_GROUPS=excalidash-admins,platform-admins
 ```
 
 Quick preflight check (recommended before starting backend):
@@ -317,6 +324,9 @@ Notes:
 | Authentik issuer format     | Use provider issuer URL: `https://<authentik-host>/application/o/<provider-slug>/`.                                           |
 | Authentik `email_verified`  | If Authentik does not emit `email_verified=true`, either add the scope mapping or set `OIDC_REQUIRE_EMAIL_VERIFIED=false`.   |
 | Redirect URI                | Must be exact callback: `https://<excalidash-host>/api/auth/oidc/callback`.                                                   |
+| Split-horizon IdP networking | Set `OIDC_ISSUER_URL` to the browser-reachable issuer and optionally `OIDC_DISCOVERY_URL` to a backend-reachable internal URL. |
+| OIDC admin mapping          | If `OIDC_ADMIN_GROUPS` is set, admin role is reconciled on each authenticated request for OIDC users: users in those groups are promoted to `ADMIN`, users not in those groups are demoted to `USER`. |
+| Legacy sessions             | Users with old sessions (issued before group claims were embedded) should sign out/in once so OIDC group claims are refreshed. |
 
 </details>
 
@@ -352,6 +362,8 @@ Configure ExcaliDash backend for hybrid OIDC:
 ```bash
 cd backend
 cp .env.oidc.example .env
+# If backend runs in Docker and Keycloak issuer is localhost for browser, set:
+# OIDC_DISCOVERY_URL=http://keycloak:8080/realms/excalidash
 # Ensure OIDC_REDIRECT_URI matches where your frontend is running:
 # - http://localhost:6767/api/auth/oidc/callback (repo frontend dev default)
 # - https://excalidash.example.com/api/auth/oidc/callback (production)
@@ -499,6 +511,6 @@ Common flags:
 # Credits
 If you find ExcaliDash useful, please consider [sponsoring](https://github.com/sponsors/ZimengXiong)
 - Example designs from:
-  - https://github.com/Prakash-sa/system-design-ultimatum/tree/main
-  - https://github.com/kitsteam/excalidraw-examples/tree/main
+  - <https://github.com/Prakash-sa/system-design-ultimatum/tree/main>
+  - <https://github.com/kitsteam/excalidraw-examples/tree/main>
 - [The amazing work of Excalidraw & contributors](https://www.npmjs.com/package/@excalidraw/excalidraw)

backend/.env.example

@@ -45,13 +45,20 @@ CSRF_SECRET=change-this-secret-in-production
 # OIDC Configuration (required when AUTH_MODE=hybrid or AUTH_MODE=oidc_enforced)
 # OIDC_PROVIDER_NAME=Authentik
 # OIDC_ISSUER_URL=https://auth.example.com/application/o/excalidash/
+# Optional: internal backend-only discovery URL for split-horizon networking.
+# Example: browser uses OIDC_ISSUER_URL=https://auth.example.com while backend discovers via http://auth:9000
+# OIDC_DISCOVERY_URL=http://auth-internal:9000/application/o/excalidash/
 # OIDC_CLIENT_ID=your-client-id
 # OIDC_CLIENT_SECRET=your-client-secret
 # OIDC_REDIRECT_URI=https://excalidash.example.com/api/auth/oidc/callback
 # OIDC_TOKEN_ENDPOINT_AUTH_METHOD=client_secret_post
 # OIDC_SCOPES=openid profile email
 # OIDC_EMAIL_CLAIM=email
 # OIDC_EMAIL_VERIFIED_CLAIM=email_verified
+# OIDC_GROUPS_CLAIM=groups
+# Comma-separated OIDC groups/roles that should have ADMIN privileges.
+# When configured, OIDC users are promoted/demoted on authenticated requests.
+# OIDC_ADMIN_GROUPS=excalidash-admins,platform-admins
 # OIDC_REQUIRE_EMAIL_VERIFIED=true
 # OIDC_JIT_PROVISIONING=true
 # OIDC_FIRST_USER_ADMIN=true

backend/.env.oidc.example

@@ -17,7 +17,13 @@ AUTH_MODE=hybrid
 
 OIDC_PROVIDER_NAME=Keycloak
 OIDC_ISSUER_URL=http://localhost:8080/realms/excalidash
+# Optional when backend runs in a container but Keycloak issuer is localhost for browser.
+# OIDC_DISCOVERY_URL=http://keycloak:8080/realms/excalidash
 OIDC_CLIENT_ID=excalidash
+OIDC_ID_TOKEN_SIGNED_RESPONSE_ALG=RS256
+OIDC_GROUPS_CLAIM=realm_access.roles
+# Example: Keycloak realm role used to grant ADMIN in ExcaliDash
+# OIDC_ADMIN_GROUPS=excalidash-admin
 
 # Redirect URI must match the frontend you're using.
 OIDC_REDIRECT_URI=http://localhost:6767/api/auth/oidc/callback

backend/src/auth.ts

@@ -40,17 +40,30 @@ interface JwtPayload {
   email: string;
   type: "access" | "refresh";
   impersonatorId?: string;
+  authProvider?: "local" | "oidc";
+  oidcGroups?: string[];
 }
 
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === "string");
+
 const isJwtPayload = (decoded: unknown): decoded is JwtPayload => {
   if (typeof decoded !== "object" || decoded === null) {
     return false;
   }
   const payload = decoded as Record<string, unknown>;
+  const authProviderOk =
+    typeof payload.authProvider === "undefined" ||
+    payload.authProvider === "local" ||
+    payload.authProvider === "oidc";
+  const oidcGroupsOk =
+    typeof payload.oidcGroups === "undefined" || isStringArray(payload.oidcGroups);
   return (
     typeof payload.userId === "string" &&
     typeof payload.email === "string" &&
-    (payload.type === "access" || payload.type === "refresh")
+    (payload.type === "access" || payload.type === "refresh") &&
+    authProviderOk &&
+    oidcGroupsOk
   );
 };
 
@@ -393,14 +406,38 @@ export const createAuthRouter = (deps: CreateAuthRouterDeps): express.Router =>
   const generateTokens = (
     userId: string,
     email: string,
-    options?: { impersonatorId?: string }
+    options?: {
+      impersonatorId?: string;
+      authProvider?: "local" | "oidc";
+      oidcGroups?: string[];
+    }
   ) => {
+    const authProvider = options?.authProvider ?? "local";
+    const sanitizedOidcGroups =
+      authProvider === "oidc"
+        ? Array.from(
+            new Set(
+              (options?.oidcGroups ?? [])
+                .map((group) => group.trim())
+                .filter((group) => group.length > 0)
+            )
+          ).slice(0, 100)
+        : undefined;
+
+    const tokenPayload = {
+      userId,
+      email,
+      impersonatorId: options?.impersonatorId,
+      authProvider,
+      oidcGroups: sanitizedOidcGroups,
+    };
+
     const signOptions: SignOptions = {
       expiresIn: config.jwtAccessExpiresIn as StringValue,
       jwtid: crypto.randomUUID(),
     };
     const accessToken = jwt.sign(
-      { userId, email, type: "access", impersonatorId: options?.impersonatorId },
+      { ...tokenPayload, type: "access" },
       config.jwtSecret,
       signOptions
     );
@@ -410,7 +447,7 @@ export const createAuthRouter = (deps: CreateAuthRouterDeps): express.Router =>
       jwtid: crypto.randomUUID(),
     };
     const refreshToken = jwt.sign(
-      { userId, email, type: "refresh", impersonatorId: options?.impersonatorId },
+      { ...tokenPayload, type: "refresh" },
       config.jwtSecret,
       refreshSignOptions
     );

backend/src/auth/accountRoutes.ts

@@ -32,7 +32,11 @@ type RegisterAccountRoutesDeps = {
   generateTokens: (
     userId: string,
     email: string,
-    options?: { impersonatorId?: string }
+    options?: {
+      impersonatorId?: string;
+      authProvider?: "local" | "oidc";
+      oidcGroups?: string[];
+    }
   ) => { accessToken: string; refreshToken: string };
   getRefreshTokenExpiresAt: () => Date;
   setAuthCookies: (

backend/src/auth/adminRoutes.ts

@@ -59,7 +59,11 @@ type RegisterAdminRoutesDeps = {
   generateTokens: (
     userId: string,
     email: string,
-    options?: { impersonatorId?: string }
+    options?: {
+      impersonatorId?: string;
+      authProvider?: "local" | "oidc";
+      oidcGroups?: string[];
+    }
   ) => { accessToken: string; refreshToken: string };
   getRefreshTokenExpiresAt: () => Date;
   config: {

backend/src/auth/coreRoutes.ts

@@ -58,6 +58,8 @@ type RegisterCoreRoutesDeps = {
     email: string;
     type: "access" | "refresh";
     impersonatorId?: string;
+    authProvider?: "local" | "oidc";
+    oidcGroups?: string[];
   };
   config: {
     authMode: "local" | "hybrid" | "oidc_enforced";
@@ -77,7 +79,11 @@ type RegisterCoreRoutesDeps = {
   generateTokens: (
     userId: string,
     email: string,
-    options?: { impersonatorId?: string }
+    options?: {
+      impersonatorId?: string;
+      authProvider?: "local" | "oidc";
+      oidcGroups?: string[];
+    }
   ) => { accessToken: string; refreshToken: string };
   getRefreshTokenExpiresAt: () => Date;
   isMissingRefreshTokenTableError: (error: unknown) => boolean;
@@ -636,7 +642,11 @@ export const registerCoreRoutes = (deps: RegisterCoreRoutesDeps) => {
             const { accessToken, refreshToken: newRefreshToken } = generateTokens(
               user.id,
               user.email,
-              { impersonatorId: decoded.impersonatorId }
+              {
+                impersonatorId: decoded.impersonatorId,
+                authProvider: decoded.authProvider,
+                oidcGroups: decoded.oidcGroups,
+              }
             );
 
             const expiresAt = getRefreshTokenExpiresAt();
@@ -713,6 +723,8 @@ export const registerCoreRoutes = (deps: RegisterCoreRoutesDeps) => {
             email: user.email,
             type: "access",
             impersonatorId: decoded.impersonatorId,
+            authProvider: decoded.authProvider,
+            oidcGroups: decoded.oidcGroups,
           },
           config.jwtSecret,
           signOptions