Merge pull request #544 from itk-dev/feature/roles-groups-permissions-page

feat: Add pages documenting roles and groups

docs/features/workspace/groups.md

@@ -0,0 +1,74 @@
+---
+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.
+:::
+
+### 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
+
+## 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:
+
+```json
+{
+  "read": {
+    "group_ids": ["group_id1", "group_id2"],
+    "user_ids": ["user_id1", "user_id2"]
+  },
+  "write": {
+    "group_ids": ["group_id1", "group_id2"],
+    "user_ids": ["user_id1", "user_id2"]
+  }
+}
+```
+
+This structure allows for precise control over who can view and modify specific resources.

docs/features/workspace/index.mdx

@@ -5,9 +5,17 @@ title: "🖥️ Workspace"
 
 The Workspace in Open WebUI provides a comprehensive environment for managing your AI interactions and configurations. It consists of several key components:
 
+## Resources
+
 - [🤖 Models](./models.md) - Create and manage custom models tailored to specific purposes
 - [🧠 Knowledge](./knowledge.md) - Manage your knowledge bases for retrieval augmented generation
 - [📚 Prompts](./prompts.md) - Create and organize reusable prompts
-- [🔒 Permissions](./permissions.md) - Configure access controls and feature availability
 
 Each section of the Workspace is designed to give you fine-grained control over your Open WebUI experience, allowing for customization and optimization of your AI interactions.
+
+## 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
+
+Roles, groups and permissions are designed to work together to provide a finegrained model for controlling user access to individual resources. 

docs/features/workspace/permissions.md

@@ -5,6 +5,12 @@ 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:
+
+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.
+
 ## Workspace Permissions
 
 Workspace permissions control access to core components of the Open WebUI platform:
@@ -56,6 +62,8 @@ By default, Open WebUI applies the following permission settings:
 - 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.
+
 ## 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.

docs/features/workspace/roles.md

@@ -0,0 +1,64 @@
+---
+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) |
+
+### Role Assignment
+
+* **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.
+
+The default role for new registrations can be configured using the `DEFAULT_USER_ROLE` environment variable:
+
+```.dotenv
+DEFAULT_USER_ROLE=pending  # Options: pending, user, admin
+```
+
+When set to "pending", new users must be manually approved by an administrator before gaining access to the system.
+
+## 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