NeveTimePanel/OPENID_CONNECT_SETUP.md

# 🔐 Настройка OpenID Connect

## Что добавлено

### Поддержка OpenID Connect провайдеров
MC Panel теперь поддерживает вход через ZITADEL:
- 🔐 **ZITADEL** - Современная платформа управления идентификацией и доступом

## 📋 Требования

### Установка зависимостей
```bash
cd backend
pip install authlib==1.3.0 httpx==0.26.0
```

Или установите все зависимости:
```bash
cd backend
pip install -r requirements.txt
```

Новые зависимости:
- `authlib==1.3.0` - OAuth2/OpenID Connect клиент
- `httpx==0.26.0` - HTTP клиент для API запросов

**Важно:** В authlib 1.3.0 используется `authlib.integrations.starlette_client` (FastAPI основан на Starlette)

## ⚙️ Настройка ZITADEL

### 1. Создание проекта в ZITADEL

#### Шаг 1: Регистрация в ZITADEL
1. Перейдите на [ZITADEL Cloud](https://zitadel.cloud/) или используйте свой self-hosted инстанс
2. Создайте новый проект или используйте существующий
3. Запомните URL вашего инстанса (например: `https://your-instance.zitadel.cloud`)

#### Шаг 2: Создание приложения
1. В проекте нажмите "New Application"
2. Выберите тип: **Web Application**
3. Выберите метод аутентификации: **Code (with PKCE)**
4. Укажите название: `MC Panel`

#### Шаг 3: Настройка Redirect URIs
Добавьте следующие redirect URIs:
- Для разработки: `http://localhost:8000/api/auth/oidc/zitadel/callback`
- Для продакшена: `https://your-domain.com/api/auth/oidc/zitadel/callback`

#### Шаг 4: Получение учётных данных
После создания приложения вы получите:
- **Client ID** - идентификатор приложения
- **Client Secret** - секретный ключ (сохраните его!)
- **Issuer URL** - URL вашего ZITADEL инстанса

### 2. Настройка в .env

Создайте или отредактируйте файл `backend/.env`:

```bash
# Базовые настройки
SECRET_KEY=your-secret-key-here-change-this-in-production
BASE_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000

# ZITADEL Configuration
ZITADEL_ISSUER=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your-client-id@your-project
ZITADEL_CLIENT_SECRET=your-client-secret
```

### 3. Пример настройки

```bash
# Пример для ZITADEL Cloud
ZITADEL_ISSUER=https://mc-panel-abc123.zitadel.cloud
ZITADEL_CLIENT_ID=123456789012345678@mc-panel
ZITADEL_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGH
```

## 🚀 Запуск

### 1. Создайте .env файл
```bash
cd backend
cp .env.example .env
```

### 2. Настройте ZITADEL
Отредактируйте `.env` файл:
```bash
# Базовые настройки
SECRET_KEY=your-secret-key-here-change-this-in-production
BASE_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000

# ZITADEL
ZITADEL_ISSUER=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your-client-id@your-project
ZITADEL_CLIENT_SECRET=your-client-secret
```

### 3. Запустите сервер
```bash
cd backend
python main.py
```

### 4. Запустите фронтенд
```bash
cd frontend
npm run dev
```

## 🎨 Интерфейс

### Страница входа
- Обычная форма входа (логин/пароль)
- Разделитель "Или войдите через"
- Кнопка ZITADEL с иконкой 🔐 и фиолетовым цветом
- Автоматическое скрытие кнопки если ZITADEL не настроен

## 🔧 Как это работает

### 1. Пользователь нажимает кнопку провайдера
```
GET /api/auth/oidc/{provider}/login
```

### 2. Перенаправление на провайдера
Пользователь перенаправляется на страницу авторизации провайдера

### 3. Callback от провайдера
```
GET /api/auth/oidc/{provider}/callback?code=...
```

### 4. Получение токена и данных пользователя
- Обмен code на access_token
- Получение информации о пользователе
- Создание или обновление пользователя в системе

### 5. Создание JWT токена
- Генерация JWT токена для пользователя
- Перенаправление на фронтенд с токеном

### 6. Автоматический вход
- Фронтенд получает токен из URL
- Сохраняет токен в localStorage
- Пользователь автоматически входит в систему

## 👥 Управление пользователями

### Автоматическое создание пользователей
При первом входе через OpenID Connect:
- Создаётся новый пользователь
- Роль: "user" (обычный пользователь)
- Username генерируется из email или имени
- Сохраняется связь с провайдером

### Данные пользователя
```json
{
  "username": "john_doe",
  "password": "",
  "role": "user",
  "servers": [],
  "oidc_id": "zitadel:123456789012345678",
  "email": "john@example.com",
  "name": "John Doe",
  "picture": "https://avatar.url",
  "provider": "zitadel",
  "created_at": "2026-01-15T12:00:00"
}
```

### Повторные входы
- Пользователь находится по `oidc_id`
- Обновляется email, имя и аватар
- Роль и серверы сохраняются

## 🔐 Безопасность

### Проверки
- Проверка state параметра (CSRF защита)
- Проверка redirect_uri
- Валидация токенов от провайдеров
- Проверка подписи JWT токенов

### Рекомендации
- Используйте HTTPS в продакшене
- Регулярно обновляйте client secrets
- Ограничьте redirect URIs
- Мониторьте подозрительную активность

## 🚨 Troubleshooting

### Ошибка "Provider not found"
- Проверьте настройки в .env файле
- Убедитесь что CLIENT_ID указан
- Перезапустите сервер

### Ошибка "Invalid redirect_uri"
- Проверьте redirect URI в настройках провайдера
- Должен точно совпадать с `BASE_URL/api/auth/oidc/{provider}/callback`

### Ошибка "Invalid client"
- Проверьте CLIENT_ID и CLIENT_SECRET
- Убедитесь что приложение активно у провайдера

### Пользователь не создаётся
- Проверьте логи сервера
- Убедитесь что провайдер возвращает email
- Проверьте права на запись в users.json

## ✅ Готово!

OpenID Connect с ZITADEL настроен и готов к использованию. Пользователи могут входить через:
- Обычную форму (логин/пароль)
- ZITADEL (OpenID Connect)

### Тестирование
1. Настройте ZITADEL в .env файле
2. Перезапустите сервер
3. Откройте страницу входа
4. Увидите кнопку "Войти через ZITADEL"
5. Нажмите на кнопку и войдите через ZITADEL

### Преимущества ZITADEL
- ✅ Полная поддержка OpenID Connect
- ✅ Современный интерфейс управления
- ✅ Поддержка многофакторной аутентификации
- ✅ Self-hosted или Cloud решение
- ✅ Бесплатный план для небольших проектов

**Удобного использования! 🔐**