Авторизация для Minecraft ------------------------- Здесь приведена информация по авторизации для лаунчеров и серверов Minecraft через сервис авторизации Ely.by. Протокол авторизации реализован максимально похожим на `оригинальный протокол авторизации Mojang `_, но тем не менее эта документация описывает все доступные функции конкретно сервиса авторизации 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. .. _profile-request: .. function:: GET /session/profile/{uuid} Запрос на этот URL выполняется клиентом в одиночной игре на локальном сервере (созданном посредством самой игры). В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока в таком же формате, как и при hasJoined запросе. Готовые библиотеки 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 RuBukkit - Список классов и клиентов для MCP Пример установки ~~~~~~~~~~~~~~~~ Предположим, что вы хотите установить авторизацию на сервер версии 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.