[mirror] feat(permissions): migrate admin endpoints and UI to group-based permission checks

[yashwant86]

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

---

Summary by MergeMonkey

• Feature Drops:
  • Migrates admin endpoints from role-based to group-based permission checks using Permission enum.
  • Adds group-based access control for admin panel operations (connectors, document sets, LLMs, etc.).
  • Introduces permission-gated endpoints with require_permission() dependency for fine-grained access.
• Improvements:
  • Fixes error handling in EE cc_pair endpoints to use OnyxError with proper error codes instead of HTTPException.
  • Corrects HTTP status code mapping (400→INSUFFICIENT_PERMISSIONS, CONFLICT→CONFLICT, 500→INTERNAL_ERROR).
• Housekeeping:
  • Removes legacy role-based permission checks and replaces with group-based Permission system.
  • Deletes obsolete permission test files (test_cc_pair_permissions.py, test_connector_permissions.py, etc.).
  • Removes unused UserRole.LIMITED, SLACK_USER, EXT_PERM_USER role handling in favor of group-based model.
  • Adds database migration to make user.role nullable.
  • Refactors test utilities to use new permission-based access patterns.

[bot-mergemonkey]

⚡ Risk Assessment — CRITICAL · ~45 min review

Focus areas: Permission dependency injection and error handling · User role nullable migration and group-based access · Deleted endpoints (set-user-role, get-user-role) impact · Frontend permission checks and removed role UI components

Assessment: Migrates admin endpoints from role-based to group-based permission checks; removes user role editing endpoints.

Walkthrough

User requests an admin operation (e.g., create connector). FastAPI dependency injection calls require_permission(Permission.FULL_ADMIN_PANEL_ACCESS), which fetches the user's effective permissions from their group memberships. If user lacks the permission, a 403 Forbidden is returned. If authorized, the endpoint executes and returns the result. Legacy role-based checks (current_curator_or_admin_user) are replaced throughout.

Changes

