[mirror] feat(permissions): wire LLM admin + user group + sidebar access onto new permission system

[yashwant86]

Mirror of upstream onyx-dot-app#10173 for benchmark. Do not merge.

---

Summary by MergeMonkey

• New Capabilities:
  • Wires LLM admin access, user group management, and sidebar visibility onto new permission system.
  • Adds READ_USER_GROUPS permission to enable group-based access control.
  • Implements permission-based access gates for admin panel features (agents, connectors, LLMs, document sets, etc.).
• Resolved Issues:
  • Fixes error type mapping in EE cc_pair endpoints to use OnyxError instead of HTTPException.
  • Corrects HTTP status codes in error responses (400→INSUFFICIENT_PERMISSIONS, CONFLICT→OnyxError).
• Maintenance:
  • Removes legacy role-based access checks in favor of permission-based gates.
  • Deletes obsolete permission tests (cc_pair, connector, doc_set, credential, persona, user_role, whole_curator_flow).
  • Refactors user role handling to support nullable roles and permission inheritance.
  • Adds database migration to make user role nullable.

[bot-mergemonkey]

⚡ Risk Assessment — CRITICAL · ~45 min review

Focus areas: Permission expansion logic and permission inheritance · Nullable user role handling and migration safety · API endpoint permission gate correctness · Frontend permission check implementation and coverage

Assessment: Migrates entire auth system from role-based to permission-based access control with breaking API changes.

Walkthrough

User initiates login → system assigns user to default group based on account type → user receives effective permissions from group membership → frontend checks permissions before rendering admin features → API endpoints validate permissions via dependency injection → access granted/denied based on permission matrix.

Changes

