From cb39cc90cb50e435eb85a18fc15802d028ec9891 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 9 May 2026 23:51:52 +0200 Subject: [PATCH] Docs/clarify bypass admin access control (#8) --- docs/reference/env-configuration.mdx | 33 ++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/reference/env-configuration.mdx b/docs/reference/env-configuration.mdx index bf92d1fe..d2f2f3b1 100644 --- a/docs/reference/env-configuration.mdx +++ b/docs/reference/env-configuration.mdx @@ -362,29 +362,54 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Description: Sets a webhook for integration with Discord/Slack/Microsoft Teams. - Persistence: This environment variable is a `PersistentConfig` variable. +:::note Admin posture toggles vs. security boundaries + +The `ENABLE_ADMIN_*` and `BYPASS_ADMIN_ACCESS_CONTROL` toggles in this section control what the admin sees and does **through Open WebUI's admin product surfaces** (admin panel pages, the chat model selector, workspace lists, the export action). They do **not** establish a security boundary against the admin themselves. + +Open WebUI is single-tenant by architecture and the `admin` role is root-equivalent on the deployment by deliberate design. Admins inherently retain unconstrained access to all data via direct database access, environment-variable inspection, server access, admin-only **Functions** (which execute arbitrary Python at module-import inside the application process), and **Tools** with the `workspace.tools` permission (which the admin can grant to themselves and which run `exec()` on the server). + +These toggles are appropriate for: + +- **Performance** — keeping admin-facing list/selector surfaces fast on large multi-user deployments where loading every user's items is a hard performance problem. +- **UI clutter reduction** — keeping those same surfaces usable when populated with thousands of items from other users. +- **Compliance posture** — meeting requirements (especially in jurisdictions with stronger labour-protection law, e.g. DE / AT / EU) that admins not be *casually* presented with other users' data, even though they remain technically able to reach it via the routes above. + +These toggles are **not** appropriate for: + +- Cross-tenant data isolation between admins. There is no cryptographic per-tenant isolation, no multi-database split, and no per-admin scope on the underlying data store. For genuine tenant separation, the supported pattern is **separate Open WebUI instances per tenant**. +- A security boundary against an admin who is determined to read data they aren't shown in their UI surfaces. + +Treat anything in this cluster as *what the admin sees and does in the product UI and API*, not *what the admin technically can reach on the deployment*. + +::: + #### `ENABLE_ADMIN_EXPORT` - Type: `bool` - Default: `True` -- Description: Controls whether admins can export data, chats and the database in the admin panel. Database exports only work for SQLite databases for now. +- Description: Controls whether the admin-panel **export** action is available (data, chats, and database export). When disabled, the export endpoints reject requests. Database exports only work for SQLite databases for now. Note that admin retains the underlying ability to dump the database directly via deployment access — this toggle controls the in-product export surface, see the admin-posture-toggles note above. Requires a restart to take effect. #### `ENABLE_ADMIN_CHAT_ACCESS` - Type: `bool` - Default: `True` -- Description: Enables admin users to directly access the chats of other users. When disabled, admins can no longer accesss user's chats in the admin panel. If you disable this, consider disabling `ENABLE_ADMIN_EXPORT` too, if you are using SQLite, as the exports also contain user chats. +- Description: Controls whether the admin-panel **other-users-chats** access surface is available. When disabled, admins can no longer access other users' chats in the admin panel and the corresponding endpoints reject the request. If you disable this, consider also disabling `ENABLE_ADMIN_EXPORT` (especially on SQLite), since exports include user chats and would re-open the same data on a different surface. Note that admin retains underlying database access regardless — this toggle controls the in-product surface, see the admin-posture-toggles note above. #### `ENABLE_ADMIN_ANALYTICS` - Type: `bool` - Default: `True` -- Description: Controls whether the **Analytics** tab is visible and accessible in the admin panel. When set to `False`, the analytics API router is not mounted and the tab is hidden from the admin navigation. Useful for deployments where analytics data collection or display is not desired. Requires a restart to take effect. +- Description: Controls whether the admin-panel **Analytics** tab is visible and the analytics API router is mounted. When set to `False`, the tab is hidden and the corresponding endpoints are not registered. Disabling does not stop the underlying data being collected, and admin retains the ability to query that data directly from the database — this toggle controls the in-product surface, see the admin-posture-toggles note above. Requires a restart to take effect. #### `BYPASS_ADMIN_ACCESS_CONTROL` - Type: `bool` - Default: `True` -- Description: When disabled, admin users are treated like regular users for workspace access (models, knowledge, prompts, tools, and notes) and only see items they have **explicit permission to access** through the existing access control system. This also applies to the visibility of models in the model selector - admins will be treated as regular users: base models and custom models they do not have **explicit permission to access**, will be hidden. If set to `True` (Default), admins have access to **all created items** in the workspace area (including other users' notes) and all models in the model selector, **regardless of access permissions**. This environment variable deprecates `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS`. If you are still using `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS` you should switch to `BYPASS_ADMIN_ACCESS_CONTROL`. +- Description: Controls whether admin users see other users' workspace items in **list and selector UI surfaces** (workspace tabs for models / knowledge / prompts / tools / notes / skills, the chat model selector, the file browser list, etc.). When set to `True` (default), those surfaces show every item from every user — convenient for single-admin / small-team deployments. When set to `False`, those same surfaces show only the admin's own items plus items explicitly shared with them, matching what a regular user would see. + + Per-id direct-access endpoints (`GET /api/v1//id/{id}` and the corresponding update / delete / access-update routes) are **intentionally not gated** by this flag and were never designed to be — gating them would protect against nothing the admin couldn't trivially do via the database query they used to obtain the resource ID in the first place, while breaking legitimate flows where an admin operates on a known item ID. See the admin-posture-toggles note above for the full architectural reasoning. + + This environment variable deprecates `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS`. If you are still using `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS`, switch to `BYPASS_ADMIN_ACCESS_CONTROL`. #### `ENABLE_USER_WEBHOOKS`