feat: Add group/role exclusion filter for OIDC group sync

Allow filtering out system/default roles from group synchronization:
- Add shouldExcludeGroup() function with exact match and regex support
- Support comma-separated exclusion patterns via OPENID_GROUPS_EXCLUDE_PATTERN
- Case-insensitive exact matching for role names
- Regex patterns with 'regex:' prefix (e.g., regex:^default-.*)
- Update extractGroupsFromToken to accept and apply exclusion filter
- Add comprehensive documentation in .env.example

Use cases:
- Exclude Keycloak default roles (default-roles-*, manage-account, etc.)
- Exclude Auth0 system scopes (offline_access, openid, profile, email)
- Exclude authentication-only roles that shouldn't become groups
- Filter out UMA authorization roles (uma_authorization)

Examples:
  OPENID_GROUPS_EXCLUDE_PATTERN=default-roles-mediawan,manage-account,offline_access
  OPENID_GROUPS_EXCLUDE_PATTERN=regex:^default-.*,regex:^manage-.*,offline_access

Tested with Keycloak 26.x - successfully filters out system roles

Author: leondape

.env.example

@@ -573,6 +573,16 @@ OPENID_GROUPS_TOKEN_KIND=access
 # Examples: keycloak, auth0, okta, google
 OPENID_GROUP_SOURCE=oidc
 
+# Exclude specific groups/roles from being synced
+# Comma-separated list of exact role names (case-insensitive) or regex patterns (prefix with 'regex:')
+# Use this to filter out system roles, default roles, or authentication roles
+# Examples:
+#   - Exact matches: default-roles-mediawan,manage-account,view-profile,offline_access
+#   - Regex pattern: regex:^default-.*,regex:.*-account$
+#   - Mixed: default-roles-mediawan,regex:^uma_.*,offline_access
+# Leave empty or commented to sync all groups
+# OPENID_GROUPS_EXCLUDE_PATTERN=default-roles-mediawan,manage-account,view-profile,offline_access
+
 # LDAP
 LDAP_URL=
 LDAP_BIND_DN=

api/server/services/PermissionService.js

@@ -548,9 +548,10 @@ const syncUserOidcGroupsFromToken = async (user, tokenset, session = null) => {
     const claimPath = process.env.OPENID_GROUPS_CLAIM_PATH || 'realm_access.roles';
     const tokenKind = process.env.OPENID_GROUPS_TOKEN_KIND || 'access';
     const groupSource = process.env.OPENID_GROUP_SOURCE || 'oidc';
+    const exclusionPattern = process.env.OPENID_GROUPS_EXCLUDE_PATTERN || null;
 
     // Extract groups from token
-    const groupNames = extractGroupsFromToken(tokenset, claimPath, tokenKind);
+    const groupNames = extractGroupsFromToken(tokenset, claimPath, tokenKind, exclusionPattern);
 
     if (!groupNames || groupNames.length === 0) {
       logger.info(

api/utils/extractJwtClaims.js

@@ -104,14 +104,54 @@ function sanitizeGroupName(groupName) {
   return sanitized;
 }
 
+/**
+ * Checks if a group name should be excluded based on exclusion patterns.
+ * Supports exact matches (case-insensitive) and regex patterns (prefix with 'regex:').
+ * @param {string} groupName - The group name to check.
+ * @param {string|null} exclusionPattern - Comma-separated list of exact names or regex patterns.
+ * @returns {boolean} True if the group should be excluded.
+ */
+function shouldExcludeGroup(groupName, exclusionPattern) {
+  if (!exclusionPattern || typeof exclusionPattern !== 'string') {
+    return false;
+  }
+
+  const patterns = exclusionPattern.split(',').map(p => p.trim()).filter(Boolean);
+  
+  for (const pattern of patterns) {
+    // Check if it's a regex pattern
+    if (pattern.startsWith('regex:')) {
+      try {
+        const regexStr = pattern.substring(6); // Remove 'regex:' prefix
+        const regex = new RegExp(regexStr, 'i'); // Case-insensitive
+        if (regex.test(groupName)) {
+          logger.debug(`[shouldExcludeGroup] Excluding '${groupName}' (matched regex: ${regexStr})`);
+          return true;
+        }
+      } catch (error) {
+        logger.warn(`[shouldExcludeGroup] Invalid regex pattern '${pattern}': ${error.message}`);
+      }
+    } else {
+      // Exact match (case-insensitive)
+      if (pattern.toLowerCase() === groupName.toLowerCase()) {
+        logger.debug(`[shouldExcludeGroup] Excluding '${groupName}' (exact match: ${pattern})`);
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
 /**
  * Extracts groups from JWT token for OIDC group synchronization
  * @param {Object} tokenset - OpenID token set containing access_token and id_token
  * @param {string} claimPath - Dot-notation path to groups/roles claim
  * @param {string} tokenKind - Which token to extract from ('access' or 'id')
+ * @param {string|null} exclusionPattern - Optional exclusion pattern for filtering groups
  * @returns {Array<string>} Array of sanitized group names
  */
-function extractGroupsFromToken(tokenset, claimPath, tokenKind = 'access') {
+function extractGroupsFromToken(tokenset, claimPath, tokenKind = 'access', exclusionPattern = null) {
   try {
     if (!tokenset || typeof tokenset !== 'object') {
       logger.warn('[extractGroupsFromToken] Invalid tokenset provided');
@@ -137,8 +177,21 @@ function extractGroupsFromToken(tokenset, claimPath, tokenKind = 'access') {
       .map(sanitizeGroupName)
       .filter(name => name.length > 0);
 
+    // Apply exclusion filter
+    const filteredGroups = exclusionPattern 
+      ? sanitizedGroups.filter(g => !shouldExcludeGroup(g, exclusionPattern))
+      : sanitizedGroups;
+
     // Remove duplicates
-    const uniqueGroups = [...new Set(sanitizedGroups)];
+    const uniqueGroups = [...new Set(filteredGroups)];
+
+    const excludedCount = sanitizedGroups.length - uniqueGroups.length;
+    if (excludedCount > 0) {
+      logger.info(
+        `[extractGroupsFromToken] Excluded ${excludedCount} groups based on exclusion pattern`,
+        { pattern: exclusionPattern },
+      );
+    }
 
     logger.info(
       `[extractGroupsFromToken] Extracted ${uniqueGroups.length} unique groups from ${tokenKind} token`,
@@ -156,5 +209,6 @@ module.exports = {
   extractClaimFromToken,
   sanitizeGroupName,
   extractGroupsFromToken,
+  shouldExcludeGroup,
 };