khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-01-04 02:36:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #905 from Classic298/dev

Browse Source
This commit is contained in:
Classic298
2025-12-20 20:15:45 +01:00
committed by GitHub
parent 6403765d00 d403cabfa0
commit edd98cb979
4 changed files with 248 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/features/rbac/groups.md
View File

@@ -3,75 +3,85 @@ sidebar_position: 3
title: "Groups"
---
Groups allow administrators to
- assign permissions to multiple users at once, simplifying access management
- limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups
- Specify access to a resource for a group to either "read" or "write" (write access implies read)
:::info
Note that the permissions model is permissive. If a user is a member of two groups that define different permissions for a resource, the most permissive permission is applied.
Groups in Open WebUI are a powerful mechanism for organizing users and managing access control at scale. They serve two primary purposes:
1. **Permission Management:** Assigning granular permissions to multiple users efficiently.
2. **Resource Access Control:** controlling who can access specific private resources (Models, Knowledge Bases, Tools).
:::info Permission Merging Logic
Open WebUI permissions are **additive** (Union-based).
* If a user is in multiple groups, they receive the **superset** of all permissions.
* If *Group A* allows "Image Generation" and *Group B* does not, a user in both groups **WILL** have access to Image Generation.
* "Deny" permissions do not exist; you can only "Grant" permissions.
:::
## Group Management
Groups can be managed in the **Admin Panel > Groups** section.
### Group Configuration
When creating or editing a group, you can configure its visibility in the system:
* **Allow Group Sharing**: (Default: **On**)
* **Enabled**: The group will appear in the "Access Control" dropdowns when users share Chat items, Models, or Knowledge lists. Use this for teams or project groups that need to collaborate on content.
* **Disabled**: The group is **hidden** from sharing menus. This is designed for groups used solely for **RBAC Permission assignment** (e.g., granting "Image Generation" rights). Hiding these prevents the Sharing UI from becoming cluttered with technical/administrative groups.
:::tip Strategy: Permission Groups vs. Sharing Groups
To maintain a clean and manageable system, consider separating your groups into two distinct categories using a naming scheme:
1. **Permission Groups** (e.g., prefix `[Perms]`, `Role-`, or `P-`)
* **Purpose**: Exclusively for granting features (e.g., `[Perms] Image Gen`, `[Perms] Web Search`).
* **Config**: Disable **Allow Group Sharing**.
* **Result**: Users get the features they need, but these technical groups don't clutter the "Share" menu.
2. **Sharing Groups** (e.g., prefix `Team-`, `Project-`, or normal names)
* **Purpose**: Exclusively for organizing people (e.g., `Marketing`, `Engineering`, `Team Alpha`) to share resources.
* **Config**: Enable **Allow Group Sharing**.
* **Best Practice**: **Disable all permissions** in these groups.
* Rely on *Global Default Permissions* (or separate *Permission Groups*) for feature rights.
* *Why?* This ensures painless **Permission Revocation**. If you decide to disable a feature (e.g., "Web Search") globally, it will instantly take effect for everyone. If your Sharing Groups had "Web Search" enabled, you would have to manually update every single group to remove the right, as the Group's `True` status would override the Global `False`. Keep functional groups clean to maintain Global control.
:::
### Creation Methods
* **Manual Creation:** Administrators can manually create groups and add users via the UI.
* **OAuth Synchronization:** If `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled, groups can be synced from your OAuth provider (e.g., Keycloak, Azure AD).
* **Auto-Creation:** With `ENABLE_OAUTH_GROUP_CREATION`, groups that don't exist locally will be created automatically.
* **Membership Sync:** Users are strictly added/removed from groups to match their OAuth claims.
### Group Structure
A group definition typically includes:
* **Name**: The display name of the group.
* **Description**: Purpose of the group.
* **Permissions**: A detailed JSON object overriding default user permissions (see [Permissions](./permissions.md)).
* **Members**: A list of User IDs belonging to the group.
Each group in Open WebUI contains:
## Assigning Permissions to Groups
- A unique identifier
- Name and description
- Owner/creator reference
- List of member user IDs
- Permission configuration
- Additional metadata
When editing a group, you can toggle specific permissions.
* **Default State**: By default, a group grants *no* extra permissions; members rely on the global defaults.
* **Granting Access**: Toggling a permission (e.g., "Web Search") to **ON** for a group means all members get that feature, even if it's disabled globally.
### Group Management
## Resource Access (RBAC)
Groups can be:
You can restrict access to specific objects (like a proprietary Model or sensitive Knowledge Base) using Groups.
- **Created manually** by administrators through the user interface
- **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled
- **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION`
are enabled
1. **Tag the Resource**: When creating/editing a Model or Knowledge Base, set its visibility to **Private** or **Restricted**.
2. **Grant Access**: Select the specific **Groups** (or individual users) that should have "Read" or "Write" access.
### OAuth Group Integration
When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims:
- Users are added to Open WebUI groups that match their OAuth claims
- Users are removed from groups not present in their OAuth claims
- With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically
created
## Group Permissions
Groups can be used to make sets of permissions available to users. For example, a group could be created for "Data
Scientists" that has read and write access to all models, knowledge bases, and tools.
## Resource Access Control for Groups
Open WebUI implements granular access control for resources like models, knowledge bases, prompts, and tools. Access can
be controlled at both the user and group level.
To enable access control for a resource, set its access to "private" and then open access to specific groups.
### Access Control Structure
Resources like knowledge bases use an access control structure that specifies read and write permissions for both users
and groups:
### Access Control Object
At a deeper level, resources store an access control list (ACL) looking like this:
```json
{
"read": {
"group_ids": ["group_id1", "group_id2"],
"user_ids": ["user_id1", "user_id2"]
"group_ids": ["marketing-team-id", "admins-id"],
"user_ids": []
},
"write": {
"group_ids": ["group_id1", "group_id2"],
"user_ids": ["user_id1", "user_id2"]
"group_ids": ["admins-id"],
"user_ids": ["editor-user-id"]
}
}
```
This structure allows for precise control over who can view and modify specific resources.
* **Read**: Users can view and use the resource.
* **Write**: Users can update or delete the resource.

