mirror of https://github.com/elyby/docs.git
320 lines
21 KiB
ReStructuredText
320 lines
21 KiB
ReStructuredText
Авторизация для Minecraft
|
||
-------------------------
|
||
|
||
Здесь приведена информация по авторизации для лаунчеров и серверов Minecraft через сервис авторизации Ely.by.
|
||
|
||
Протокол авторизации реализован максимально похожим на `оригинальный протокол авторизации Mojang <http://wiki.vg/Authentication>`_,
|
||
но тем не менее эта документация описывает все доступные функции конкретно сервиса авторизации Ely.by.
|
||
|
||
Общие положения
|
||
===============
|
||
|
||
* Все запросы должны выполняться на URL **https://authserver.ely.by**.
|
||
|
||
* При успешном запросе, сервер вернёт ответ со статусом 200. Любой другой код свидетельствует об ошибке.
|
||
|
||
* Сервер всегда отвечает JSON данными, кроме случаев системных ошибок и ответов на legacy запросы. Учитывайте это для
|
||
отображения пользователю правильного сообщения об ошибке.
|
||
|
||
* В случае стандартной ошибки, вы получилите следующие данные:
|
||
|
||
.. code-block:: javascript
|
||
|
||
{
|
||
"error": "Краткое описание ошибки",
|
||
"errorMessage": "Более длинное описание ошибки на английском языке, пригодное для отображения пользователю."
|
||
}
|
||
|
||
Предусмотренные ошибки
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
В отличие от оригинального протокола, на Ely применяется меньший зоопарк ошибок:
|
||
|
||
.. list-table::
|
||
:widths: 20 50 30
|
||
:header-rows: 1
|
||
|
||
* - Ошибка (error)
|
||
- Причина
|
||
- Решение
|
||
* - IllegalArgumentException
|
||
- Вы передали неполный список данных для выполнения запроса.
|
||
- Внимательно перепроверьте что вы шлёте в запросе и что указано в документации.
|
||
* - ForbiddenOperationException
|
||
- Пользователь ввёл/разработчик передал неверные значения.
|
||
- Необходимо вывести пользователю уведомление о неправильно введённых данных.
|
||
|
||
Для индикации ошибки Not Found используется ответ с 404 статусом.
|
||
|
||
Авторизация в лаунчере
|
||
======================
|
||
|
||
В этом разделе описана авторизация для лаунчера или любой другой настольной программы, которой необходимо получить
|
||
accessToken для игрового клиента Minecraft. Важно понимать, что этот accessToken не имеет ничего общего с accessToken,
|
||
получаемым при oAuth авторизации - это два абсолютно разных ключа.
|
||
|
||
Все запросы выполняются на подуровень /auth POST запросом.
|
||
|
||
.. function:: /auth/authenticate
|
||
|
||
Непосредственная авторизация пользователя, используя его логин (ник или e-mail) и пароль.
|
||
|
||
Входные параметры:
|
||
|
||
:username: Никнейм пользователя или его e-mail (более предпочтительно).
|
||
|
||
:password: Пароль пользователя.
|
||
|
||
:clientToken: Уникальный токен лаунчера пользователя.
|
||
|
||
Успешный ответ:
|
||
|
||
.. code-block:: javascript
|
||
|
||
{
|
||
'accessToken': "Длинная_строка_содержащая_access_token",
|
||
'clientToken': "Переданный_в_запросе_client_token",
|
||
'availableProfiles': {}, /* См. ниже */
|
||
'selectedProfile': {
|
||
'id': "Длинная_строка_с_uuid_пользователя",
|
||
'name': "Текущий_nickname_пользователя",
|
||
'legacy': false
|
||
}
|
||
}
|
||
|
||
**availableProfiles** содержит в себе массив с одним элементом, таким же, как и selectedProfile. Добавлено только для
|
||
соответствия оригинальному протоколу и на деле не используется самими Mojang.
|
||
|
||
Касательно параметра **legacy** в selectedProfile в оригинальном протоколе явно не даны пояснения на счёт этого
|
||
параметра, но сказано, что обычно он в false. Возможно, он как-то используется официальным лаунчером.
|
||
|
||
.. function:: /auth/refresh
|
||
|
||
Обновляет валидный accessToken. Этот запрос позволяет не хранить на клиенте его пароль, а оперировать только сохранённым
|
||
значением accessToken для практически бесконечной возможности проходить авторизацию.
|
||
|
||
Входные параметры:
|
||
|
||
:accessToken: Уникальный ключ, полученый после авторизации.
|
||
|
||
:clientToken: Уникальный идентификатор клиента, относительно которого получен accessToken.
|
||
|
||
.. note:: В оригинальном протоколе так же передаётся значение selectedProfile, но на деле от него мало что зависит и
|
||
для идентификации пользователя достаточно только этих двух параметров. Наш сервер не обидится, увидив его -
|
||
он просто его проигнорирует.
|
||
|
||
В случае получения какой-либо предусмотренной ошибки, следует заново запросить пароль пользователя и произвести
|
||
обычную авторизацию.
|
||
|
||
Успешный ответ:
|
||
|
||
.. code-block:: javascript
|
||
|
||
{
|
||
'accessToken': "Новая_длинная_строка_ содержащая_access_token",
|
||
'clientToken': "Переданный_в_запросе_client_token",
|
||
'selectedProfile': {
|
||
'id': "Длинная_строка_с_uuid_пользователя",
|
||
'name': "Текущий_nickname_пользователя",
|
||
'legacy': false
|
||
}
|
||
}
|
||
|
||
.. function:: /auth/validate
|
||
|
||
Этот запрос позволяет проверить валиден ли указанный accessToken или нет. Этот запрос не обновляет токен и его время
|
||
жизни, а только позволяет удостовериться, что он ещё действительный. При отправке устаревшего токена, будет выведено
|
||
соответствующее сообщение, а сам токен будет удалён из базы.
|
||
|
||
Входные параметры:
|
||
|
||
:accessToken: Уникальный ключ, полученый после авторизации.
|
||
|
||
Успешным ответом будет являться пустое тело. Ориентируйтесь на поле **error** в теле ответа.
|
||
|
||
.. function:: /auth/signout
|
||
|
||
Этот запрос позволяет выполнить инвалидацию всех выданных пользователю токенов.
|
||
|
||
Входные параметры:
|
||
|
||
:username: Никнейм пользователя или его e-mail (более предпочтительно).
|
||
|
||
:password: Пароль пользователя.
|
||
|
||
Успешным ответом будет являться пустое тело. Ориентируйтесь на поле **error** в теле ответа.
|
||
|
||
.. function:: /auth/invalidate
|
||
|
||
Запрос позволяет инвалидировать accessToken. В случае, если переданный токен не удастся найти в хранилище токенов,
|
||
ошибка не будет сгенерирована и вы получите успешный ответ.
|
||
|
||
Входные параметры:
|
||
|
||
:accessToken: Уникальный ключ, полученый после авторизации.
|
||
|
||
:clientToken: Уникальный идентификатор клиента, относительно которого получен accessToken.
|
||
|
||
Успешным ответом будет являться пустое тело. Ориентируйтесь на поле **error** в теле ответа.
|
||
|
||
Авторизация на сервере
|
||
======================
|
||
|
||
Эти запросы выполняются непосредственно клиентом и сервером при помощи внутреннего кода или библиотеки authlib
|
||
(начиная с версии 1.7.2). Они актуальны только в том случае, если вы уже произвели авторизацию и запустили игру с валидным
|
||
accessToken. Вам остаётся только заменить пути внутри игры/библиотеки на привидённые ниже пути.
|
||
|
||
Поскольку непосредственно изменить что-либо в работе authlib или игры вы не можете, здесь не приводятся передаваемые значения
|
||
и ответы сервера. При необходимости вы сможете найти эту информацию самостоятельно в интернете.
|
||
|
||
Через authlib
|
||
~~~~~~~~~~~~~
|
||
|
||
.. important:: Эта часть документации описывает запросы, выполняемые через authlib в версии игры 1.7.2+. Для более старых
|
||
версий смотрите раздел ниже.
|
||
|
||
Все запросы из этой категории выполняются на подуровень /session. Перед каждым из запросов указан тип отправляемого запроса.
|
||
|
||
.. function:: POST /session/join
|
||
|
||
Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true.
|
||
|
||
.. function:: GET /session/hasJoined
|
||
|
||
Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключится, успешно
|
||
выполнит join запрос.
|
||
|
||
.. attention:: Внутри тела ответа есть параметр **properties**, который, в свою очередь, содержит поле **value** с
|
||
закодированной в ней base64 строкой. В оригинальной системе авторизации данные зашифрованы с помощью
|
||
приватного ключа и расшифровывались на клиенте с помощью публичного.
|
||
|
||
Ely, в свою очередь, **не выполняет шифрацию вовсе**, поэтому вам необходимо отключить проверку подписи в
|
||
библиотеке authlib. В противном случае текстуры всегда будут признаваться невалидными.
|
||
|
||
Для старых версий
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
.. important:: Эта часть документации описывает запросы, выполняемые более старыми версиями Minecraft, когда не применялась
|
||
библиотека authlib. Это все версии, младше версии 1.7.2.
|
||
|
||
Все запросы из этой категории выполняются на подуровень /session/legacy. Перед каждым из запросов указан тип отправляемого запроса.
|
||
|
||
Принцип обработки этих запросов такой же, как и для authlib, отличие только во входных параметрах и возвращаемых значения.
|
||
|
||
.. function:: GET /session/legacy/join
|
||
|
||
Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true.
|
||
|
||
.. function:: GET /session/legacy/hasJoined
|
||
|
||
Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключится, успешно
|
||
выполнит join запрос.
|
||
|
||
Важно не потерять GET параметр **?user=** в конце обоих запросов, чтобы получились следующие URL:
|
||
``http://minecraft.ely.by/session/legacy/hasJoined?user=``.
|
||
|
||
Одиночная игра
|
||
==============
|
||
|
||
По сути, одиночная игра - это локальный сервер, созданный для одного игрока. По крайней мере это так, начиная с версии 1.6,
|
||
в которой и был представлен механизм локальных серверов.
|
||
|
||
Тем не менее, описанный ниже запрос актуален только для Minecraft 1.7.6+, когда для загрузки скинов стала использоваться
|
||
так же authlib.
|
||
|
||
.. function:: GET /session/profile/{uuid}
|
||
|
||
Запрос на этот URL выполняется клиентом в одиночной игре на локальном сервере (созданном посредством самой игры).
|
||
В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока.
|
||
|
||
Готовые библиотеки authlib
|
||
==========================
|
||
|
||
Поскольку самостоятельная реализация связана с трудностями поиска исходников, подключения зависимостей и в конце-концов с
|
||
процессом компиляции, ниже приведён список пропатченых библиотек со всеми необходимыми изменениями адресов, отключённой
|
||
проверкой подписи и встроенной системой скинов для серверов с online-mode=false. Вы можете использовать их "как есть".
|
||
|
||
* Minecraft 1.8 - :download:`authlib 1.5.17 <_static/minecraft-auth/authlib/authlib-1.5.17.jar>`
|
||
|
||
* Minecraft 1.7.10 - :download:`authlib 1.5.16 <_static/minecraft-auth/authlib/authlib-1.5.16.jar>`
|
||
|
||
* Minecraft 1.7.9 - :download:`authlib 1.5.13 <_static/minecraft-auth/authlib/authlib-1.5.13.jar>`
|
||
|
||
В более ранних версиях система скинов находилась внутри клиента, так что библиотеки ниже обеспечивают только авторизацию.
|
||
|
||
* Minecraft 1.7.5 - :download:`authlib 1.3.1 <_static/minecraft-auth/authlib/authlib-1.3.1.jar>`
|
||
|
||
* Minecraft 1.7.2 - :download:`authlib 1.3 <_static/minecraft-auth/authlib/authlib-1.3.jar>`
|
||
|
||
.. hint:: На самом деле вам нужен только файл ``YggdrasilMinecraftSessionService.class``. Но здесь приведены готовые
|
||
библиотеки, чтобы вам не нужно было его искать и самостоятельно изменять.
|
||
|
||
Для использования библиотеки вам необходимо заменить оригинальную, располагающуюся по пути /libraries/com/mojang/authlib/
|
||
согласно её имени или же положить в другое место и просто при запуске игры подключить её, вместо оригинальной.
|
||
|
||
Установка authlib на сервер
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Кроме этого библиотеку необходимо установить и на сервер. Для этого вам понадобится файл сервера с расширением .jar.
|
||
Щёлкните на нём правой кнопкой мыши, выберите вариант "Открыть с помощью..." и выберите удобный архиватор (скорее всего WinRar).
|
||
Затем проделайте те же действия с authlib такой же версии, что и ваш сервер.
|
||
|
||
Перед вами будет 2 окна: одно с файлами authlib, другое с файлами сервера. Вам необходимо перетащить **только папку "com"**
|
||
из authlib на сервер и подтвердить замену.
|
||
|
||
.. figure:: _static/minecraft-auth/authlib-install.png
|
||
:align: center
|
||
:alt: Процесс перетягивания: что куда.
|
||
|
||
После этих действий вы можете закрыть оба окна и в настройках сервера включить online-mode=true, авторизация через Ely.by
|
||
установлена и работает!
|
||
|
||
Установка на версии ниже 1.7.2
|
||
==============================
|
||
|
||
Для более старых версий существует достаточно большое многообразие различных случаев, раскрыть которые в этой документации
|
||
не представляется возможным. Вся установка заключается в замене определённых строк в определённых классах через
|
||
InClassTranslator.
|
||
|
||
На форуме RuBukkit есть отличный пост, в котором собрана вся нужна информация по именам классов на различных версиях
|
||
Minecraft. Переписывать его сюда не имеет смысла, так что просто перейдите на его страницу и найдите нужную версию.
|
||
|
||
|rubukkit_link|.
|
||
|
||
.. |rubukkit_link| raw:: html
|
||
|
||
<a href="http://www.rubukkit.org/threads/spisok-klassov-i-klientov-dlja-mcp.25108/#post-303710" target="_blank">RuBukkit -
|
||
Список классов и клиентов для MCP</a>
|
||
|
||
Пример установки
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
Предположим, что вы хотите установить авторизацию на сервер версии 1.5.2.
|
||
|
||
Сначала вы переходите по вышепривидённой ссылке, выбираете нужную версию (1.5.2) и видите список классов:
|
||
|
||
* **bdk.class** - путь до joinserver
|
||
|
||
* **jg.class** - путь до checkserver
|
||
|
||
Затем вы должны взять .jar файл клиента и открыть его любым архиватором. После чего вам необходимо найти файл **bdk.class**.
|
||
Для этого удобно воспользоваться поиском.
|
||
|
||
После того, как вы нашли файл, его нужно извлечь из архива - просто перетащите его оттуда в удобную для вас дирикторию.
|
||
|
||
Дальше запустите InClassTranslator и в нём откройте этот класс. Слева будет список найденных в файле строк, которые вы
|
||
можете изменить. Нужно заменить только строку, отвечающую за запрос на подключение к серверу:
|
||
|
||
.. figure:: _static/minecraft-auth/installing_by_inclasstranslator.png
|
||
:align: center
|
||
:alt: Процесс перетягивания: что куда.
|
||
|
||
После этого вам нужно положить изменённый .class обратно в .jar файл игры.
|
||
|
||
Ту же самую операцию вам необходимо провести и с сервером, только заменить ссылку на hasJoined.
|
||
|
||
-----------------------
|
||
|
||
После этих действий вам нужно в настройках включить online-mode=true и сервер станет пускать на себя только тех игроков,
|
||
которые будут авторизованы через Ely.by.
|