init_guac
This commit is contained in:
root
385
guacamole_test_11_26/docs/AUTHENTICATION_FLOW.md
Executable file
385
guacamole_test_11_26/docs/AUTHENTICATION_FLOW.md
Executable file
@ -0,0 +1,385 @@
|
||||
# 🔐 Authentication Flow Diagram
|
||||
|
||||
## 📊 Complete Authentication Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ СИСТЕМА АУТЕНТИФИКАЦИИ │
|
||||
│ │
|
||||
│ ┌───────────────┐ ┌──────────────┐ ┌────────────────────┐ │
|
||||
│ │ Environment │ │ Guacamole │ │ Application │ │
|
||||
│ │ Variables │───▶│ Database │───▶│ Runtime │ │
|
||||
│ │ (.env) │ │ (PostgreSQL) │ │ (FastAPI) │ │
|
||||
│ └───────────────┘ └──────────────┘ └────────────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ SYSTEM_ADMIN_USERNAME / PASSWORD │ │
|
||||
│ │ (От вас, НЕ захардкожены) │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Startup Sequence
|
||||
|
||||
```
|
||||
1️⃣ API STARTUP
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ docker compose up -d │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ GuacamoleAuthenticator.__init__() │
|
||||
│ ├─ Read SYSTEM_ADMIN_USERNAME from env │
|
||||
│ ├─ Read SYSTEM_ADMIN_PASSWORD from env │
|
||||
│ └─ If missing → ValueError ❌ │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ wait_for_guacamole() │
|
||||
│ └─ Wait for Guacamole API to be ready │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ cleanup_orphaned_guacamole_connections() │
|
||||
│ ├─ Get system token (uses env credentials) │
|
||||
│ ├─ List all Guacamole connections │
|
||||
│ ├─ Check Redis for each connection │
|
||||
│ └─ Delete orphaned connections │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ✅ API Ready for User Requests │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 👤 User Login Flow
|
||||
|
||||
```
|
||||
1️⃣ USER LOGIN REQUEST
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ POST /auth/login │
|
||||
│ { │
|
||||
│ "username": "alice", │
|
||||
│ "password": "user_password" │
|
||||
│ } │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ guacamole_authenticator.authenticate_user() │
|
||||
│ ├─ Send to Guacamole: username="alice" │
|
||||
│ ├─ Send to Guacamole: password="user_password" │
|
||||
│ ├─ Get Guacamole token for alice │
|
||||
│ └─ Get user role and permissions │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ create_jwt_for_user() │
|
||||
│ ├─ Create JWT with username="alice" │
|
||||
│ ├─ Store Guacamole token in Redis session │
|
||||
│ └─ Return JWT to client │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ✅ User Authenticated │
|
||||
│ Client has JWT → Can make API requests │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**ВАЖНО:**
|
||||
- ❌ НЕ используется `SYSTEM_ADMIN_USERNAME/PASSWORD`
|
||||
- ✅ Используются credentials самого пользователя (alice)
|
||||
|
||||
---
|
||||
|
||||
## 🔌 User Creates Connection
|
||||
|
||||
```
|
||||
2️⃣ CREATE CONNECTION REQUEST
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ POST /connect │
|
||||
│ Authorization: Bearer <JWT> │
|
||||
│ { │
|
||||
│ "hostname": "server01", │
|
||||
│ "protocol": "rdp", │
|
||||
│ "username": "remote_user", │
|
||||
│ "password": "remote_password" │
|
||||
│ } │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ JWT Middleware │
|
||||
│ ├─ Extract session_id from JWT │
|
||||
│ ├─ Get Guacamole token from Redis session │
|
||||
│ ├─ Get user info (username="alice", role="USER") │
|
||||
│ └─ Pass to endpoint handler │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ create_remote_connection() │
|
||||
│ ├─ Use alice's Guacamole token │
|
||||
│ ├─ Create connection in Guacamole │
|
||||
│ ├─ Store connection info in Redis │
|
||||
│ └─ Return connection URL │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ✅ Connection Created │
|
||||
│ Owner: alice (from JWT) │
|
||||
│ Guacamole Token: alice's token (from Redis) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**ВАЖНО:**
|
||||
- ❌ НЕ используется `SYSTEM_ADMIN_USERNAME/PASSWORD`
|
||||
- ✅ Используется Guacamole token самого пользователя (alice)
|
||||
|
||||
---
|
||||
|
||||
## 🗑️ User Deletes Connection
|
||||
|
||||
```
|
||||
3️⃣ DELETE CONNECTION REQUEST
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ DELETE /connections/{id} │
|
||||
│ Authorization: Bearer <JWT> │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ delete_connection() │
|
||||
│ ├─ Get connection from Redis │
|
||||
│ ├─ Check ownership (connection.owner == alice) │
|
||||
│ ├─ Use alice's Guacamole token from Redis │
|
||||
│ └─ Delete from Guacamole │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ✅ Connection Deleted │
|
||||
│ Used: alice's token (NOT system admin) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**ВАЖНО:**
|
||||
- ❌ НЕ используется `SYSTEM_ADMIN_USERNAME/PASSWORD`
|
||||
- ✅ Используется Guacamole token владельца подключения
|
||||
|
||||
---
|
||||
|
||||
## 🧹 Background Cleanup (System)
|
||||
|
||||
```
|
||||
4️⃣ CLEANUP EXPIRED CONNECTIONS
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Background Task (every 60 seconds) │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ cleanup_expired_connections_once() │
|
||||
│ ├─ Get all connections from Redis │
|
||||
│ ├─ Find expired connections │
|
||||
│ └─ For each expired connection: │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ delete_connection_with_user_token() │
|
||||
│ ├─ Get user's token from Redis │
|
||||
│ ├─ Delete from Guacamole using user's token │
|
||||
│ └─ Delete from Redis │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ✅ Expired Connections Cleaned │
|
||||
│ Used: Each user's token (NOT system admin) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**ВАЖНО:**
|
||||
- ✅ Использует токен каждого пользователя (из Redis)
|
||||
- ❌ НЕ используется `SYSTEM_ADMIN_USERNAME/PASSWORD`
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Orphaned Cleanup (System)
|
||||
|
||||
```
|
||||
5️⃣ CLEANUP ORPHANED CONNECTIONS (Startup Only)
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ API Startup Event │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ cleanup_orphaned_guacamole_connections() │
|
||||
│ ├─ Get system token using env credentials │
|
||||
│ ├─ List ALL connections from Guacamole │
|
||||
│ ├─ Check if each exists in Redis │
|
||||
│ └─ Delete if NOT in Redis (orphaned) │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ get_system_token() │
|
||||
│ ├─ Read SYSTEM_ADMIN_USERNAME from env │
|
||||
│ ├─ Read SYSTEM_ADMIN_PASSWORD from env │
|
||||
│ ├─ Authenticate to Guacamole │
|
||||
│ └─ Return system token │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ delete_connection_with_system_token() │
|
||||
│ └─ Delete orphaned connections │
|
||||
└──────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ✅ Orphaned Connections Cleaned │
|
||||
│ Used: SYSTEM_ADMIN credentials from env │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**ВАЖНО:**
|
||||
- ✅ Это ЕДИНСТВЕННОЕ место где используется `SYSTEM_ADMIN`
|
||||
- ✅ Работает ТОЛЬКО на старте API
|
||||
- ✅ Credentials берутся из environment variables
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Model
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ БЕЗОПАСНОСТЬ CREDENTIALS │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────┬──────────────┬──────────────────────┐
|
||||
│ Credential Type │ Storage │ Usage │
|
||||
├─────────────────────┼──────────────┼──────────────────────┤
|
||||
│ SYSTEM_ADMIN │ .env file │ Startup cleanup │
|
||||
│ (username/pass) │ ✅ Required │ (orphaned conns) │
|
||||
├─────────────────────┼──────────────┼──────────────────────┤
|
||||
│ User Guacamole │ Redis │ User operations │
|
||||
│ token │ (ephemeral) │ (create/delete) │
|
||||
├─────────────────────┼──────────────┼──────────────────────┤
|
||||
│ User JWT │ Client │ API authorization │
|
||||
│ token │ (ephemeral) │ (all endpoints) │
|
||||
├─────────────────────┼──────────────┼──────────────────────┤
|
||||
│ REDIS_PASSWORD │ .env file │ Redis connections │
|
||||
│ │ ✅ Required │ (all components) │
|
||||
├─────────────────────┼──────────────┼──────────────────────┤
|
||||
│ POSTGRES_PASSWORD │ .env file │ DB connections │
|
||||
│ │ ✅ Required │ (API + Guacamole) │
|
||||
└─────────────────────┴──────────────┴──────────────────────┘
|
||||
|
||||
КРИТИЧНО:
|
||||
✅ Все credentials из .env (НЕ захардкожены)
|
||||
✅ User tokens ephemeral (хранятся в Redis с TTL)
|
||||
✅ System token используется ТОЛЬКО для cleanup
|
||||
✅ Нет fallback значений (API упадет если нет .env)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Token Types Comparison
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────────────────┐
|
||||
│ ТРИ ТИПА ТОКЕНОВ │
|
||||
└───────────────────────────────────────────────────────────────┘
|
||||
|
||||
1️⃣ JWT TOKEN (User API Token)
|
||||
├─ Создается: При login пользователя
|
||||
├─ Хранится: На клиенте (LocalStorage/Memory)
|
||||
├─ Срок жизни: 60 минут (configurable)
|
||||
├─ Используется для: Авторизации API запросов
|
||||
└─ Содержит: username, role, session_id
|
||||
|
||||
2️⃣ GUACAMOLE TOKEN (User Session Token)
|
||||
├─ Создается: При аутентификации в Guacamole
|
||||
├─ Хранится: В Redis (по session_id из JWT)
|
||||
├─ Срок жизни: Привязан к JWT сессии
|
||||
├─ Используется для: Создания/удаления подключений
|
||||
└─ Содержит: Guacamole authToken
|
||||
|
||||
3️⃣ SYSTEM TOKEN (Service Account Token)
|
||||
├─ Создается: При startup API
|
||||
├─ Хранится: В памяти GuacamoleAuthenticator
|
||||
├─ Срок жизни: До рестарта API
|
||||
├─ Используется для: Cleanup orphaned connections
|
||||
└─ Содержит: Guacamole authToken (for system admin)
|
||||
|
||||
ВАЖНО:
|
||||
✅ User никогда не видит SYSTEM TOKEN
|
||||
✅ SYSTEM TOKEN используется ТОЛЬКО внутри API
|
||||
✅ User operations используют User's Guacamole token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Key Takeaways
|
||||
|
||||
### ✅ **Что МОЖНО менять:**
|
||||
```env
|
||||
SYSTEM_ADMIN_USERNAME=любое_имя # ✅ Любое имя
|
||||
SYSTEM_ADMIN_PASSWORD=любой_пароль # ✅ Любой пароль
|
||||
REDIS_PASSWORD=любой_пароль # ✅ Любой пароль
|
||||
POSTGRES_PASSWORD=любой_пароль # ✅ Любой пароль
|
||||
```
|
||||
|
||||
### ❌ **Что НЕЛЬЗЯ:**
|
||||
```env
|
||||
SYSTEM_ADMIN_USERNAME= # ❌ Пустое значение
|
||||
SYSTEM_ADMIN_PASSWORD=guacadmin # ❌ Дефолтное значение
|
||||
REDIS_PASSWORD=redis_pass # ❌ Дефолтное значение
|
||||
```
|
||||
|
||||
### 🔒 **Где используются credentials:**
|
||||
|
||||
| Credential | Used By | Used For | User Visible? |
|
||||
|------------|---------|----------|---------------|
|
||||
| `SYSTEM_ADMIN_USERNAME/PASSWORD` | API (startup) | Orphaned cleanup | ❌ No |
|
||||
| User's Guacamole token | API (runtime) | User operations | ❌ No (in Redis) |
|
||||
| User's JWT | Client | API authorization | ✅ Yes (client-side) |
|
||||
|
||||
### 🎯 **Безопасность:**
|
||||
|
||||
1. ✅ **No hardcoded credentials** - Все из .env
|
||||
2. ✅ **No fallback values** - API упадет без credentials
|
||||
3. ✅ **System token isolated** - Только для cleanup
|
||||
4. ✅ **User tokens ephemeral** - Срок жизни ограничен
|
||||
5. ✅ **Role-based access** - GUEST/USER/ADMIN permissions
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- `ENDPOINT_AUDIT_REPORT.md` - Detailed endpoint analysis
|
||||
- `COMPATIBILITY_SUMMARY.md` - Quick compatibility check
|
||||
- `DEPLOYMENT_CHECKLIST.md` - Deployment guide
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-10-29
|
||||
**Version:** 1.0
|
||||
**Status:** ✅ PRODUCTION READY
|
||||
|
||||
Reference in New Issue
Block a user