29
docs/features/rbac/index.mdx
View File

@@ -3,9 +3,28 @@ sidebar_position: 100
title: "Role-Based Access Control (RBAC)"
---
## Access Control
- [‍🔑 Roles](./roles.md) - The roles defined in Open WebUI
- [‍🔐 Groups](./groups.md) - Setup groups of users to share access to resources
- [🔒 Permissions](./permissions.md) - Configure access controls and feature availability
Open WebUI implements a flexible and secure **Role-Based Access Control (RBAC)** system. This system allows administrators to precisely manage user capabilities and access to resources through three interconnected layers:
Roles, groups and permissions are designed to work together to provide a finegrained model for controlling user access to individual resources.
1. [**Roles**](./roles.md): The high-level user type (Admin, User, Pending). This defines the baseline trust level.
2. [**Permissions**](./permissions.md): Granular feature flags (e.g., "Can Delete Chats", "Can Use Web Search").
3. [**Groups**](./groups.md): The mechanism for organizing users, granting additional permissions, and managing shared access to resources (ACLs).
:::info Key Concept: Additive Permissions
The security model is **Additive**. Users start with their default rights, and Group memberships **add** capabilities. A user effectively has the *union* of all rights granted by their Roles and Groups.
:::
## Documentation Guide
* [‍🔑 **Roles**](./roles.md)
* Understand the difference between Admins and Users.
* Learn about Admin limitations and security/privacy configurations.
* [🔒 **Permissions**](./permissions.md)
* Explore the full list of available permission toggles.
* Understand granular controls for Chat, Workspace, and Features.
* **Security Tip**: Learn how properly configured Global Defaults protect your system.
* [‍🔐 **Groups**](./groups.md)
* Learn how to structure teams and projects.
* **Strategy**: Distinguish between "Permission Groups" (for rights) and "Sharing Groups" (for access).
* Manage Access Control Lists (ACLs) for private Models and Knowledge.