Files	Summary
Permission System Core backend/onyx/auth/permissions.py backend/onyx/db/enums.py	Adds READ_USER_GROUPS permission and expands permission definitions. Implements permission expansion logic to derive implied permissions from granted ones.
EE CC Pair Error Handling backend/ee/onyx/server/documents/cc_pair.py	Replaces HTTPException with OnyxError for permission-related failures. Maps HTTP status codes to semantic error codes (INSUFFICIENT_PERMISSIONS, CONFLICT, INTERNAL_ERROR).
Backend Auth & User Management backend/onyx/auth/users.py backend/onyx/auth/schemas.py backend/onyx/auth/api_key.py backend/onyx/db/auth.py backend/onyx/db/models.py	Refactors user role handling to support nullable roles. Updates user creation and API key role assignment to use permission-based defaults. Adds role value serialization.
Admin Panel Permission Gates backend/onyx/server/documents/cc_pair.py backend/onyx/server/features/document_set/api.py backend/onyx/server/documents/connector.py backend/onyx/server/documents/credential.py backend/onyx/server/manage/llm/api.py backend/onyx/server/manage/administrative.py backend/onyx/server/manage/discord_bot/api.py backend/onyx/server/manage/slack_bot.py backend/onyx/server/features/tool/api.py backend/onyx/server/features/persona/api.py backend/onyx/server/features/oauth_config/api.py backend/onyx/server/api_key/api.py backend/onyx/server/pat/api.py backend/onyx/server/onyx_api/ingestion.py backend/onyx/server/federated/api.py backend/ee/onyx/server/user_group/api.py backend/ee/onyx/server/oauth/api.py backend/ee/onyx/server/oauth/confluence_cloud.py backend/ee/onyx/server/oauth/google_drive.py backend/ee/onyx/server/oauth/slack.py backend/ee/onyx/server/query_history/api.py backend/ee/onyx/server/token_rate_limits/api.py	Replaces role-based access checks with permission-based dependency injection. Uses require_permission() for FULL_ADMIN_PANEL_ACCESS and current_curator_or_admin_user for curator-level operations.
Database Query & Filtering backend/onyx/db/document_set.py backend/onyx/db/connector_credential_pair.py backend/onyx/db/credentials.py backend/onyx/db/feedback.py backend/onyx/db/users.py backend/onyx/db/api_key.py backend/onyx/db/llm.py backend/onyx/db/notification.py backend/onyx/db/persona.py backend/ee/onyx/db/user_group.py backend/ee/onyx/db/token_limit.py backend/ee/onyx/db/analytics.py backend/ee/onyx/db/license.py	Refactors permission checks to use has_permission() and get_effective_permissions(). Removes legacy role-based filtering logic. Simplifies curator/admin role checks.
LLM Provider Access Control backend/onyx/llm/factory.py backend/onyx/db/user_preferences.py	Updates LLM provider access logic to accept is_admin boolean instead of deriving from user role. Removes role-to-account-type mapping.
Error Handling & Codes backend/onyx/error_handling/error_codes.py	Adds BAD_REQUEST and DOCUMENT_SET_NOT_FOUND error codes for semantic error responses.
Database Migrations backend/alembic/versions/c8e316473aaa_make_user_role_nullable.py	Adds migration to make user role column nullable, supporting permission-based role assignment.
Integration Tests - Permission Matrix backend/tests/integration/tests/permissions/_access_matrix.py, test_add_agents.py, test_create_user_api_keys.py, test_manage_actions.py, test_manage_agents.py, test_manage_bots.py, test_manage_connectors.py, test_manage_document_sets.py, test_manage_llms.py, test_manage_service_account_api_keys.py, test_manage_user_groups.py, test_read_query_history.py	Adds comprehensive permission-based access matrix tests for all admin panel features. Replaces legacy role-based permission tests.
Integration Tests - Cleanup backend/tests/integration/tests/permissions/test_cc_pair_permissions.py, test_connector_permissions.py, test_doc_set_permissions.py, test_credential_permissions.py, test_persona_permissions.py, test_user_role_permissions.py, test_whole_curator_flow.py	Removes obsolete role-based permission tests replaced by new permission matrix tests.
Integration Tests - Fixtures & Utilities backend/tests/integration/tests/permissions/conftest.py backend/tests/integration/tests/permissions/test_auth_permission_propagation.py backend/tests/integration/tests/permissions/test_file_connector_permissions.py backend/tests/integration/tests/permissions/test_admin_access.py backend/tests/integration/common_utils/managers/user.py backend/tests/integration/common_utils/managers/user_group.py backend/tests/integration/common_utils/managers/api_key.py	Updates test fixtures and utilities to support permission-based access control. Adds user group manager methods. Refactors user role verification.
Integration Tests - User & Auth backend/tests/integration/tests/users/test_password_signup_upgrade.py backend/tests/integration/tests/users/test_user_pagination.py backend/tests/integration/tests/users/test_slack_user_deactivation.py backend/tests/integration/tests/users/test_default_group_assignment.py backend/tests/integration/tests/api_key/test_api_key.py backend/tests/integration/tests/auth/test_saml_user_conversion.py backend/tests/integration/tests/chat/test_chat_session_access.py	Updates user and auth tests to work with nullable roles and permission-based access. Adds user group assignment verification.
Integration Tests - Other backend/tests/integration/tests/query_history/test_query_history.py backend/tests/integration/tests/query_history/utils.py backend/tests/integration/tests/connector/test_connector_deletion.py backend/tests/integration/tests/document_set/test_syncing.py backend/tests/integration/tests/pat/test_pat_api.py backend/tests/integration/tests/llm_provider/test_llm_provider.py backend/tests/integration/multitenant_tests/syncing/test_search_permissions.py backend/tests/integration/multitenant_tests/discord_bot/test_discord_bot_multitenant.py backend/tests/integration/multitenant_tests/invitation/test_user_invitation.py backend/tests/integration/multitenant_tests/tenants/test_tenant_creation.py backend/tests/integration/tests/scim/test_scim_groups.py backend/tests/integration/tests/scim/test_scim_users.py backend/tests/integration/tests/usergroup/test_usergroup_syncing.py backend/tests/integration/conftest.py	Updates various integration tests to use permission-based access and user group assignment. Adds API key creation for permission-gated endpoints.
Unit Tests backend/tests/unit/onyx/auth/test_permissions.py backend/tests/unit/onyx/auth/test_jwt_provisioning.py backend/tests/unit/onyx/auth/test_user_registration.py backend/tests/unit/onyx/server/test_full_user_snapshot.py backend/tests/unit/onyx/server/scim/conftest.py backend/tests/external_dependency_unit/db/test_user_account_type.py backend/tests/external_dependency_unit/llm/test_llm_provider.py backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py backend/tests/external_dependency_unit/llm/test_llm_provider_called.py backend/tests/external_dependency_unit/conftest.py backend/tests/external_dependency_unit/connectors/google_drive/test_google_drive_group_sync.py backend/tests/external_dependency_unit/craft/conftest.py backend/tests/daily/conftest.py	Updates unit tests to support nullable roles and permission-based access. Adds permission expansion tests.
User Management API backend/onyx/server/manage/users.py, models.py	Removes set-user-role and get-user-role endpoints. Updates user response models to include effective_permissions. Refactors user snapshot generation.
Frontend - Permission System web/src/lib/permissions.ts, permissions.test.ts	Adds frontend permission checking utilities and tests. Implements hasPermission() and getFirstPermittedAdminRoute() helpers.
Frontend - Admin Routes & Sidebar web/src/lib/admin-routes.ts web/src/lib/admin-sidebar-utils.ts web/src/sections/sidebar/AdminSidebar.tsx web/src/sections/sidebar/AppSidebar.tsx web/src/sections/sidebar/CreateConnectorSidebar.tsx web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx web/src/app/admin/connector/[ccPairId]/page.tsx web/src/app/craft/v1/configure/page.tsx	Refactors sidebar visibility and admin route access to use permission-based checks. Adds permission-gated feature flags. Removes role-based sidebar filtering.
Frontend - User Management UI web/src/refresh-pages/admin/UsersPage/index.tsx web/src/refresh-pages/admin/UsersPage/UsersTable.tsx web/src/refresh-pages/admin/UsersPage/UserFilters.tsx web/src/refresh-pages/admin/UsersPage/EditUserModal.tsx web/src/refresh-pages/admin/UsersPage/AccountTypeCell.tsx web/src/refresh-pages/admin/UsersPage/svc.ts web/src/refresh-pages/admin/UsersPage/interfaces.ts web/src/components/admin/users/SignedUpUserTable.tsx web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx	Removes user role management UI (role dropdown, role cell). Replaces with account type display. Removes setUserRole API call. Updates user filters and modals.
Frontend - Service Accounts & Groups web/src/refresh-pages/admin/ServiceAccountsPage/index.tsx web/src/refresh-pages/admin/ServiceAccountsPage/ApiKeyFormModal.tsx web/src/refresh-pages/admin/ServiceAccountsPage/interfaces.ts web/src/refresh-pages/admin/GroupsPage/shared.tsx web/src/refresh-pages/admin/GroupsPage/useGroupMemberCandidates.ts web/src/refresh-pages/admin/GroupsPage/EditGroupPage.tsx web/src/refresh-pages/admin/GroupsPage/CreateGroupPage.tsx web/src/refresh-pages/admin/GroupsPage/GroupPermissionsSection.tsx web/src/refresh-pages/admin/GroupsPage/interfaces.ts	Updates service account and group management to use permission-based access. Adds group permissions section. Refactors role handling in group member candidates.
Frontend - Auth & User Context web/src/providers/UserProvider.tsx web/src/lib/auth/requireAuth.ts web/src/hooks/useAdminUsers.ts web/src/hooks/useUserCounts.ts	Updates user context to derive isAdmin from permission checks. Removes role-based allowlist. Updates user counts to use role_counts field.
Frontend - Components & Pages web/src/components/admin/ClientLayout.tsx web/src/components/admin/ClientLayout.test.tsx web/src/components/admin/connectors/AccessTypeGroupSelector.tsx web/src/components/IsPublicGroupSelector.tsx web/src/components/ConnectorMultiSelect.tsx web/src/components/GenericMultiSelect.tsx web/src/refresh-pages/SettingsPage.tsx web/src/refresh-pages/AgentsNavigationPage.tsx web/src/refresh-pages/AgentEditorPage.tsx web/src/refresh-pages/AppPage.tsx web/src/refresh-pages/admin/AgentsPage/AgentRowActions.tsx web/src/sections/cards/AgentCard.tsx web/src/sections/modals/ShareAgentModal.tsx web/src/sections/modals/llmConfig/shared.tsx web/src/sections/onboarding/OnboardingFlow.tsx web/src/refresh-components/popovers/ActionsPopover/index.tsx	Updates components to use permission-based access checks via hasPermission(). Removes role-based visibility logic. Adds permission-gated feature display.
Frontend - E2E Tests web/tests/e2e/admin/permissions/fixtures.ts web/tests/e2e/admin/permissions/permission_gating.spec.ts web/tests/e2e/admin/permissions/permission_system.spec.ts web/tests/e2e/utils/permissions.ts web/tests/e2e/utils/onyxApiClient.ts web/tests/e2e/global-setup.ts web/tests/e2e/onboarding/onboarding_flow.spec.ts web/tests/e2e/agents/create_and_edit_agent.spec.ts web/tests/e2e/mcp/mcp_oauth_flow.spec.ts	Adds comprehensive E2E tests for permission-based access gating. Updates API client with permission management methods. Refactors user role setup in global setup.
Frontend - Types web/src/lib/types.ts	Updates UserRole enum with new roles (GLOBAL_CURATOR, LIMITED, SLACK_USER, EXT_PERM_USER). Adds effective_permissions field to user snapshots. Removes invalid role hover text.
Frontend - Admin Routes Config web/src/lib/admin-routes.ts	Expands admin routes configuration with permission-based feature flags and route definitions.

