172 lines
11 KiB
Markdown
172 lines
11 KiB
Markdown
|
# AuthService
|
|||
|
|
|
|||
|
|
## Обзор класса
|
|||
|
|
|
|||
|
|
`Minecraft_launcher` поддерживает три способа входа: офлайн-профиль без пароля, учётную запись
|
|||
|
|
Ely.by и учётную запись Microsoft. `AuthService` закрывает первые два: это Yggdrasil-клиент Ely.by
|
|||
|
|
плюс офлайн-режим. За третий отвечает [MsaAuthService](MsaAuthService.md).
|
|||
|
|
|
|||
|
|
Результат любого способа — структура `AuthResult`, объявленная в этом же заголовке. Она содержит
|
|||
|
|
ровно то, что подставляется в аргументы запуска вида `${auth_*}`, поэтому дальше запуск игры идёт
|
|||
|
|
по общему пути независимо от того, как пользователь вошёл.
|
|||
|
|
|
|||
|
|
Класс также умеет скачивать `authlib-injector` — библиотеку, которая перенаправляет обращения игры
|
|||
|
|
к серверу авторизации на Ely.by.
|
|||
|
|
|
|||
|
|
## Место в проекте и зависимости
|
|||
|
|
|
|||
|
|
Экземпляр создаётся и принадлежит [LauncherBackend](LauncherBackend.md); других владельцев нет.
|
|||
|
|
Заголовок подключает [MsaAuthService](MsaAuthService.md) — ради общей структуры `AuthResult` — и
|
|||
|
|
[GameLauncher](GameLauncher.md) через поля `LaunchOptions`, которые заполняются из результата
|
|||
|
|
авторизации.
|
|||
|
|
|
|||
|
|
Требования сборки: `Qt6::Core` (`QDateTime`, `QJsonObject`, `QString`) и `Qt6::Network`
|
|||
|
|
(`QNetworkAccessManager`).
|
|||
|
|
|
|||
|
|
## Иерархия и роль
|
|||
|
|
|
|||
|
|
Наследует `QObject`: даёт мета-объектную систему, сигнал `progress` и владение по родителю.
|
|||
|
|
Виртуальных методов базового класса не переопределяет.
|
|||
|
|
|
|||
|
|
## Публичные структуры
|
|||
|
|
|
|||
|
|
### AuthResult
|
|||
|
|
|
|||
|
|
Результат авторизации — то, что подставляется в `${auth_*}` аргументы запуска.
|
|||
|
|
|
|||
|
|
| Поле | Тип | Описание |
|
|||
|
|
|------|-----|----------|
|
|||
|
|
| `ok` | `bool` | Авторизация удалась |
|
|||
|
|
| `twoFactorRequired` | `bool` | Ely.by отклонил пароль с пометкой two factor — нужен одноразовый код |
|
|||
|
|
| `licenseMissing` | `bool` | Вход в Microsoft прошёл, но копии игры на аккаунте нет. Обрабатывается отдельно от прочих ошибок, потому что чинится только покупкой |
|
|||
|
|
| `error` | `QString` | Текст ошибки, когда `ok` равен `false` |
|
|||
|
|
| `playerName` | `QString` | Подставляется в `${auth_player_name}` |
|
|||
|
|
| `uuid` | `QString` | Подставляется в `${auth_uuid}`; hex без дефисов |
|
|||
|
|
| `accessToken` | `QString` | Подставляется в `${auth_access_token}` |
|
|||
|
|
| `clientToken` | `QString` | Подставляется в `${clientid}` |
|
|||
|
|
| `userType` | `QString` | Подставляется в `${user_type}`; принимает значения `legacy` (офлайн), `msa` (Microsoft) и `ELYBY` |
|
|||
|
|
| `refreshToken` | `QString` | Только для аккаунтов Microsoft: продлевает сессию без ввода пароля |
|
|||
|
|
| `xuid` | `QString` | Только для Microsoft; подставляется в `${auth_xuid}` |
|
|||
|
|
| `expiresAt` | `QDateTime` | Только для Microsoft: UTC-время, когда протухает `accessToken` |
|
|||
|
|
|
|||
|
|
## Псевдонимы типов
|
|||
|
|
|
|||
|
|
`AuthService::Callback` — `std::function<void(const AuthResult &)>`. Все сетевые методы
|
|||
|
|
асинхронные: колбэк вызывается ровно один раз и всегда в потоке GUI.
|
|||
|
|
|
|||
|
|
## Публичные методы
|
|||
|
|
|
|||
|
|
#### explicit AuthService(QObject \*parent = nullptr)
|
|||
|
|
|
|||
|
|
Создаёт сервис и его `QNetworkAccessManager`. Конструктор помечен `explicit`.
|
|||
|
|
|
|||
|
|
#### static AuthResult offline(const QString &nickname)
|
|||
|
|
|
|||
|
|
Готовит результат для офлайн-профиля без единого сетевого запроса. UUID выводится из ника так же,
|
|||
|
|
как это делает сам Minecraft в офлайне: `UUID.nameUUIDFromBytes(("OfflinePlayer:" + name)
|
|||
|
|
.getBytes(UTF_8))`. Благодаря этому один и тот же ник всегда даёт один и тот же UUID, и прогресс
|
|||
|
|
на сервере не теряется.
|
|||
|
|
|
|||
|
|
#### static QString generateClientToken()
|
|||
|
|
|
|||
|
|
Случайный `clientToken` лаунчера. Генерируется один раз на профиль и хранится вместе с ним:
|
|||
|
|
Yggdrasil связывает выданный `accessToken` именно с этим значением.
|
|||
|
|
|
|||
|
|
#### void loginElyBy(const QString &login, const QString &password, const QString &clientToken, const QString &accessToken, Callback callback)
|
|||
|
|
|
|||
|
|
Полный цикл входа в Ely.by: сначала проверка имеющегося токена, затем его продление, и только при
|
|||
|
|
неудаче — авторизация по паролю. Пароль можно оставить пустым, если уже есть рабочий
|
|||
|
|
`accessToken`, — тогда пользователю не придётся вводить его заново.
|
|||
|
|
|
|||
|
|
По ходу работы испускает `progress` с описанием текущего шага. Результат приходит в `callback`
|
|||
|
|
один раз; при ответе с пометкой двухфакторной аутентификации в нём выставлен
|
|||
|
|
`twoFactorRequired`, и вызывающий код должен спросить у пользователя код и продолжить через
|
|||
|
|
`loginElyByWithTotp()`.
|
|||
|
|
|
|||
|
|
#### void loginElyByWithTotp(const QString &login, const QString &password, const QString &totp, const QString &clientToken, Callback callback)
|
|||
|
|
|
|||
|
|
Повтор авторизации с одноразовым кодом двухфакторной аутентификации. Пароль и код объединяются в
|
|||
|
|
одно поле в формате «пароль:код», как того требует Ely.by.
|
|||
|
|
|
|||
|
|
#### void ensureAuthlibInjector(const QString &targetDir, std::function<void(const QString &path, const QString &error)> callback)
|
|||
|
|
|
|||
|
|
Скачивает `authlib-injector` в `targetDir`, если его там ещё нет. Колбэк получает либо путь к
|
|||
|
|
готовому jar, либо текст ошибки — заполнено всегда ровно одно из двух.
|
|||
|
|
|
|||
|
|
Библиотека нужна только для профилей Ely.by: она подключается к JVM аргументом `-javaagent` и
|
|||
|
|
перенаправляет обращения игры к серверу авторизации.
|
|||
|
|
|
|||
|
|
## Сигналы
|
|||
|
|
|
|||
|
|
#### progress(const QString &message)
|
|||
|
|
|
|||
|
|
Описание текущего шага авторизации. Испускается по ходу всех сетевых операций.
|
|||
|
|
|
|||
|
|
Обработчик показывает сообщение пользователю: в главном окне лаунчера оно попадает в плашку
|
|||
|
|
статуса и держится до следующего сообщения, потому что шаг может занять заметное время.
|
|||
|
|
|
|||
|
|
## Владение и время жизни
|
|||
|
|
|
|||
|
|
Класс наследует `QObject` и принимает `parent` в конструкторе — родитель его и удалит.
|
|||
|
|
`QNetworkAccessManager` создаётся в конструкторе с сервисом в роли родителя и уничтожается вместе
|
|||
|
|
с ним.
|
|||
|
|
|
|||
|
|
Колбэки захватываются по значению и живут до своего единственного вызова. Уничтожение сервиса во
|
|||
|
|
время незавершённого запроса отменяет запрос вместе с менеджером сети — колбэк в этом случае не
|
|||
|
|
вызывается, поэтому захватывать в него сырые указатели на объекты с меньшим временем жизни, чем у
|
|||
|
|
сервиса, нельзя.
|
|||
|
|
|
|||
|
|
## Потокобезопасность
|
|||
|
|
|
|||
|
|
Только поток GUI. Все сетевые методы асинхронные, и их колбэки вызываются в том же потоке, в
|
|||
|
|
котором создан сервис. Собственной синхронизации в классе нет.
|
|||
|
|
|
|||
|
|
## Взаимодействие с другими классами
|
|||
|
|
|
|||
|
|
`LauncherBackend` вызывает методы входа при запуске игры и переправляет сигнал `progress` в
|
|||
|
|
интерфейс. Полученный `AuthResult` он раскладывает по полям `LaunchOptions`, которые уходят в
|
|||
|
|
[GameLauncher](GameLauncher.md). Путь, возвращённый `ensureAuthlibInjector()`, попадает в поле
|
|||
|
|
`authlibInjectorPath` тех же параметров запуска.
|
|||
|
|
|
|||
|
|
Сохранением токенов между запусками занимается `LauncherBackend`: сам сервис ничего не пишет на
|
|||
|
|
диск, кроме скачанного jar.
|
|||
|
|
|
|||
|
|
## Внешнее взаимодействие
|
|||
|
|
|
|||
|
|
**Сеть, исходящие запросы.** Класс общается с сервером авторизации Ely.by через
|
|||
|
|
`QNetworkAccessManager`. Формат — JSON поверх HTTPS, запросы инициирует всегда лаунчер. Внутренний
|
|||
|
|
помощник `postJson()` разделяет три исхода: успешный ответ, ответ с кодом ошибки и транспортную
|
|||
|
|
ошибку — последняя отдаётся отдельным параметром, чтобы отличить недоступную сеть от отказа
|
|||
|
|
сервера.
|
|||
|
|
|
|||
|
|
Отдельным каналом идёт загрузка `authlib-injector` — обычная HTTPS-загрузка файла в
|
|||
|
|
`targetDir`. Повторных попыток при неудаче класс не делает: решение о повторе принимает вызывающий
|
|||
|
|
код.
|
|||
|
|
|
|||
|
|
Все сигналы и колбэки приходят в поток GUI.
|
|||
|
|
|
|||
|
|
## Пример использования
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
auto *auth = new AuthService(this);
|
|||
|
|
connect(auth, &AuthService::progress, this, &Backend::showStatus);
|
|||
|
|
|
|||
|
|
auth->loginElyBy(profile.login, profile.password,
|
|||
|
|
profile.clientToken, profile.accessToken,
|
|||
|
|
[this](const AuthResult &result) {
|
|||
|
|
if (result.twoFactorRequired) {
|
|||
|
|
emit twoFactorRequired(m_pendingProfileName);
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
if (!result.ok) {
|
|||
|
|
emit launchError(result.error);
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
continueLaunch(result);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
При создании этого документа использовался ИИ.
|