Add SSO
This commit is contained in:
235
OPENID_CONNECT_SETUP.md
Normal file
235
OPENID_CONNECT_SETUP.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 🔐 Настройка 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 решение
|
||||
- ✅ Бесплатный план для небольших проектов
|
||||
|
||||
**Удобного использования! 🔐**
|
||||
Reference in New Issue
Block a user