Groups & Role-Based Access Control
Relevant source files
The following files were used as context for generating this wiki page:
The Groups and Role-Based Access Control (RBAC) system in RAGAPPv3 provides a structured framework for managing user permissions and resource access across a multi-tenant environment. The system is designed to handle users, organizations, and groups, ensuring that access to sensitive resources—such as Document Vaults—is strictly governed by assigned roles and group memberships. Sources: README.md:32-40, backend/app/models/database.py:207-290
At its core, the RBAC implementation utilizes JWT-based authentication combined with persistent database records to enforce security boundaries. Users are assigned specific roles (e.g., Superadmin, Admin, Member, Viewer) that determine their global capabilities, while Group-based access allows for granular permissioning at the Vault level. Sources: README.md:417-425, frontend/src/lib/api.ts:890-930
User Hierarchy and Roles
RAGAPPv3 defines a clear hierarchy of user roles, each with increasing levels of authority. These roles are enforced at both the API level via Pydantic model validation and the frontend through route guards. Sources: specs/security-ux-hardening/SPEC.md:80-95, qa-report.md:370-385
Defined Roles
| Role | Description |
|---|---|
| Superadmin | Full system access, including management of all users, organizations, and global settings. |
| Admin | Manages organization members, group assignments, and user roles (excluding other admins). |
| Member | Standard access to create documents, search knowledge bases, and participate in chats. |
| Viewer | Read-only access; restricted to viewing knowledge bases and searching without modification. |
Sources: README.md:417-425, backend/app/models/database.py:207-220
Organizations and Groups Architecture
The system supports multi-tenancy through an Organization and Group structure. Organizations serve as top-level containers, while Groups allow for logical clustering of users within an organization to facilitate bulk permission management. Sources: backend/app/models/database.py:222-260
Entity Relationship Diagram
The following diagram illustrates the relationships between Users, Organizations, and Groups within the database schema.
Organizational Data Structures
- Users: Stores account details, hashed passwords, and the primary system role.
- Organizations: Defines the tenant entity, including names and unique slugs.
- Groups: Logical subsets of users within an organization, used for vault-specific permissions.
- Memberships: Link tables (
org_members,group_members) manage the many-to-many relationships between these entities.
Sources: backend/app/models/database.py:207-260, frontend/src/lib/api.ts:1140-1175
Resource Access: Vault Permissions
Access to Document Vaults is the primary point of enforcement for the Groups and RBAC system. Permissions can be granted either directly to a User or indirectly via a Group. Sources: backend/app/models/database.py:292-310, frontend/src/lib/api.ts:1240-1270
Vault Permission Levels
Vault permissions are categorized into three distinct levels:
- Read: Allows viewing and searching vault contents.
- Write: Allows uploading documents and modifying existing metadata.
- Admin: Full control over the specific vault, including member management.
Sources: backend/app/models/database.py:292-310, frontend/src/lib/api.ts:890-903
Group-Vault Access Flow
The following sequence shows how the system validates access when a user attempts to interact with a vault resource.
Security and Authentication Integration
The RBAC system is tightly integrated with the application's authentication lifecycle. Security is maintained through several layers:
- JWT Verification: Access tokens carry the user's identity, which is verified against the
user_sessionsanduserstables on every request. - CSRF Protection: Mutating requests (POST, PUT, DELETE) require a valid CSRF token, preventing unauthorized actions on behalf of a user.
- Role Allowlisting: The backend enforces a strict allowlist for roles in API payloads (e.g., ensuring a message role is only
userorassistant).
Sources: frontend/src/lib/api.ts:25-100, specs/security-ux-hardening/SPEC.md:40-55, backend/app/models/database.py:262-280
Core Database Schema (SQL)
-- Vault group access table: group-based access to vaults
CREATE TABLE IF NOT EXISTS vault_group_access (
id INTEGER PRIMARY KEY AUTOINCREMENT,
vault_id INTEGER NOT NULL,
group_id INTEGER NOT NULL,
permission TEXT NOT NULL DEFAULT 'read' CHECK (permission IN ('read','write','admin')),
granted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (vault_id) REFERENCES vaults(id) ON DELETE CASCADE,
FOREIGN KEY (group_id) REFERENCES groups(id) ON DELETE CASCADE
);
Sources: backend/app/models/database.py:301-310
Conclusion
The Groups and RBAC system provides the necessary security infrastructure to scale RAGAPPv3 from a single-user tool to an enterprise-grade multi-tenant platform. By separating global roles from resource-specific group permissions, the project ensures that knowledge remains secure and accessible only to the appropriate stakeholders. Sources: README.md:15-30, qa-report.md:15-25