This document describes the Role-Based Access Control (RBAC) system implemented in the osysHome-Users plugin. It covers the available user roles, how they are assigned, stored, and how they affect access permissions throughout the application. For information about user administration operations, see Administrative Operations.

The osysHome-Users plugin implements a straightforward role-based access control system with predefined roles that define the level of access and capabilities available to each user. Roles are assigned during user creation and can be modified by administrators.

flowchart TD
    A["User Authentication"] --> B["Role Determination"]
    B --> C["Permission Evaluation"]
    C --> D["Access Control"]
    
    subgraph "User Management"
        E["UserForm.role"] --> F["User Object"]
        F --> G["role Property"]
    end
    
    B --- G

Sources: forms/UserForm.py:9, init.py:38, init.py:50

The system defines four distinct roles with increasing privileges:

These roles are hardcoded in the UserForm class and represent a hierarchical permission structure.

graph TD
    A["Available Roles"] --> B["guest"]
    A --> C["user"]
    A --> D["editor"]
    A --> E["admin"]
    
    subgraph "Permission Level"
        F["Lowest"] --- B
        G["Low"] --- C
        H["Medium"] --- D
        I["Highest"] --- E
    end

Sources: forms/UserForm.py:9

Roles are assigned to users through the user management interface. When creating a new user or editing an existing one, administrators can select one of the predefined roles from a dropdown menu.

sequenceDiagram
    participant Admin as "Administrator"
    participant UI as "User Interface"
    participant Form as "UserForm"
    participant System as "Users Plugin"
    participant DB as "User Object"
    
    Admin->>UI: Access user creation/edit
    UI->>Form: Display role selection
    Admin->>Form: Select role
    Admin->>Form: Submit form
    Form->>System: Validate submission
    System->>DB: obj.setProperty("role", form.role.data)
    DB-->>System: Confirmation
    System-->>Admin: Redirect to user list

Sources: init.py:37-39, init.py:50-51, forms/UserForm.py:9

The role value is stored as a property of the user object using the setProperty method. This ensures that the role information persists in the database and can be retrieved for permission checks.

Sources: init.py:38, init.py:50

User roles are displayed in the user listing table, allowing administrators to quickly view the permission level of each account in the system.

graph TD
    A["Users Table"] --> B["Username Column"]
    A --> C["Role Column"]
    A --> D["Home page Column"]
    A --> E["Last login Column"]
    A --> F["Actions Column"]
    
    C --> G["Display user.role value"]

Sources: templates/users.html:24

The system's roles are defined as options in the SelectField for the role attribute in the UserForm class:

role = SelectField('Role',choices=(("user","User"),("guest","Guest"), ("editor","Editor"), ("admin","Administrator")), validators=[DataRequired()])

This field is required, meaning every user must have an assigned role.

Sources: forms/UserForm.py:9

When a new user is created, the role is assigned from the form submission:

obj = addObject(form.username.data, "Users")
obj.setProperty("role", form.role.data)

Sources: init.py:37-38

Similarly, when a user is edited, the role can be updated:

obj.setProperty("role", form.role.data)

Sources: init.py:50

While the role assignment is visible in the provided code, the actual permission checking based on these roles is likely implemented in the core application. The osysHome-Users plugin focuses on the management of user roles rather than enforcing permissions.

The expected permission model based on the defined roles would be:

graph TD
    A["Permission System"] --> B["Role Check"]
    B --> C["Feature Authorization"]
    
    subgraph "Role Hierarchy"
        D["admin"] -->|"has all permissions of"| E["editor"]
        E -->|"has all permissions of"| F["user"]
        F -->|"has all permissions of"| G["guest"]
    end
    
    subgraph "Core Application"
        H["Check user.role"]
        I["Compare with required role"]
        J["Grant/Deny Access"]
    end
    
    B --- H
    H --> I
    I --> J

When working with the role-based access control system in osysHome-Users:

1. Assign Appropriate Roles: Give users the minimum role level needed for their tasks
2. Regular Audits: Periodically review user roles to ensure they remain appropriate
3. Role Consistency: Maintain consistent role assignments across related users
4. Document Custom Permissions: If extending the system with custom role-based logic, document the permissions associated with each role

The current implementation has several limitations to be aware of:

1. Fixed Role Set: The system uses a predefined set of roles without custom role creation
2. No Granular Permissions: The roles appear to be hierarchical rather than offering granular permission assignment
3. No Role Inheritance: Role inheritance is implied but not explicitly implemented in the code

Sources: forms/UserForm.py:9

The role-based access control system interacts with several other components of the osysHome-Users plugin:

graph TD
    A["Role-Based Access Control"] --- B["User Management"]
    A --- C["Authentication System"]
    A --- D["Administrative Interface"]
    
    subgraph "Code Components"
        E["UserForm.role"]
        F["User.role property"]
        G["Permission checks"]
    end
    
    B --- E
    B --- F
    C --- F
    C --- G
    D --- G

Sources: forms/UserForm.py:9, init.py:38, init.py:50