153
docs/features/rbac/permissions.md
View File

@@ -3,72 +3,135 @@ sidebar_position: 3
title: "Permissions"
---
The `Permissions` section of the `Workspace` within Open WebUI allows administrators to configure access controls and feature availability for users. This powerful system enables fine-grained control over what users can access and modify within the application.
Administrators can manage permissions in the following ways:
Administrators can manage permissions in three primary ways:
1. **Global Default Permissions:** Set the baseline permissions for all user accounts via the Admin Panel.
2. **Group Permissions:** Create groups with specific permission overrides (e.g., a "Power Users" group with access to image generation).
3. **Role-Based Access:** The `Pending` role has no access, `Admin` has full access, and `User` is subject to the permission system.
1. **User Interface:** The Workspace's Permissions section provides a graphical interface for configuring permissions.
2. **Environment Variables:** Permissions can be set using environment variables, which are stored as `PersistentConfig` variables.
3. **Group Management:** Assigning users to groups with predefined permissions.
:::info Permission Logic
Permissions in Open WebUI are **additive**.
* A user's effective permissions are the combination of **Global Defaults** and all their **Group Memberships**.
* **True takes precedence over False**: If *any* source (Global Default or *any* single Group) grants a permission, the user **will** have that permission.
* **No "Deny" ability**: You cannot use a specific group to "take away" a permission that is granted by another group or by the global defaults. To restrict a feature, it must be disabled in the Global Defaults *and* disabled in **all** groups the user belongs to.
:::
## Workspace Permissions
:::tip Best Practice: Principle of Least Privilege
Since permissions are **additive**, the recommended security strategy is to start with **Restriction**:
1. **minimize Global Default Permissions**: Configure the default permissions (Admin > Settings > Users) to include *only* what absolutely every user should have.
2. **Grant via Groups**: Create specific groups (e.g., "Creators", "Power Users") to explicitly **grant** advanced features like Image Generation or File Uploads.
Workspace permissions control access to core components of the Open WebUI platform:
This approach ensures that new users don't accidentally get access to sensitive features, while allowing you to easily promote users by simply adding them to the relevant group.
:::
- **Models Access**: Toggle to allow users to access and manage custom models. (Environment variable: `USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS`)
- **Knowledge Access**: Toggle to allow users to access and manage knowledge bases. (Environment variable: `USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS`)
- **Prompts Access**: Toggle to allow users to access and manage saved prompts. (Environment variable: `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS`)
- **Tools Access**: Toggle to allow users to access and manage tools. (Environment variable: `USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS`) *Note: Enabling this gives users the ability to upload arbitrary code to the server.*
## Permission Categories
## Chat Permissions
Permissions are organized into four main categories: **Workspace**, **Sharing**, **Chat**, and **Features**.
Chat permissions determine what actions users can perform within chat conversations:
### 1. Workspace Permissions
Controls access to the "Workspace" section where users create and manage resources.
Some permissions are **dependent** on others (e.g., you cannot import models if you cannot access the Models workspace).
- **Allow Chat Controls**: Toggle to enable access to chat control options.
- **Allow File Upload**: Toggle to permit users to upload files during chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_FILE_UPLOAD`)
- **Allow Chat Delete**: Toggle to permit users to delete chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_DELETE`)
- **Allow Chat Edit**: Toggle to permit users to edit messages in chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_EDIT`)
- **Allow Temporary Chat**: Toggle to permit users to create temporary chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_TEMPORARY`)
| Permission | Description |
| :--- | :--- |
| **Models Access** | **(Parent)** Access the **Models** workspace to create or edit custom models. |
| **Models Import** | *(Requires Models Access)* Ability to import models from JSON/files. |
| **Models Export** | *(Requires Models Access)* Ability to export models to files. |
| **Knowledge Access** | Access the **Knowledge** workspace to manage knowledge bases. |
| **Prompts Access** | **(Parent)** Access the **Prompts** workspace to manage custom system prompts. |
| **Prompts Import** | *(Requires Prompts Access)* Ability to import prompts. |
| **Prompts Export** | *(Requires Prompts Access)* Ability to export prompts. |
| **Tools Access** | **(Parent)** Access the **Tools** workspace to manage functions/tools. |
| **Tools Import** | *(Requires Tools Access)* Ability to import tools. |
| **Tools Export** | *(Requires Tools Access)* Ability to export tools. |
## Features Permissions
### 2. Sharing Permissions
Controls what users can share with the community or make public.
Features permissions control access to specialized capabilities within Open WebUI:
| Permission | Description |
| :--- | :--- |
| **Share Models** | **(Parent)** Ability to share models (make them accessible to others). |
| **Public Models** | *(Requires Share Models)* Ability to make models publicly discoverable. |
| **Share Knowledge** | **(Parent)** Ability to share knowledge bases. |
| **Public Knowledge** | *(Requires Share Knowledge)* Ability to make knowledge bases public. |
| **Share Prompts** | **(Parent)** Ability to share prompts. |
| **Public Prompts** | *(Requires Share Prompts)* Ability to make prompts public. |
| **Share Tools** | **(Parent)** Ability to share tools. |
| **Public Tools** | *(Requires Share Tools)* Ability to make tools public. |
| **Share Notes** | **(Parent)** Ability to share Notes. |
| **Public Notes** | *(Requires Share Notes)* Ability to make Notes public. |
- **Web Search**: Toggle to allow users to perform web searches during chat sessions. (Environment variable: `ENABLE_WEB_SEARCH`)
- **Image Generation**: Toggle to allow users to generate images. (Environment variable: `ENABLE_IMAGE_GENERATION`)
- **Code Interpreter**: Toggle to allow users to use the code interpreter feature. (Environment variable: `USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`)
- **Direct Tool Servers**: Toggle to allow users to connect directly to tool servers. (Environment variable: `USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS`)
### 3. Chat Permissions
Controls the features available to the user inside the chat interface.
## Default Permission Settings
| Permission | Description |
| :--- | :--- |
| **Chat Controls** | **(Parent)** Access to advanced chat settings. Required for Valves, System Prompt, and Parameters. |
| **Model Valves** | *(Requires Chat Controls)* Access to model-specific configuration "valves". |
| **System Prompt** | *(Requires Chat Controls)* Ability to edit the system prompt for a conversation. |
| **Parameters** | *(Requires Chat Controls)* Ability to adjust LLM parameters (e.g., temperature, top_k). |
| **File Upload** | Ability to upload files to the chat. |
| **Delete Chat** | Ability to delete entire chat conversations. |
| **Delete Message** | Ability to delete individual messages. |
| **Edit Message** | Ability to edit messages. |
| **Continue Response** | Ability to use the "Continue" feature for truncated responses. |
| **Regenerate Response**| Ability to regenerate an AI response. |
| **Rate Response** | Ability to thumbs up/down responses. |
| **Share Chat** | Ability to generate a share link for a chat. |
| **Export Chat** | Ability to export chat history. |
| **Speech-to-Text (STT)**| Ability to use voice input. |
| **Text-to-Speech (TTS)**| Ability to use voice output. |
| **Audio Call** | Ability to use the real-time audio call feature. |
| **Multiple Models** | Ability to select multiple models for a simultaneous response. |
| **Temporary Chat** | **(Parent)** Ability to toggle "Temporary Chat" (incognito mode/history off). |
| **Enforced Temporary** | *(Requires Temporary Chat)* **Restricts** the user to *always* use temporary chat (history disabled). |
By default, Open WebUI applies the following permission settings:
### 4. Features Permissions
Controls access to broad platform capabilities.
**Workspace Permissions**:
| Permission | Description |
| :--- | :--- |
| **API Keys** | Ability to generate Personal Access Tokens (API Keys) in User Settings. |
| **Notes** | Access to the "Notes" feature. |
| **Channels** | Access to the "Channels" feature. |
| **Folders** | Ability to use folders for organizing chats. |
| **Web Search** | Ability to use Web Search integration. |
| **Image Generation** | Ability to use Image Generation tools. |
| **Code Interpreter** | Ability to use the Python Code Interpreter. |
| **Direct Tool Servers** | Ability to connect to custom Tool Servers in settings. |
- Models Access: Disabled (`USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS=False`)
- Knowledge Access: Disabled (`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS=False`)
- Prompts Access: Disabled (`USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS=False`)
- Tools Access: Disabled (`USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS=False`)
:::warning API Keys Security & Admin Access
The **API Keys** permission (`features.api_keys`) is treated with higher security and works differently than other features:
**Chat Permissions**:
1. **Global Toggle Required**:
The feature must be enabled globally in **Admin Settings > General > Enable API Keys**. If this is off, *no one* (not even groups with permission) can generate keys.
- Allow Chat Controls: Enabled
- Allow File Upload: Enabled (`USER_PERMISSIONS_CHAT_FILE_UPLOAD=True`)
- Allow Chat Delete: Enabled (`USER_PERMISSIONS_CHAT_DELETE=True`)
- Allow Chat Edit: Enabled (`USER_PERMISSIONS_CHAT_EDIT=True`)
- Allow Temporary Chat: Enabled (`USER_PERMISSIONS_CHAT_TEMPORARY=True`)
2. **Permission Check Required**:
In addition to the global toggle, the user must look for the permission `features.api_keys`.
**Features Permissions**:
3. **Admins Are Not Exempt**:
Unlike most other permissions which Admins bypass, **Administrators require this permission** to generate API keys. They are subject to the same checks as regular users for this critical security feature.
- Web Search: Enabled (`ENABLE_WEB_SEARCH=True`)
- Image Generation: Enabled (`ENABLE_IMAGE_GENERATION=True`)
- Code Interpreter: Enabled (`USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`)
- Direct Tool Servers: Disabled (`USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS=False`)
Administrators can change the default permissions in the user interface under "users" in the admin panel.
**Recommended "Least Privilege" Configuration**:
* **Step 1**: Disable `API Keys` in **Global Default Permissions** (so new users don't get it by default).
* **Step 2**: Create a specific Group (e.g., `🔐 API Users`) with `API Keys` enabled.
* **Step 3**: Manually add specific users—including yourself/Admins—to this group to grant access.
:::
## Managing Permissions
Administrators can adjust these permissions through the user interface or by setting the corresponding environment variables in the configuration. All permission-related environment variables are marked as `PersistentConfig` variables, meaning they are stored internally after the first launch and can be managed through the Open WebUI interface.
Administrators can adjust these permissions through the **Admin Panel > Settings > Users > Permissions**.
This flexibility allows organizations to implement security policies while still providing users with the tools they need. For more detailed information about environment variables related to permissions, see the [Environment Variable Configuration](https://docs.openwebui.com/getting-started/env-configuration#workspace-permissions) documentation.
* **Default Permissions**: Changing settings here applies to all users immediately, unless they are granted the permission via a Group.
* **Group Permissions**: Go to **Admin Panel > Groups**, verify a group, and edit its permissions. Group permissions override the default (e.g., if "Image Generation" is disabled by default, a "Creative User" group can have it enabled).
### Environment Variables
While the UI is the recommended way to manage permissions, initial defaults can be set via environment variables. These are typically prefixed with `USER_PERMISSIONS_`.
* `ENABLE_IMAGE_GENERATION=True`
* `ENABLE_WEB_SEARCH=True`
* `USER_PERMISSIONS_CHAT_FILE_UPLOAD=True`
See the [Environment Configuration](../getting-started/env-configuration.mdx) guide for a complete list of valid variables.

106
docs/features/rbac/roles.md
View File

@@ -3,63 +3,65 @@ sidebar_position: 3
title: "Roles"
---
Open WebUI implements a structured role-based access control system with three primary user roles:
| **Role** | **Description** | **Default Creation** |
|---------------|---------------------------------------------------|----------------------------------|
| Administrator | System administrator with full control | First user account |
| Regular User | Standard user with limited permissions | Subsequent approved users |
| Pending | Unapproved user awaiting administrator activation | New registrations (configurable) |
Open WebUI defines three primary **System Roles** that determine the fundamental access level of a user account. These roles are distinct from [Groups](./groups.md) and [Permissions](./permissions.md).
### Role Assignment
| Role | Keyword | Description |
| :--- | :--- | :--- |
| **Admin** | `admin` | **Superuser**. Full control over the system. |
| **User** | `user` | **Standard User**. Subject to RBAC permissions. |
| **Pending** | `pending` | **Restricted**. No access until approved. |
- **First User:** The first account created on a new Open WebUI instance automatically receives Administrator
privileges.
- **Subsequent Users:** New user registrations are assigned a default role based on the `DEFAULT_USER_ROLE`
configuration.
## Role Details
The default role for new registrations can be configured using the `DEFAULT_USER_ROLE` environment variable:
### Administrator (`admin`)
The Admin role is designed for system maintainers.
* **Full Access**: default access to all resources and settings.
* **Management**: Can manage users, groups, and global configurations.
* **Bypass**: Bypasses most permission checks by default.
```.dotenv
DEFAULT_USER_ROLE=pending # Options: pending, user, admin
:::warning Admin Limitations & Best Practices
While Administrators generally have unrestricted access, certain system configurations can limit their capabilities for security and privacy:
* **Privacy Controls**: Environment variables like `ENABLE_ADMIN_CHAT_ACCESS=False` can prevent Admins from viewing user chats.
* **Strict Feature Checks**: Critical security features like **API Keys** (`features.api_keys`) require explicit permission, even for Admins.
* **Access Control Exceptions**: If `BYPASS_ADMIN_ACCESS_CONTROL` is disabled, Admins may require explicit permissions to access private model/knowledge resources.
For a robust security posture, we recommend including Admins in your permission schema (via Groups) rather than relying solely on the role's implicit bypasses. This ensures consistent access if bypass limitations are ever enabled.
:::
### Standard User (`user`)
This is the default functional role for team members.
* **Subject to Permissions**: Does not have implicit access. All capabilities must be granted via **Global Default Permissions** or **Group Memberships**.
* **Additive Rights**: As explained in the [Permissions](./permissions.md) section, their effective rights are the sum of all their grants.
### Pending User (`pending`)
The default state for new sign-ups (if configured) or deactivated users.
* **Zero Access**: Cannot perform any actions or see any content.
* **Approval Required**: Must be promoted to `user` or `admin` by an existing Administrator.
:::note
The `admin` role effectively has `check_permission() == True` for everything. Granular permissions (like disabling "Web Search") generally do **not** apply to admins.
:::
## Role Assignment
### Initial Setup
* **First User:** The very first account created on a fresh installation is automatically assigned the **Admin** role.
* **Subsequent Users:** New sign-ups are assigned the **Default User Role**.
### Configuration
You can control the default role for new users via the `DEFAULT_USER_ROLE` environment variable:
```bash
DEFAULT_USER_ROLE=pending
# Options: 'pending', 'user', 'admin'
```
* **pending (Recommended for public/shared instances):** New users cannot log in until an Admin explicitly activates them in the Admin Panel.
* **user:** New users get immediate access with default permissions.
* **admin:** (Use with caution) New users become full administrators.
When set to "pending", new users must be manually approved by an administrator before gaining access to the system.
## Changing Roles
Administrators can change a user's role at any time via **Admin Panel > Users**.
* Promoting a user to `admin` grants them full control.
* Demoting an admin to `user` subjects them to the permission system again.
## User Groups
Groups allow administrators to
- assign permissions to multiple users at once, simplifying access management
- limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to
specific groups
- Group access to a resource can be set as "read" or "write"
### Group Structure
Each group in Open WebUI contains:
- A unique identifier
- Name and description
- Owner/creator reference
- List of member user IDs
- Permission configuration
- Additional metadata
### Group Management
Groups can be:
- **Created manually** by administrators through the user interface
- **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled
- **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION`
are enabled
### OAuth Group Integration
When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims:
- Users are added to Open WebUI groups that match their OAuth claims
- Users are removed from groups not present in their OAuth claims
- With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically
created