[jtodaroii]

Summary

Login-time Entra sync creates a Group for every Entra group the user belongs to, so in large tenants thousands of groups that are never shared with end up in every user's ACL principal list. This adds an opt-in setting, permissions.syncOnlyExistingEntraGroups in librechat.yaml (env fallback ENTRA_ID_SYNC_ONLY_EXISTING_GROUPS), that skips creating missing groups during sync. Membership is still added and removed on groups already in the database, which are created when someone shares a resource with them. Default behavior is unchanged.

Closes #16633

Related to #15830, #16233

How it works

syncsOnlyExistingEntraGroups in packages/api/src/acl/principals.ts resolves the setting: the librechat.yaml value wins when set, otherwise the env flag decides. The OAuth callback runs before the config middleware, so oauth.js resolves the user's app config and passes it to syncUserEntraGroupMemberships, which skips steps 4–6 (fetch details, upsert, add) when the setting is on.

Type of change

• Feature
• Performance improvement

Testing

Tested environments/configuration:

• Database: mongodb-memory-server
• Settings: librechat.yaml true/false/unset, env flag true/unset

Automated tests:

• api/server/services/PermissionService.spec.js: missing groups are not fetched or created with the env flag or the YAML setting; the user is still removed from existing groups they left; the YAML setting overrides the env flag. Each new case fails without the change.
• packages/api/src/acl/principals.spec.ts: precedence of the YAML setting over the env flag.
• PermissionService.spec.js plus the oauth, oauth.state and admin/auth.refresh route suites: 135 passed; principals.spec.ts: 7 passed.

Screenshots / recordings

No user-facing change

Risk / compatibility

• New optional config field and env var, off by default.
• Groups already created by earlier syncs are left in place; the setting stops new ones from being added.

[Copilot]

Copilot review overview

🟡 Changes recommended

The toggle lacks required YAML configuration support, and new backend behavior was added to the legacy CJS layer.

Review effort: Balanced
Findings: 3

Open (3)

• Add defaulted configSchema field for the sync feature toggle · New
• Move sync policy implementation from legacy CJS into TypeScript · New
• Update documentation to describe conditional group creation · New

What changed in this PR

Adds an opt-in mode that limits login-time Entra synchronization to groups already stored locally, reducing ACL principal growth.

Changes:

• Skips missing-group creation when the flag is enabled.
• Documents the new environment variable.
• Tests membership additions, removals, and skipped creation.

File	Description
.env.example	Documents the new toggle.
api/​server/​services/​PermissionService.js	Applies existing-group-only synchronization.
api/​server/​services/​PermissionService.spec.js	Tests enabled and default behavior.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jtodaroii]

@danny-avila Merged current dev with no conflicts; ready for review. Closes #16633.