vtl-appliance/docs/WEB_UI_AUTHENTICATION.md

🔐 Web UI Authentication & Authorization System

📋 Overview

Implemented comprehensive authentication and authorization system for the MHVTL Web UI with role-based access control, session management, and multi-user support.

---

✨ Features

1. User Authentication 🔑

• Secure login system with password hashing (BCrypt)
• Session management with 1-hour timeout
• Automatic session validation on page load
• Secure logout functionality

2. Role-Based Access Control 👥

Two user roles with different permissions:

Admin Role 🔴

Full access to all features:

• ✅ View all system information
• ✅ Modify configurations
• ✅ Create/delete tapes
• ✅ Manage iSCSI targets
• ✅ Restart/shutdown appliance
• ✅ Manage users
• ✅ Change passwords

Viewer Role 🔵

Read-only access:

• ✅ View all system information
• ✅ View configurations
• ✅ View tape lists
• ✅ View iSCSI targets
• ❌ Cannot modify anything
• ❌ Cannot create/delete
• ❌ Cannot restart/shutdown
• ✅ Can change own password

3. Multi-User Support 👤👤

• Support for unlimited users
• Each user has unique credentials
• Users can be enabled/disabled
• User creation/deletion (admin only)
• Password management

4. Security Features 🛡️

• Password hashing with BCrypt
• Session timeout (1 hour)
• CSRF protection via session tokens
• Secure password storage
• Cannot delete own admin account
• Double confirmation for critical actions

---

🎨 User Interface

Login Page

Beautiful gradient login page with:

• Modern design with gradient background
• Form validation
• Loading states
• Error messages
• Default credentials display
• Auto-redirect if already logged in

URL: http://localhost/mhvtl-config/login.html

Default Credentials:

Username: admin
Password: admin123

Main Application

After login:

• User info displayed in navbar
• Role badge (ADMIN/VIEWER)
• Logout link
• Role-based UI restrictions

Viewer UI:

• All modification buttons disabled
• Form inputs readonly
• "Admin access required" tooltips
• Grayed out controls

---

🔧 Technical Implementation

Backend (PHP)

auth.php - Authentication System

Functions:

• initializeUsersFile() - Create default admin user
• loadUsers() - Load users from JSON file
• saveUsers($users) - Save users to JSON file
• authenticateUser($username, $password) - Verify credentials
• isLoggedIn() - Check session validity
• isAdmin() - Check admin role
• isViewer() - Check viewer role
• getCurrentUser() - Get current user info
• logout() - Destroy session
• requireLogin() - Enforce authentication
• requireAdmin() - Enforce admin role
• getAllUsers() - List all users (admin only)
• createUser($data) - Create new user (admin only)
• updateUser($data) - Update user (admin only)
• deleteUser($username) - Delete user (admin only)
• changePassword($data) - Change own password

User Storage:

• File: /etc/mhvtl/users.json
• Format: JSON array of user objects
• Permissions: 0600 (owner read/write only)

User Object:

{
    "username": "admin",
    "password": "$2y$10$...",  // BCrypt hash
    "role": "admin",
    "created": "2025-12-09 17:00:00",
    "enabled": true
}

api.php - API Endpoints

New Endpoints:

• login - Authenticate user
• logout - End session
• check_session - Validate session
• get_users - List users (admin)
• create_user - Create user (admin)
• update_user - Update user (admin)
• delete_user - Delete user (admin)
• change_password - Change password

Protected Endpoints: All existing endpoints now require authentication. Admin-only endpoints:

• save_config
• restart_service
• create_tapes
• delete_tape
• bulk_delete_tapes
• create_target
• delete_target
• add_lun
• bind_initiator
• unbind_initiator
• restart_appliance
• shutdown_appliance

Frontend (JavaScript)

Session Management

// Check session on page load
async function checkSession() {
    const response = await fetch('api.php', {
        method: 'POST',
        body: JSON.stringify({ action: 'check_session' })
    });
    
    const data = await response.json();
    
    if (!data.logged_in) {
        window.location.href = 'login.html';
    }
}

Role-Based UI

function applyRoleBasedUI() {
    if (currentUser.role !== 'admin') {
        // Disable admin-only buttons
        document.querySelectorAll('[onclick*="applyConfig"]')
            .forEach(btn => {
                btn.disabled = true;
                btn.title = 'Admin access required';
            });
        
        // Make inputs readonly
        document.querySelectorAll('input, select')
            .forEach(input => {
                input.setAttribute('readonly', 'readonly');
            });
    }
}

