External/bichon
1
0
Fork 0
mirror of https://github.com/rustmailer/bichon.git synced 2026-08-03 07:48:34 +02:00
Code Issues Packages Projects Releases Wiki Activity

Created Permissions and Multi-User System (markdown)

rustmailer
2025-12-30 15:34:07 +08:00
parent 0b200d78d4
commit 409f7007cf
1 changed files with 93 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Permissions-and-Multi‐User-System.md
+93
@@ -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.