init_guac

guacamole_test_11_26/docs/CUSTOM_GUACAMOLE_USER.md

@@ -0,0 +1,325 @@
+# 🔐 Создание пользователя Guacamole с кастомным паролем
+
+## ❓ Почему нельзя просто изменить пароль в SQL?
+
+### **Проблема:**
+
+Guacamole использует **специфичный алгоритм хеширования**:
+
+```python
+password_hash = SHA-256(password_bytes + salt_bytes)
+```
+
+**НЕ просто SHA-256 от пароля!**
+
+### **Почему это сложно:**
+
+❌ **Нельзя использовать стандартные SQL функции**, потому что:
+
+```sql
+-- ❌ Это НЕ сработает:
+SELECT encode(digest('mypassword', 'sha256'), 'hex')
+
+-- ❌ Это тоже НЕ сработает:
+SELECT sha256('mypassword'::bytea || 'salt'::bytea)
+```
+
+**Причины:**
+1. PostgreSQL не имеет встроенной функции для конкатенации bytes + bytes и SHA-256
+2. Salt должен быть случайным (32 байта)
+3. Нужен точный формат который использует Guacamole
+
+---
+
+## ✅ **Решение: Python скрипт**
+
+Мы предоставляем скрипт `generate_guacamole_user.py` который:
+- ✅ Генерирует правильный SHA-256 хеш
+- ✅ Создает случайный безопасный salt
+- ✅ Выводит готовый SQL для вставки в БД
+
+---
+
+## 🚀 **Быстрый старт**
+
+### **Вариант 1: Создать SQL файл (рекомендуется для deployment)**
+
+```bash
+# 1. Генерируем SQL для admin пользователя
+cd GuacamoleRemoteAccess
+
+python3 generate_guacamole_user.py \
+  --username guacadmin \
+  --password "MySecurePassword123!" \
+  --admin \
+  > 002-custom-admin-user.sql
+
+# 2. Проверяем сгенерированный SQL
+cat 002-custom-admin-user.sql
+
+# 3. Применяем ДО первого запуска Guacamole
+# Вместо дефолтного 002-create-admin-user.sql используем наш:
+docker compose up -d postgres
+docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < 002-custom-admin-user.sql
+
+# 4. Запускаем остальные сервисы
+docker compose up -d
+```
+
+---
+
+### **Вариант 2: Применить сразу к запущенной БД**
+
+```bash
+# Генерируем и сразу применяем
+python3 generate_guacamole_user.py \
+  --username admin2 \
+  --password "AnotherSecurePass456!" \
+  --admin | \
+  docker compose exec -T postgres psql -U guacamole_user -d guacamole_db
+```
+
+---
+
+### **Вариант 3: Создать обычного пользователя (не admin)**
+
+```bash
+# Пользователь без прав администратора
+python3 generate_guacamole_user.py \
+  --username john_doe \
+  --password "JohnSecurePass789!" \
+  > create-user-john.sql
+
+docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < create-user-john.sql
+```
+
+---
+
+## 📋 **Полный пример: Deployment с кастомным admin**
+
+### **Шаг 1: Генерируем безопасный пароль**
+
+```bash
+# Генерируем случайный пароль (32 символа)
+NEW_PASSWORD=$(openssl rand -base64 32)
+echo "Generated password: $NEW_PASSWORD"
+
+# Сохраняем в безопасное место (password manager)
+```
+
+---
+
+### **Шаг 2: Генерируем SQL**
+
+```bash
+cd GuacamoleRemoteAccess
+
+python3 generate_guacamole_user.py \
+  --username guacadmin \
+  --password "$NEW_PASSWORD" \
+  --admin \
+  --verify \
+  > 002-custom-admin-user.sql
+```
+
+**Output:**
+```
+🔍 Verifying hash generation...
+✅ Hash generation verified
+
+✅ SQL generated successfully!
+   Username: guacadmin
+   Role: Administrator
+   Password length: 44 characters
+
+💡 To apply this SQL:
+   docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < output.sql
+```
+
+---
+
+### **Шаг 3: Заменяем дефолтный SQL**
+
+```bash
+# Переименовываем старый (на всякий случай)
+mv 002-create-admin-user.sql 002-create-admin-user.sql.backup
+
+# Используем наш
+mv 002-custom-admin-user.sql 002-create-admin-user.sql
+```
+
+---
+
+### **Шаг 4: Обновляем production.env**
+
+```bash
+nano production.env
+
+# Устанавливаем те же credentials
+SYSTEM_ADMIN_USERNAME=guacadmin
+SYSTEM_ADMIN_PASSWORD=<ваш_сгенерированный_пароль>
+```
+
+⚠️ **КРИТИЧНО:** Пароли должны совпадать!
+
+---
+
+### **Шаг 5: Запускаем**
+
+```bash
+# Первый запуск - SQL применится автоматически
+docker compose up -d
+
+# Проверяем логи
+docker compose logs postgres | grep "guacadmin"
+```
+
+---
+
+### **Шаг 6: Проверяем доступ**
+
+```bash
+# Проверяем что можем войти
+curl -X POST https://mc.exbytestudios.com/api/auth/login-ecdh \
+  -H "Content-Type: application/json" \
+  -d '{"username": "guacadmin", "password": "ваш_пароль"}'
+
+# Должны получить JWT токен
+```
+
+---
+
+## 🔄 **Для существующей установки**
+
+Если Guacamole уже запущен и нужно **изменить пароль guacadmin**:
+
+### **Вариант A: Через UI (рекомендуется)**
+1. Войдите как guacadmin
+2. Settings → Users → guacadmin → Change password
+3. Установите новый пароль
+4. Обновите `production.env` с новым паролем
+
+### **Вариант B: Через SQL (если забыли пароль)**
+
+```bash
+# 1. Генерируем новый хеш
+python3 generate_guacamole_user.py \
+  --username guacadmin \
+  --password "NewPassword123!" \
+  --admin \
+  | grep "decode(" > update.txt
+
+# 2. Создаем UPDATE SQL
+cat > update-password.sql <<'EOF'
+UPDATE guacamole_user 
+SET 
+    password_hash = decode('NEW_HASH_HERE', 'hex'),
+    password_salt = decode('NEW_SALT_HERE', 'hex'),
+    password_date = CURRENT_TIMESTAMP
+WHERE entity_id = (
+    SELECT entity_id FROM guacamole_entity 
+    WHERE name = 'guacadmin' AND type = 'USER'
+);
+EOF
+
+# 3. Вручно копируем hash и salt из вывода скрипта
+# 4. Применяем
+docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < update-password.sql
+
+# 5. Обновляем production.env
+nano production.env
+# SYSTEM_ADMIN_PASSWORD=NewPassword123!
+
+# 6. Перезапускаем API
+docker compose restart remote_access_api
+```
+
+---
+
+## 🔍 **Как работает скрипт**
+
+```python
+# 1. Генерируем случайный salt (32 байта)
+salt = secrets.token_bytes(32)
+
+# 2. Конвертируем пароль в bytes
+password_bytes = password.encode('utf-8')
+
+# 3. Вычисляем SHA-256(password + salt)
+hash_input = password_bytes + salt
+password_hash = hashlib.sha256(hash_input).digest()
+
+# 4. Конвертируем в HEX для PostgreSQL
+hash_hex = password_hash.hex().upper()
+salt_hex = salt.hex().upper()
+
+# 5. Генерируем SQL с decode('HEX', 'hex')
+```
+
+**Именно так это делает Guacamole изнутри!**
+
+---
+
+## 🆘 **Troubleshooting**
+
+### Проблема: `ImportError: No module named 'secrets'`
+
+**Решение:** Используйте Python 3.6+
+
+```bash
+python3 --version  # Должно быть >= 3.6
+```
+
+---
+
+### Проблема: Пароль не работает после применения SQL
+
+**Причины:**
+1. ❌ SQL применился к неправильной БД
+2. ❌ Пользователь уже существует (дубликат)
+3. ❌ Некорректный пароль в `production.env`
+
+**Решение:**
+```bash
+# Проверяем что пользователь создался
+docker compose exec postgres psql -U guacamole_user -d guacamole_db -c \
+  "SELECT name, password_date FROM guacamole_user u 
+   JOIN guacamole_entity e ON u.entity_id = e.entity_id 
+   WHERE e.name = 'guacadmin';"
+
+# Если пользователь есть - проверяем пароль через UI
+```
+
+---
+
+### Проблема: Хочу использовать UUID вместо username
+
+**Решение:** Измените `--username` на UUID:
+
+```bash
+python3 generate_guacamole_user.py \
+  --username "admin-$(uuidgen)" \
+  --password "SecurePass!" \
+  --admin
+```
+
+---
+
+## 📚 **Дополнительные ресурсы**
+
+- [Guacamole Password Hashing](https://guacamole.apache.org/doc/gug/jdbc-auth.html#jdbc-auth-password-hashing)
+- [PostgreSQL pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) - если хотите делать это в чистом SQL
+- `SECURITY_SETUP.md` - настройка безопасности
+- `MIGRATION_SECURITY_UPDATE.md` - миграция существующих установок
+
+---
+
+## ✅ **Best Practices**
+
+1. ✅ **Генерируйте пароли случайно** (`openssl rand -base64 32`)
+2. ✅ **Используйте разные пароли** для разных окружений (dev/staging/prod)
+3. ✅ **Не коммитьте** сгенерированные SQL файлы с паролями в git
+4. ✅ **Храните пароли безопасно** (password manager, vault)
+5. ✅ **Меняйте пароли регулярно** (каждые 90 дней)
+6. ✅ **Используйте `--verify`** флаг для проверки генерации хеша
+