Files	Summary
EE CC Pair Error Handling backend/ee/onyx/server/documents/cc_pair.py	Replaces HTTPException with OnyxError for permission/conflict/internal errors in sync endpoints, using proper error codes (INSUFFICIENT_PERMISSIONS, CONFLICT, INTERNAL_ERROR) instead of raw HTTP status codes.
Permission System Core backend/onyx/auth/permissions.py	Adds READ_USERS and READ_DOCUMENT_SETS permissions; auto-grants permissions to all users in Community Edition; adds _get_current_user() helper for permission dependency injection.
Admin Endpoint Permission Migration backend/onyx/server/documents/cc_pair.py backend/onyx/server/features/document_set/api.py backend/ee/onyx/server/user_group/api.py backend/onyx/server/features/mcp/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/onyx/server/api_key/api.py backend/onyx/server/manage/administrative.py backend/onyx/server/features/tool/api.py backend/onyx/server/federated/api.py backend/onyx/server/manage/discord_bot/api.py backend/onyx/server/manage/slack_bot.py backend/onyx/server/onyx_api/ingestion.py backend/ee/onyx/server/token_rate_limits/api.py	Replaces current_curator_or_admin_user dependency with require_permission(Permission.FULL_ADMIN_PANEL_ACCESS) or specific permission checks on admin endpoints.
User Role & Permission Refactoring backend/onyx/auth/users.py backend/onyx/db/auth.py backend/onyx/db/models.py backend/onyx/auth/schemas.py backend/onyx/auth/api_key.py	Refactors user role handling to support nullable role field; updates role assignment logic for API keys and user creation; removes legacy role-based permission checks.
Database & Permission Queries backend/onyx/db/persona.py 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/notification.py backend/onyx/db/user_preferences.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	Replaces role-based permission checks with group-based Permission system; removes legacy role-specific logic (CURATOR, GLOBAL_CURATOR, LIMITED, SLACK_USER, EXT_PERM_USER); simplifies queries to use has_permission() and get_effective_permissions().
User Management API backend/onyx/server/manage/users.py	Removes set-user-role and get-user-role endpoints; updates user snapshot serialization to include is_admin flag; refactors user counts by role to use new permission model.
Error Handling & Codes backend/onyx/error_handling/error_codes.py	Adds BAD_REQUEST and DOCUMENT_SET_NOT_FOUND error codes for consistent error handling across endpoints.
Database Migration backend/alembic/versions/c8e316473aaa_make_user_role_nullable.py	Adds migration to make user.role column nullable, supporting transition to group-based permission model.
Test Infrastructure & Fixtures backend/tests/integration/tests/permissions/conftest.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 backend/tests/integration/conftest.py	Updates test fixtures and managers to use group-based permission model; adds helper methods for permission-based user creation and group assignment.
Permission-Based Integration Tests backend/tests/integration/tests/permissions/_access_matrix.py, test_add_agents.py, test_admin_access.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, test_file_connector_permissions.py	Adds comprehensive permission-gated endpoint tests covering ADD_AGENTS, CREATE_USER_API_KEYS, MANAGE_* operations; replaces legacy role-based tests with permission matrix validation.
Deleted Legacy Permission Tests 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_whole_curator_flow.py, test_user_role_permissions.py	Removes obsolete role-based permission tests; replaced by new permission-gated endpoint tests.
Test Utilities & Helpers backend/tests/integration/tests/api_key/test_api_key.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/query_history/test_query_history.py backend/tests/integration/tests/query_history/utils.py backend/tests/integration/tests/usergroup/test_usergroup_syncing.py backend/tests/integration/tests/users/test_slack_user_deactivation.py backend/tests/integration/tests/users/test_user_pagination.py backend/tests/integration/tests/users/test_password_signup_upgrade.py backend/tests/integration/tests/users/test_default_group_assignment.py backend/tests/integration/tests/auth/test_saml_user_conversion.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/multitenant_tests/syncing/test_search_permissions.py backend/tests/integration/tests/anonymous_user/test_anonymous_user.py backend/tests/integration/tests/chat/test_chat_session_access.py backend/tests/integration/tests/scim/test_scim_groups.py backend/tests/integration/tests/scim/test_scim_users.py backend/tests/integration/tests/llm_provider/test_llm_provider.py backend/tests/external_dependency_unit/db/test_user_account_type.py backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.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_called.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/external_dependency_unit/conftest.py backend/tests/daily/conftest.py backend/tests/unit/onyx/auth/test_jwt_provisioning.py backend/tests/unit/onyx/auth/test_user_registration.py backend/tests/unit/onyx/auth/test_permissions.py backend/tests/unit/onyx/server/scim/conftest.py backend/tests/unit/onyx/server/test_full_user_snapshot.py	Updates test utilities to use new permission-based access patterns; refactors user creation and API key setup to leverage group-based permissions.
Frontend Admin Routes & Permissions web/src/lib/admin-routes.ts, admin-sidebar-utils.ts	Updates admin route permission requirements from 'admin' role to specific Permission enum values (manage:llms, manage:connectors, etc.).
Frontend User & Permission Types web/src/lib/types.ts, permissions.ts	Adds is_admin flag to User type; updates UserRole enum to remove LIMITED/SLACK_USER/EXT_PERM_USER; refactors Permission type to use string literals for permission checks.
Frontend User Provider & Auth web/src/providers/UserProvider.tsx web/src/lib/auth/requireAuth.ts	Updates UserProvider to derive isAdmin from user.role === ADMIN; refactors auth checks to use permission-based access control via groups.
Frontend Admin Users Management 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/hooks/useAdminUsers.ts web/src/hooks/useUserCounts.ts	Removes user role editing UI; replaces with account type display; updates user filtering and counts to use new permission model; removes setUserRole API call.
Frontend Service Accounts & API Keys web/src/refresh-pages/admin/ServiceAccountsPage/index.tsx, ApiKeyFormModal.tsx, interfaces.ts	Removes API key role change functionality; updates form to use group-based permissions instead of direct role assignment.
Frontend Groups Management web/src/refresh-pages/admin/GroupsPage/shared.tsx, useGroupMemberCandidates.ts, EditGroupPage.tsx, CreateGroupPage.tsx, GroupPermissionsSection.tsx, interfaces.ts	Adds permission management UI for groups; updates member candidate selection to include API keys; refactors permission section for bulk permission assignment.
Frontend Document Sets & Connectors web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx web/src/app/admin/connector/[ccPairId]/page.tsx web/src/components/admin/connectors/AccessTypeGroupSelector.tsx web/src/components/IsPublicGroupSelector.tsx	Updates curator role checks to use permission-based access; refactors group selector logic for permission-aware filtering.
Frontend Agents & Tools web/src/refresh-pages/AgentsNavigationPage.tsx web/src/refresh-pages/admin/AgentsPage/AgentRowActions.tsx web/src/refresh-pages/AgentEditorPage.tsx web/src/sections/cards/AgentCard.tsx web/src/sections/modals/ShareAgentModal.tsx	Updates agent creation and editing to use permission-based access checks instead of role-based; refactors curator/admin checks.
Frontend Settings & PAT web/src/refresh-pages/SettingsPage.tsx web/src/sections/sidebar/AppSidebar.tsx web/src/sections/sidebar/CreateConnectorSidebar.tsx web/src/sections/onboarding/OnboardingFlow.tsx web/src/sections/modals/llmConfig/shared.tsx web/src/app/craft/v1/configure/page.tsx web/src/refresh-pages/AppPage.tsx	Updates permission checks throughout UI to use hasPermission() helper; refactors curator/admin role checks to permission-based access.
Frontend Component Utilities web/src/components/ConnectorMultiSelect.tsx web/src/components/GenericMultiSelect.tsx web/src/refresh-components/popovers/ActionsPopover/index.tsx web/src/app/admin/ClientLayout.tsx web/src/app/admin/ClientLayout.test.tsx	Adds test IDs for search inputs; updates permission checks in action popovers; adds ClientLayout test for permission-based routing.
Frontend Deleted Components web/src/components/admin/users/SignedUpUserTable.tsx web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx web/src/components/admin/users/buttons/UserRoleDropdown.tsx	Removes user role UI components; replaced by account type display and group-based permission management.
E2E Tests & Utilities 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 gating; updates API client to use new setUserRole endpoint; adds permission group cleanup utilities.

Sequence Diagram

sequenceDiagram
    participant Client
    participant FastAPI
    participant PermissionDep as require_permission()
    participant UserGroups as User Groups DB
    participant Endpoint
    Client->>FastAPI: POST /admin/connectors
    FastAPI->>PermissionDep: Resolve dependency
    PermissionDep->>UserGroups: Fetch user's groups
    UserGroups-->>PermissionDep: Return group list
    PermissionDep->>PermissionDep: Check if any group has FULL_ADMIN_PANEL_ACCESS
    alt User has permission
        PermissionDep-->>FastAPI: Return user
        FastAPI->>Endpoint: Call endpoint
        Endpoint-->>Client: 200 OK + result
    else User lacks permission
        PermissionDep-->>FastAPI: Raise HTTPException 403
        FastAPI-->>Client: 403 Forbidden
    end

Loading

Dig Deeper With Commands

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

Runs only when explicitly triggered.