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.