Sergey Karmanov
196b7d0ff4
All checks were successful
Create and publish a Docker image / Publish image (push) Successful in 6m31s
84 lines
5.9 KiB
Markdown
84 lines
5.9 KiB
Markdown
# Макросервис авторизации в Modeus через Microsoft
|
||
|
||
[](LICENSE)
|
||
[](https://dotnet.microsoft.com/download/dotnet/9.0)
|
||
|
||
## Зачем нужен этот сервис
|
||
|
||
ModeusSchedule.MSAuth — это вспомогательный HTTP-сервис, который автоматизирует авторизацию в Microsoft, заходит в веб-интерфейс Modeus и извлекает свежий `id_token` (JWT). Этот токен затем может использоваться другими компонентами вашей системы для обращения к API Modeus без ручного входа пользователя. Проект устраняет необходимость хранить пользовательские cookie, а также упрощает раздачу короткоживущих токенов другим сервисам через REST‑эндпоинт.
|
||
|
||
### Почему макросервис?
|
||
|
||
```dive
|
||
Total Image size: 1.4 GB
|
||
Potential wasted space: 6.5 MB
|
||
Image efficiency score: 99 %
|
||
```
|
||
|
||
> Внутри находится полноценный браузер Chromium с Playwright, что требует "значительных" ПЗУ ресурсов. Поэтому такой сервис лучше запускать отдельно от основных приложений.
|
||
|
||
## Ключевые возможности
|
||
|
||
- Браузерная авторизация через 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` / переменные окружения | Пароль от этой учетной записи. |
|
||
| `MS_TOTP_SECRET` *(опционально)* | `appsettings.json` / переменные окружения | Секрет для генерации TOTP-кодов. |
|
||
| `API_KEY` *(опционально)* | `appsettings.json` / переменные окружения | Если задан, сервис будет требовать заголовок `X-API-Key`. |
|
||
|
||
## Быстрый старт
|
||
|
||
1. Установите .NET 9 SDK и Playwright (будет установлен автоматически при первом запуске).
|
||
1. Создайте файл `appsettings.Development.json` или задайте переменные окружения с параметрами из таблицы выше.
|
||
1. Соберите и запустите сервис:
|
||
|
||
```bash
|
||
cd src
|
||
dotnet run
|
||
```
|
||
|
||
или
|
||
|
||
```bash
|
||
docker compose -f docker-compose-dev.yml up
|
||
```
|
||
|
||
1. Выполните запрос:
|
||
|
||
```bash
|
||
curl -H "X-API-Key: <ваш ключ>" http://localhost:5000/auth/ms
|
||
```
|
||
|
||
В ответ вы получите JSON с полем `jwt`. При повторных вызовах в пределах времени жизни кэша сервис не будет заново входить в Microsoft.
|
||
|
||
## Безопасность и эксплуатация
|
||
|
||
- Используйте отдельную сервисную учетную запись Microsoft с минимально необходимыми правами.
|
||
- Ограничьте доступ к эндпоинту по сети (VPN, reverse proxy) и включите проверку `API_KEY`.
|
||
- Логи Playwright могут содержать диагностическую информацию, поэтому убедитесь, что они не раскрывают пароли.
|
||
|
||
## Идеи для улучшений
|
||
|
||
- Сброс кэша по запросу.
|
||
- Переписать на TypeScript с использованием Playwright напрямую.
|
||
|
||
## Лицензия
|
||
|
||
Проект распространяется под лицензией MIT. Подробнее в файле [`LICENSE`](LICENSE).
|