59 lines
4.5 KiB
Markdown
59 lines
4.5 KiB
Markdown
# 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`).
|
||
1. При первом запросе Playwright поднимает headless Chromium и логинится в Modeus через Microsoft IDP.
|
||
1. После успешного входа токен `id_token` извлекается из `sessionStorage`, сохраняется в памяти и отдается клиенту.
|
||
1. Пока токен свежий, новые запросы обслуживаются из кэша. Как только 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 (будет поставлен автоматически при первом запуске).
|
||
1. Создайте файл `appsettings.Development.json` или задайте переменные окружения с параметрами из таблицы выше.
|
||
1. Соберите и запустите сервис:
|
||
|
||
```bash
|
||
cd src
|
||
dotnet run
|
||
```
|
||
|
||
1. Выполните запрос:
|
||
|
||
```bash
|
||
curl -H "X-API-Key: <ваш ключ>" http://localhost:5000/auth/ms
|
||
```
|
||
|
||
В ответ вы получите JSON с полем `jwt`. При повторных вызовах в пределах времени жизни кэша сервис не будет заново входить в Microsoft.
|
||
|
||
## Безопасность и эксплуатация
|
||
|
||
- Используйте отдельную сервисную учетную запись Microsoft с минимально необходимыми правами.
|
||
- Ограничьте доступ к эндпоинту по сети (VPN, reverse proxy) и включите проверку `API_KEY`.
|
||
- Логи Playwright могут содержать диагностическую информацию, поэтому убедитесь, что они не раскрывают пароли.
|
||
|
||
## Лицензия
|
||
|
||
Проект распространяется под лицензией MIT. Подробнее в файле [`LICENSE`](LICENSE).
|