Logout

async function logout() {
    await fetch('api.php', {
        method: 'POST',
        body: JSON.stringify({ action: 'logout' })
    });
    
    window.location.href = 'login.html';
}

---

🎯 Usage

First Login

1. Navigate to http://localhost/mhvtl-config/
2. Automatically redirected to login page
3. Use default credentials:
   • Username: admin
   • Password: admin123
4. Click "Sign In"
5. Redirected to main application

Creating Users (Admin Only)

Via API:

fetch('api.php', {
    method: 'POST',
    body: JSON.stringify({
        action: 'create_user',
        username: 'viewer1',
        password: 'password123',
        role: 'viewer'
    })
});

Changing Password

Via API:

fetch('api.php', {
    method: 'POST',
    body: JSON.stringify({
        action: 'change_password',
        current_password: 'oldpass',
        new_password: 'newpass'
    })
});

Logout

Click "Logout" link in navbar or:

logout();

---

🔒 Security Best Practices

Implemented:

1. ✅ Password Hashing - BCrypt with automatic salt
2. ✅ Session Timeout - 1-hour inactivity timeout
3. ✅ Secure Storage - User file with 0600 permissions
4. ✅ Role Validation - Server-side role checking
5. ✅ CSRF Protection - Session-based validation
6. ✅ Input Validation - Username/password validation
7. ✅ Self-Protection - Cannot delete own account
8. ✅ Secure Defaults - Default admin account created

Recommendations:

1. ⚠️ Change Default Password - Immediately after first login
2. ⚠️ Use Strong Passwords - Minimum 8 characters, mixed case, numbers
3. ⚠️ Regular Password Changes - Change passwords periodically
4. ⚠️ Limit Admin Accounts - Only create admin accounts when necessary
5. ⚠️ Disable Unused Accounts - Disable instead of delete for audit trail
6. ⚠️ HTTPS Recommended - Use HTTPS in production for encrypted communication

---

📁 Files Created/Modified

New Files:

1. /builder/adastra-vtl/web-ui/auth.php - Authentication system
2. /builder/adastra-vtl/web-ui/login.html - Login page
3. /etc/mhvtl/users.json - User database (auto-created)

Modified Files:

1. /builder/adastra-vtl/web-ui/api.php - Added auth integration
2. /builder/adastra-vtl/web-ui/script.js - Added session check & role-based UI

Deployed to:

• /var/www/html/mhvtl-config/

---

🎨 UI Changes

Navbar

Before:

🎞️ Adastra VTL
Virtual Tape Library Configuration

After:

🎞️ Adastra VTL
Virtual Tape Library Configuration
👤 admin [ADMIN] Logout

Viewer Mode

All modification controls:

• Grayed out (opacity: 0.5)
• Disabled state
• Tooltip: "Admin access required"
• Readonly inputs

---

🧪 Testing

Test Login

# Open browser
http://localhost/mhvtl-config/

# Should redirect to login page
http://localhost/mhvtl-config/login.html

# Login with:
Username: admin
Password: admin123

# Should redirect to main page
http://localhost/mhvtl-config/index.html

Test Session

# After login, refresh page
# Should stay logged in

# Wait 1 hour
# Refresh page
# Should redirect to login (session expired)

Test Roles

# Create viewer user via API
# Login as viewer
# Verify:
- All buttons disabled
- Inputs readonly
- Can view everything
- Cannot modify anything

---

📊 Default Users

Username	Password	Role	Status
admin	admin123	admin	enabled

⚠️ IMPORTANT: Change the default password immediately after first login!

---

✅ Summary

What's Protected:

• ✅ All pages require authentication
• ✅ All API endpoints require authentication
• ✅ Admin actions require admin role
• ✅ Sessions expire after 1 hour
• ✅ Passwords securely hashed
• ✅ Role-based UI restrictions

User Experience:

• ✅ Beautiful login page
• ✅ Automatic session checking
• ✅ Clear role indicators
• ✅ Intuitive logout
• ✅ Helpful error messages
• ✅ Smooth redirects

Security:

• ✅ BCrypt password hashing
• ✅ Session management
• ✅ Role-based access control
• ✅ Secure file permissions
• ✅ Input validation
• ✅ CSRF protection

---

Status: ✅ COMPLETE
Date: December 9, 2025
Access: http://localhost/mhvtl-config/
Default Login: admin / admin123