new awesome build

2026-01-28 22:37:47 +03:00
parent 848646003c
commit fcb8f6bac7
119 changed files with 7291 additions and 5575 deletions
--- a/DOCS/Core_Monitoring/Authentication.md
+++ b/DOCS/Core_Monitoring/Authentication.md
@@ -0,0 +1,114 @@
+# Процесс аутентификации в OpenVPN Monitor
+
+Аутентификация в приложении реализована с использованием **Flask** и **JWT (JSON Web Tokens)**. Ниже приведено подробное описание механизмов и примеры использования API из консоли.
+
+---
+
+## 1. Логика работы
+
+Механизм аутентификации поддерживает два режима: стандартный вход и вход с двухфакторной аутентификацией (2FA).
+
+### Основные этапы:
+1.  **Запрос на вход (`POST /api/auth/login`)**:
+    *   Клиент отправляет `username` и `password`.
+    *   Сервер проверяет хеш пароля с использованием **BCrypt**.
+    *   **Защита (Rate Limiting)**: После 5 неудачных попыток IP-адрес блокируется на 15 минут.
+2.  **Выдача токена**:
+    *   **Если 2FA отключена**: Сервер возвращает финальный JWT-токен (валиден 8 часов).
+    *   **Если 2FA включена**: Сервер возвращает `temp_token` (валиден 5 минут) и флаг `requires_2fa: true`.
+3.  **Верификация 2FA (`POST /api/auth/verify-2fa`)**:
+    *   Клиент отправляет `temp_token` и 6-значный код (OTP).
+    *   Сервер проверяет код с помощью библиотеки `pyotp`.
+    *   При успешной проверке выдается финальный JWT-токен.
+
+---
+
+## 2. Использование API через консоль
+
+Для выполнения прямых вызовов API необходимо получить JWT-токен и передавать его в заголовке `Authorization`.
+
+### Шаг 1: Аутентификация
+
+#### Вариант А: 2FA отключена
+Выполните запрос для получения токена:
+```bash
+curl -X POST http://<SERVER_IP>:5001/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "ваш_пароль"}'
+```
+В ответе придет JSON с полем `"token"`.
+
+#### Вариант Б: 2FA включена (двухэтапный вход)
+1. Получите временный токен:
+```bash
+curl -X POST http://<SERVER_IP>:5001/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "ваш_пароль"}'
+```
+Скопируйте `temp_token` из ответа.
+
+2. Подтвердите вход кодом OTP:
+```bash
+curl -X POST http://<SERVER_IP>:5001/api/auth/verify-2fa \
+     -H "Content-Type: application/json" \
+     -d '{"temp_token": "ВАШ_TEMP_TOKEN", "otp": "123456"}'
+```
+Скопируйте финальный `token` из ответа.
+
+### Шаг 2: Вызов защищенных методов
+
+Используйте полученный токен в заголовке `Bearer`:
+
+**Пример: Получение списка клиентов**
+```bash
+curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
+     http://<SERVER_IP>:5001/api/v1/stats
+```
+
+**Пример: Просмотр сертификатов**
+```bash
+curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
+     http://<SERVER_IP>:5001/api/v1/certificates
+```
+
+---
+
+## 3. Быстрое получение токена из браузера
+
+Если вы уже вошли в веб-интерфейс, токен можно быстро скопировать без лишних запросов:
+1. Откройте панель разработчика (**F12**).
+2. Перейдите на вкладку **Application** (или **Storage**).
+4. Найдите ключ `ovpmon_token` — это и есть ваш текущий JWT-токен.
+
+---
+
+## 4. Account Management & 2FA Configuration
+
+Endpoints for managing the current user's security settings.
+
+### User Profile
+`GET /api/v1/user/me`
+Returns current user info and 2FA status.
+```json
+{ "success": true, "username": "admin", "is_2fa_enabled": false }
+```
+
+### Password Change
+`POST /api/auth/change-password`
+**Payload**: `{"current_password": "old", "new_password": "new"}`
+
+### 2FA Setup Flow
+
+1. **Initiate Setup**
+   `POST /api/auth/setup-2fa`
+   Returns a secret and a `otpauth://` URI for QR code generation.
+
+2. **Enable 2FA**
+   `POST /api/auth/enable-2fa`
+   **Payload**: `{"secret": "GENERATED_SECRET", "otp": "123456"}`
+   Verifies the code and enables 2FA for the user.
+
+3. **Disable 2FA**
+   `POST /api/auth/disable-2fa`
+   Disables 2FA (No payload required).
+