Auth User Plugin

The Auth User plugin provides comprehensive user authentication and management functionality for FastPluggy applications.

📊 Current Status

✅ PRODUCTION READY FEATURES:
- Complete admin interface for user management (CRUD operations)
- User authentication with secure password hashing
- Session management with configurable expiration
- User profile pages with authentication protection
- Automatic admin user creation on first install
- Menu integration for user functions

⚠️ PARTIALLY IMPLEMENTED:
- Login routes (exist but commented out - ready for activation)

📋 ROADMAP: See Implementation Roadmap for detailed development plan.

Features

• User Authentication: Secure username/password authentication with BCrypt hashing
• Admin Interface: Complete user management with list, add, edit functionality
• Session Management: Configurable session handling with JSON data storage
• User Profiles: Protected profile pages for authenticated users
• Menu Integration: Automatic menu items for profile and logout
• Template System: Jinja2 templates for login and profile pages
• Database Integration: SQLAlchemy models with FastPluggy core

Models

FastPluggyBaseUser

The main user model with the following fields:
- username: Unique username (String, 255 chars)
- hashed_password: Securely hashed password (String, 255 chars)
- is_admin: Boolean flag indicating admin privileges (default: False)

Session

Session management model for user authentication:
- session_id: Unique session identifier (String, 255 chars)
- session_data: JSON data stored in the session
- session_lifetime: Session expiration timestamp
- session_time: Session creation timestamp

Configuration

The plugin uses AuthUserConfig class with the following settings:

from fastpluggy.core.config import BaseDatabaseSettings
from typing import Optional

class AuthUserConfig(BaseDatabaseSettings):
    # Set to None to enable UI-based setup on first install
    # If None, admin user creation will be handled via setup UI
    default_admin_username: Optional[str] = None
    default_admin_password: Optional[str] = None
    login_template: str = 'auth_user/login.html'

Admin User Setup

The plugin provides intelligent admin user setup with two approaches:

🎯 Recommended: UI-Based Setup (Default)

By default, default_admin_username and default_admin_password are set to None, which enables the setup UI:

1. First Install: When no users exist, visit /setup/ to create the first admin user
2. Secure: No hardcoded credentials - you choose the username and password
3. User-Friendly: Clean web interface with validation and error handling
4. Automatic Detection: The system automatically detects when setup is needed

🔧 Alternative: Automatic Creation with Configured Credentials

If you prefer automatic admin creation, configure default credentials:

# In your environment or config
default_admin_username = "your_admin_username"
default_admin_password = "your_secure_password"

When configured, the plugin will automatically create the admin user on first startup.

📋 Setup Process

1. Plugin Load: System checks if any users exist
2. If No Users:
   - With configured credentials: Automatically creates admin user
   - Without credentials (default): Logs message to visit /setup/
3. Setup UI: Visit /setup/ to create admin user with custom credentials
4. Redirect: After successful setup, redirects to login page

🔍 Setup Status Check

You can check if setup is needed programmatically:

from fastpluggy_plugin.auth_user.src.repository import needs_initial_setup
from fastpluggy.core.database import get_db

if needs_initial_setup(get_db()):
    print("Setup required - visit /setup/")
else:
    print("Admin user exists")

Routes

Setup Routes

• GET /setup/ - Initial admin user setup page (only accessible when no users exist)
• POST /setup/ - Process admin user creation form
• GET /setup/check - API endpoint to check if setup is needed

Authentication Routes

• GET /logout - Logout user and clear session

Profile Routes

• GET /profile/ - User profile page (requires authentication)

Menu Integration

The plugin automatically adds the following menu items:
- Profile (/profile/) - User profile page
- Logout (/logout) - Logout functionality

Templates

The plugin expects the following Jinja2 templates:
- auth_user/profile.html.j2 - User profile page template
- auth_user/login.html.j2 - Login page template (referenced in config)

Usage

1. Installation: The plugin is automatically loaded when included in the FastPluggy application
2. First Run: On first installation with no existing users, call initialize_admin_user() to create the default admin account
3. Authentication: Users can authenticate using the login system (implementation may need to be completed)
4. Profile Management: Authenticated users can access their profile page at /profile/

Security Notes

• Passwords are securely hashed using BasicAuthManager.hash_password()
• Sessions are managed with configurable lifetime (default: 1 hour)
• Admin privileges are controlled via the is_admin boolean field
• Important: Change the default admin password after first login for security

Development Status

Some authentication routes are currently commented out in the login router and may need to be implemented based on your specific requirements.