ModeusSchedule.MSAuth/README.md

ModeusSchedule.MSAuth

Зачем нужен этот сервис

ModeusSchedule.MSAuth — это вспомогательный HTTP-сервис, который автоматизирует авторизацию в Microsoft, заходит в веб-интерфейс Modeus и извлекает свежий id_token (JWT). Этот токен затем может использоваться другими компонентами вашей системы для обращения к API Modeus без ручного входа пользователя. Проект устраняет необходимость хранить пользовательские cookie, а также упрощает раздачу короткоживущих токенов другим сервисам через REST‑эндпоинт.

Ключевые возможности

• Браузерная авторизация через Playwright и Chromium в режиме headless.
• Кэширование токена на 20 минут, чтобы избежать лишних логинов.
• Ограничение параллельных попыток авторизации (возврат HTTP 429, если процесс уже идет).
• Опциональная защита API ключом (заголовок X-API-Key).
• Простой REST‑эндпоинт GET /auth/ms, который возвращает JSON { "jwt": "..." }.

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

1. Сервис при старте проверяет, что заданы параметры подключения к Modeus и учетные данные Microsoft (MODEUS_URL, MS_USERNAME, MS_PASSWORD).
2. При первом запросе Playwright поднимает headless Chromium и логинится в Modeus через Microsoft IDP.
3. После успешного входа токен id_token извлекается из sessionStorage, сохраняется в памяти и отдается клиенту.
4. Пока токен свежий, новые запросы обслуживаются из кэша. Как только TTL истекает, запускается новая авторизация.

Конфигурация

Параметр	Где задается	Назначение
MODEUS_URL	appsettings.json / переменные окружения	URL портала Modeus (например, https://<название вуза>.modeus.org/).
MS_USERNAME	appsettings.json / переменные окружения	Логин сервисной учетной записи Microsoft 365.
MS_PASSWORD	appsettings.json / переменные окружения	Пароль от этой учетной записи.
API_KEY (опционально)	appsettings.json / переменные окружения	Если задан, сервис будет требовать заголовок X-API-Key.

Быстрый старт

1. Установите .NET 9 SDK и Playwright (будет поставлен автоматически при первом запуске).
2. Создайте файл appsettings.Development.json или задайте переменные окружения с параметрами из таблицы выше.
3. Соберите и запустите сервис:

cd src
dotnet run

1. Выполните запрос:

curl -H "X-API-Key: <ваш ключ>" http://localhost:5000/auth/ms

В ответ вы получите JSON с полем jwt. При повторных вызовах в пределах времени жизни кэша сервис не будет заново входить в Microsoft.

Безопасность и эксплуатация

• Используйте отдельную сервисную учетную запись Microsoft с минимально необходимыми правами.
• Ограничьте доступ к эндпоинту по сети (VPN, reverse proxy) и включите проверку API_KEY.
• Логи Playwright могут содержать диагностическую информацию, поэтому убедитесь, что они не раскрывают пароли.

Лицензия

Проект распространяется под лицензией MIT. Подробнее в файле LICENSE.