Sequence Diagram

sequenceDiagram
  participant User
  participant Frontend
  participant API
  participant AuthMiddleware
  participant PermissionEngine
  participant Database
  User->>Frontend: Login
  Frontend->>API: POST /auth/login
  API->>AuthMiddleware: Validate credentials
  AuthMiddleware->>Database: Fetch user
  Database-->>AuthMiddleware: User record
  AuthMiddleware->>PermissionEngine: Get effective permissions
  PermissionEngine->>Database: Fetch user groups
  Database-->>PermissionEngine: Group memberships
  PermissionEngine->>Database: Fetch group permissions
  Database-->>PermissionEngine: Permission list
  PermissionEngine-->>AuthMiddleware: Effective permissions
  AuthMiddleware-->>API: User + permissions
  API-->>Frontend: Auth token + user snapshot
  Frontend->>Frontend: Check hasPermission(MANAGE_LLMS)
  Frontend->>Frontend: Render LLM admin panel
  User->>Frontend: Click LLM settings
  Frontend->>API: GET /manage/llm
  API->>AuthMiddleware: Validate request
  AuthMiddleware->>PermissionEngine: Check MANAGE_LLMS
  PermissionEngine-->>AuthMiddleware: Permission granted
  AuthMiddleware-->>API: Proceed
  API->>Database: Fetch LLM configs
  Database-->>API: LLM list
  API-->>Frontend: LLM data
  Frontend-->>User: Display LLM settings

Loading

Dig Deeper With Commands

• /review <file-path> <function-optional>
• /chat <file-path> "<question>"
• /roast <file-path>

Runs only when explicitly triggered.