From 409f7007cf509e203dc1ad7e953d3d305abb0caa Mon Sep 17 00:00:00 2001 From: rustmailer Date: Tue, 30 Dec 2025 15:34:07 +0800 Subject: [PATCH] Created Permissions and Multi-User System (markdown) --- Permissions-and-Multi‐User-System.md | 93 ++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 Permissions-and-Multi‐User-System.md diff --git a/Permissions-and-Multi‐User-System.md b/Permissions-and-Multi‐User-System.md new file mode 100644 index 0000000..ba53652 --- /dev/null +++ b/Permissions-and-Multi‐User-System.md @@ -0,0 +1,93 @@ +# Bichon v0.2.0 User Permissions & RBAC Guide + +Starting from version 0.2.0, Bichon introduces a comprehensive **Multi-user management** system and **Role-Based Access Control (RBAC)** architecture. This replaces the previous single-root-account model. + + +## 1. Major Changes: Authentication Upgrade + +In previous versions, Bichon supported only a single `root` account, and authentication had to be explicitly enabled via parameters. + +* **Default Authentication**: Since v0.2.0, identity authentication is **enabled by default**. The `--bichon-enable-access-token` parameter is no longer required. +* **Built-in Administrator**: The system initializes with a default `admin` account. + * **Default Username**: `admin` + * **Default Password**: `admin@bichon` +* **Security & Constraints**: + * The `admin` account's role is fixed and cannot be changed. + * Built-in roles and the default `admin` user **cannot be deleted**. + * All other profile information for the `admin` account (e.g., password) can be modified. + + + +## 2. Role-Based Access Control (RBAC) Architecture + +The permission model is divided into two dimensions: **Global System Roles** (what a user can do in the system) and **Account-Specific Roles** (what a user can do with a specific email account). + + + +### 2.1 Built-in Roles + +Bichon provides 5 predefined roles. Roles are collections of permissions categorized into **Global** and **Account** types. + +| Role Name | Type | Description | Core Scope | +| :--- | :--- | :--- | :--- | +| **Admin** | Global | Super Administrator | Full system access, user management, and access to **all** data. | +| **Manager** | Global | Operations Manager | Can manage users and connect new email accounts. | +| **Member** | Global | Regular Member | Basic platform access. Can log in but has no admin privileges. | +| **AccountManager** | Account | Account Owner | Full control over a **specifically authorized** email account. | +| **AccountViewer** | Account | Account Observer | Read-only access to a **specifically authorized** email account. | + +> **Authorization Logic**: In Bichon, the "Email Account" is the primary resource. When an account is created, the owner or an Admin can grant access to other users by assigning them a specific **Account Role** via an ACL (Access Control List). + + + +## 3. Detailed Permission List + +### 3.1 Global Permissions (System-Wide) +These determine the user's capabilities across the entire platform. + +| Permission Key | Description | Built-in Roles | +| :--- | :--- | :--- | +| `system:root` | Full system access and core configuration. | Admin | +| `user:manage` | Create, update, and delete users and custom roles. | Admin | +| `user:view` | Read-only access to the user list and profiles. | Admin, Manager | +| `token:manage` | View and revoke all active API Access Tokens. | Admin | +| `account:create` | Connect new email accounts to the system. | Admin, Manager | +| `system:access` | Required for basic login and dashboard access. | All Roles | +| `*:all` (Suffix) | Global "ALL" overrides (e.g., `data:read:all`). | Admin | + +### 3.2 Account Permissions (Data-Scoped) +These are applied to specific email accounts during the authorization process. + +| Permission Key | Description | Built-in Roles | +| :--- | :--- | :--- | +| `account:manage` | Update settings or sync specific authorized accounts. | AccountManager | +| `account:read_details` | View status and metadata of authorized accounts. | AccountManager, Viewer | +| `data:read` | Search and read messages within authorized accounts. | AccountManager, Viewer | +| `data:manage` | Manage tags, categories, and metadata for messages. | AccountManager | +| `data:raw_download` | Download raw EML/MIME files. | AccountManager | +| `data:delete` | Permanently delete messages from authorized accounts. | AccountManager | +| `data:export:batch` | Bulk export message data from authorized accounts. | AccountManager | +| `data:import:batch` | Import EML/PST data into a target account. | AccountManager | + +## 4. Security: Access Tokens & Constraints + +Bichon differentiates between internal session management and external API integration. + +### 4.1 Token Types +| Token Type | Visibility | Management | Expiration | +| :--- | :--- | :--- | :--- | +| **WebUI Token** | Invisible to User | System-controlled | Set by `bichon_webui_token_expiration_hours` | +| **API Token** | Visible to User | User-created & Revocable | Custom expiration set at creation | + +### 4.2 User Security Attributes +Security constraints are **User Attributes**. If configured, they apply to all **API Tokens** associated with that user: + +* **Rate Limit**: Controls the maximum number of requests a user can make within a specific timeframe to prevent API abuse. +* **IP Whitelist**: Restricts API access to specific IP addresses or ranges. Requests from unauthorized IPs will be rejected even with a valid API Token. + +## 5. Best Practices + +1. **Principle of Least Privilege**: For auditors who only need to search and view emails, assign the `Member` global role and authorize specific accounts with the `AccountViewer` role. +2. **Custom Roles**: Built-in roles are immutable. If you need a specific set of permissions (e.g., a "Support" role that can only manage tags but not delete mail), you can create a **Custom Role** via the UI or API. +3. **API Security**: The old "root token" method is deprecated. Generate individual Access Tokens for users. The API will automatically enforce permissions based on the roles assigned to that specific user. +