gns3-server/.claude/memory/rbac-user-isolation-design.md

name, description, metadata

name	description	metadata
rbac-user-isolation-design	GNS3 RBAC user isolation design and implementation thought process	type project

RBAC User Isolation Design Summary

Core Problem

GNS3 3.0 has a complete RBAC framework (ACE + Role + Privilege), but lacks user isolation implementation, causing users to see resources they shouldn't have access to.

Design Conflict

Traditional RBAC's path permission model fundamentally conflicts with user data isolation:

• Path permission model: Controls which paths users can access (e.g., /projects)
• User data isolation: Controls which specific resources users can access (e.g., alice's project vs bob's project)

Final Implementation Approach

Three-Step Permission Check Logic

# Step 1: ACE check - basic access permission
# Get list of projects user has ACE for
ace_projects = [p for p in all_projects() if user_has_ace(p, "Project.Audit")]

# Step 2: Filter ace_projects by created_by - user's own projects
# Key: Project sharing is only available through resource pools
user_projects = [p for p in ace_projects if p.created_by == user.username]

# Step 3: Resource pool projects
# Projects shared through resource pools
pool_projects = [p for p in pool_projects]

final_projects = user_projects + pool_projects

Key Design Decisions

1. ACE vs created_by Relationship

• ACE for basic access control: Whether user can access the system
• created_by for user isolation: Which specific resources user can access
• Step 2 filtering is critical: Even with broad ACE, created_by filtering ensures user isolation

2. Project Sharing Mechanism

• Project sharing only through resource pools: Cannot configure ACE directly for specific projects
• Avoids complexity of direct ACE sharing: Prevents permission configuration chaos

3. Broad ACE Fault Tolerance

Even with configuration: ACE: Users group + User role + "/" + propagate: True
Result: Users still only see projects they created
Reason: Step 2 created_by filtering removes other users' projects

Problems Solved

Problem 1: Missing User Isolation

• Issue: All users can see all projects
• Solution: Filter by created_by to implement user isolation

Problem 2: Broad ACE Breaking Isolation

• Issue: path: "/" + propagate: true breaks user isolation
• Solution: Step 2 created_by filtering ensures user isolation even with broad ACE

Problem 3: Permission Check Order Conflicts

• Issue: seen mechanism blocks subsequent checks
• Solution: Remove seen mechanism, use pipeline-style filtering

Technical Details

API Layer Permission Check

@router.get("/projects")  # Note: no has_privilege decorator
async def get_projects(current_user: schemas.User = Depends(get_current_active_user)):
    # Permission checks in business logic

Duplicate Prevention

• No seen_project_ids mechanism
• Natural duplicate prevention through pipeline filtering

Performance Considerations

• ACE check: O(n), where n is total projects
• created_by filtering: O(m), where m is ace_projects count
• Resource pool check: O(k), where k is pool project count

Use Cases

Scenario 1: Personal Use

alice creates project → alice only sees alice's projects ✅
bob creates project → bob only sees bob's projects ✅
No extra configuration needed, automatic user isolation

Scenario 2: Team Collaboration

Admin creates resource pool → adds projects → team members can access
alice creates project → alice still sees her own projects ✅
Team sharing + user isolation coexist

Scenario 3: Broad ACE Configuration

ACE: Users group + "/" + propagate: True
alice still only sees alice's projects ✅
User isolation unaffected by ACE configuration

Design Principles

1. Separation of Concerns

• Basic access permission: Controlled by ACE
• Data ownership: Controlled by created_by
• Team sharing: Controlled by resource pools

2. Defensive Design

• User isolation remains effective even with improper ACE configuration
• Secure by default: users only see their own resources

3. Simplicity

• Avoid complex seen mechanisms and mutual exclusion logic
• Clear pipeline-style check order

Relationship with Original ACE System

Preserved Components

• ✅ ACE framework (permission check mechanism)
• ✅ Role and privilege definitions
• ✅ Resource pool functionality

Improved Components

• ✅ Added user isolation (created_by filtering)
• ✅ Clarified project sharing mechanism (only through resource pools)
• ✅ Simplified permission check logic

Removed Components

• ❌ Removed /projects path privilege check
• ❌ Removed complex seen_project_ids mechanism
• ❌ Avoided "can see all non-pool projects" privilege leak

Implementation Details

• Main modification: gns3server/api/routes/controller/projects.py
• Function: get_projects()
• Branch: feature/simple-user-isolation
• Base branch: upstream/3.1

Key Commits

1. Implemented basic created_by filtering
2. Implemented three-layer permission check (with logic issues)
3. Fixed to correct three-step check logic

Design Evolution Process

Phase 1: Simple created_by Filtering

user_projects = [p for p in all_projects() if p.created_by == user.username]

Issue: Didn't integrate with ACE system

Phase 2: Three-Layer Check (Wrong Version)

# Used seen_project_ids mechanism
# Issue: Broad ACE breaks user isolation

Phase 3: Three-Step Check (Correct Version)

# Step 1: ACE check
# Step 2: Filter ace_projects by created_by
# Step 3: Resource pools

Solution: User isolation works even with broad ACE

Relationship with RBAC Roadmap

This implementation addresses items mentioned in the roadmap:

• Phase 1 (MVP): Basic project isolation implementation
• Auto-ACE on create: Still needs to be implemented separately
• Template isolation: Can use same design pattern

Unsolved Issues

1. Auto-ACE on project creation: Part of roadmap Phase 1
2. Template and image isolation: Can apply same design pattern
3. Default ACE configuration: Need reasonable default permissions for Users group

Design Limitations

1. Project sharing only through resource pools: No direct ACE configuration for sharing
2. ACE configuration required: Users need basic ACE to access system
3. Performance considerations: ACE check queries database for each project

Future Improvement Directions

1. Auto-create ACE: Automatically add ACE for creator when creating projects
2. Default ACE strategy: Configure reasonable default permissions for Users group
3. Performance optimization: Cache ACE check results to reduce database queries

This design achieves effective user isolation while maintaining RBAC system integrity, and solves the problem of broad ACE configurations breaking isolation.

Key insight: The Step 2 created_by filtering is the critical innovation that allows ACE and user isolation to coexist properly.