NeveTimePanel/OPENID_CONNECT_SETUP.md

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

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

Поддержка OpenID Connect провайдеров

MC Panel теперь поддерживает вход через ZITADEL:

• 🔐 ZITADEL - Современная платформа управления идентификацией и доступом

📋 Требования

Установка зависимостей

cd backend
pip install authlib==1.3.0 httpx==0.26.0

Или установите все зависимости:

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 или используйте свой 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:

# Базовые настройки
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. Пример настройки

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

🚀 Запуск

1. Создайте .env файл

cd backend
cp .env.example .env

2. Настройте ZITADEL

Отредактируйте .env файл:

# Базовые настройки
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. Запустите сервер

cd backend
python main.py

4. Запустите фронтенд

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 или имени
• Сохраняется связь с провайдером

Данные пользователя

{
  "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 решение
• ✅ Бесплатный план для небольших проектов

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