ADMIN_SYSTEM

Admin System Documentation

Overview

The NDF Studio admin system provides comprehensive user management capabilities with automatic first-user superuser promotion and a complete admin interface for user management.

Features

1. Automatic First-User Superuser Promotion

• Mechanism: The first user to register in the system is automatically promoted to superuser status
• Implementation: Handled in UserManager._make_first_user_superuser() method
• Logging: All superuser promotions are logged with SECURITY level events
• Safety: Only applies to the very first user in the system

2. Admin User Management Interface

Backend API Endpoints

All admin endpoints require superuser privileges and are prefixed with /auth/admin/:

• GET /auth/admin/users - List all users with statistics
• POST /auth/admin/users - Create new user
• PUT /auth/admin/users/{user_id} - Update user details
• POST /auth/admin/users/{user_id}/promote - Promote user to superuser
• POST /auth/admin/users/{user_id}/demote - Demote superuser to regular user
• DELETE /auth/admin/users/{user_id} - Delete user
• GET /auth/admin/stats - Get system statistics

Frontend Admin Panel

• Location: Accessible via the "Admin" tab in the Knowledge Base panel
• Access Control: Only visible to superusers
• Features:
  • User listing with status indicators
  • Create new users
  • Edit existing users
  • Promote/demote users
  • Delete users
  • System statistics dashboard

Security Features

1. Access Control

• All admin endpoints require superuser authentication
• Non-superusers receive 403 Forbidden responses
• Frontend hides admin panel from non-superusers

2. Self-Protection Mechanisms

• Self-Demotion Prevention: Admins cannot demote themselves
• Self-Deletion Prevention: Admins cannot delete themselves
• Superuser Deletion Prevention: Superusers cannot be deleted (configurable)

3. Audit Logging

All admin actions are logged with SECURITY level events:

logger.security(
    f"Admin '{current_user.username}' promoted user '{user.username}' to superuser",
    event_type="admin_user_promotion",
    admin_user_id=str(current_user.id),
    promoted_user_id=str(user.id),
    promoted_username=user.username,
    reason=request.reason
)

API Reference

User Management Models

class UserPromoteRequest(BaseModel):
    user_id: str
    reason: Optional[str] = None

class UserDemoteRequest(BaseModel):
    user_id: str
    reason: Optional[str] = None

class AdminUserCreate(BaseModel):
    username: str
    email: str
    password: str
    is_superuser: bool = False
    is_active: bool = True

class UserUpdateRequest(BaseModel):
    username: Optional[str] = None
    email: Optional[str] = None
    is_active: Optional[bool] = None
    is_superuser: Optional[bool] = None

Endpoint Details

GET /auth/admin/users

Response:

{
  "users": [
    {
      "id": "uuid",
      "username": "string",
      "email": "string",
      "is_active": true,
      "is_superuser": false,
      "is_verified": true,
      "created_at": "timestamp"
    }
  ],
  "total": 5,
  "superusers": 1,
  "active_users": 4
}

POST /auth/admin/users

Request:

{
  "username": "newuser",
  "email": "[email protected]",
  "password": "securepassword",
  "is_superuser": false,
  "is_active": true
}

Response:

{
  "message": "User created successfully",
  "user": {
    "id": "uuid",
    "username": "newuser",
    "email": "[email protected]",
    "is_active": true,
    "is_superuser": false
  }
}

PUT /auth/admin/users/{user_id}

Request:

{
  "username": "updated_username",
  "email": "[email protected]",
  "is_active": true,
  "is_superuser": false
}

POST /auth/admin/users/{user_id}/promote

Request:

{
  "reason": "User needs admin access for project management"
}

POST /auth/admin/users/{user_id}/demote

Request:

{
  "reason": "User no longer needs admin access"
}

DELETE /auth/admin/users/{user_id}

Response:

{
  "message": "User 'username' deleted successfully"
}

GET /auth/admin/stats

Response:

{
  "total_users": 10,
  "active_users": 8,
  "inactive_users": 2,
  "superusers": 2,
  "regular_users": 8,
  "system_info": {
    "first_user_created": true,
    "has_superusers": true
  }
}

Frontend Integration

Admin Panel Component

The AdminPanel component provides a complete user management interface:

• User List: Table view with user details and status indicators
• Create User: Modal form for creating new users
• Edit User: Modal form for updating user details
• Actions: Promote, demote, and delete buttons for each user
• Statistics: Dashboard showing system statistics

Access Control

{activeTab === "admin" && userInfo?.is_superuser && (
  <div className="p-4">
    <AdminPanel />
  </div>
)}
{activeTab === "admin" && !userInfo?.is_superuser && (
  <div className="p-4 text-center">
    <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded">
      <strong>Access Denied:</strong> Admin privileges required to access this panel.
    </div>
  </div>
)}

Testing

Test Script

Run the comprehensive admin system test:

python test_admin_system.py

The test script verifies:

1. Automatic first-user superuser promotion
2. Admin user management operations
3. Access control and security measures
4. User promotion and demotion
5. User creation and deletion
6. System statistics
7. Self-protection mechanisms

Manual Testing

1. First User Registration:

   • Register the first user in a fresh system
   • Verify they become superuser automatically
   • Check logs for promotion event

2. Admin Panel Access:

   • Login as superuser
   • Navigate to Knowledge Base → Admin tab
   • Verify admin panel is visible and functional

3. User Management:

   • Create new users via admin panel
   • Promote regular users to superuser
   • Demote superusers to regular users
   • Update user details
   • Delete users

4. Access Control:

   • Login as regular user
   • Verify admin panel is not accessible
   • Verify admin API endpoints return 403

Configuration

Environment Variables

No additional environment variables are required. The admin system uses existing authentication configuration.

Database Schema

The admin system uses the existing User model with the is_superuser field:

class User(SQLModel, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    email: str = Field(nullable=False, unique=True, index=True)
    hashed_password: str = Field(nullable=False)
    is_active: bool = Field(default=True, nullable=False)
    is_superuser: bool = Field(default=False, nullable=False)
    is_verified: bool = Field(default=True, nullable=False)
    username: str = Field(nullable=False, unique=True, index=True)

Troubleshooting

Common Issues

1. First user not promoted to superuser:

   • Check if there are existing users in the database
   • Verify the _make_first_user_superuser method is called
   • Check logs for any errors

2. Admin panel not visible:

   • Verify user has is_superuser: true
   • Check browser console for errors
   • Verify the admin tab is added to DEV_PANEL_TABS

3. Admin API endpoints returning 403:

   • Verify user authentication
   • Check if user has superuser privileges
   • Verify token is valid and not expired

4. User creation/deletion failing:

   • Check database permissions
   • Verify user directory creation
   • Check logs for specific error messages

Log Analysis

Admin actions are logged with specific event types:

• first_user_superuser_promotion
• admin_user_creation
• admin_user_update
• admin_user_promotion
• admin_user_demotion
• admin_user_deletion

Search logs for these event types to track admin activities.

Security Considerations

1. Token Security: Admin operations require valid JWT tokens
2. Audit Trail: All admin actions are logged with detailed information
3. Self-Protection: Admins cannot accidentally remove their own privileges
4. Access Control: Non-superusers cannot access admin functionality
5. Input Validation: All user inputs are validated and sanitized

Future Enhancements

1. Role-Based Access Control: Support for multiple admin roles
2. Bulk Operations: Batch user management operations
3. User Activity Monitoring: Track user login patterns and activity
4. Advanced Statistics: More detailed system usage analytics
5. Email Notifications: Notify users of role changes
6. Two-Factor Authentication: Enhanced security for admin accounts