vtl-appliance/dist/adastra-vtl-installer/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:**
```json
{
    "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**

```javascript
// 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**

```javascript
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**

```javascript
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:**
```javascript
fetch('api.php', {
    method: 'POST',
    body: JSON.stringify({
        action: 'create_user',
        username: 'viewer1',
        password: 'password123',
        role: 'viewer'
    })
});
```

### Changing Password

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

### Logout

Click "Logout" link in navbar or:
```javascript
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

```bash
# 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

```bash
# After login, refresh page
# Should stay logged in

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

### Test Roles

```bash
# 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`