Авторизация для Minecraft

Здесь приведена информация по авторизации для лаунчеров и серверов Minecraft через сервис авторизации Ely.by.

Протокол авторизации реализован максимально похожим на оригинальный протокол авторизации Mojang, но тем не менее эта документация описывает все доступные функции конкретно сервиса авторизации Ely.by.

Общие положения

• Все запросы должны выполняться на URL https://authserver.ely.by.

• При успешном запросе, сервер вернёт ответ со статусом 200. Любой другой код свидетельствует об ошибке.

• Сервер всегда отвечает JSON данными, кроме случаев системных ошибок и ответов на legacy запросы. Учитывайте это для отображения пользователю правильного сообщения об ошибке.

• В случае стандартной ошибки, вы получите следующие данные:

  {
      "error": "Краткое описание ошибки",
      "errorMessage": "Более длинное описание ошибки на английском языке, пригодное для отображения пользователю."
  }
  

Предусмотренные ошибки

В отличие от оригинального протокола, на Ely применяется меньший зоопарк ошибок:

Ошибка (error)	Причина	Решение
IllegalArgumentException	Вы передали неполный список данных для выполнения запроса.	Внимательно перепроверьте что вы шлёте в запросе и что указано в документации.
ForbiddenOperationException	Пользователь ввёл/разработчик передал неверные значения.	Необходимо вывести пользователю уведомление о неправильно введённых данных.

Для индикации ошибки Not Found используется ответ с 404 статусом.

Авторизация в лаунчере

В этом разделе описана авторизация для игрового лаунчера и описывает действия, необходимые для получения accessToken для игрового клиента Minecraft. В результате авторизации будет получен JWT-токен с правами доступа minecraft_server_session.

Внимание

Мы рекомендуем использовать протокол авторизации OAuth 2.0 с запросом прав доступа minecraft_server_session, как более безопасный и удобный для пользователя метод.

POST /auth/authenticate

Непосредственная авторизация пользователя, используя его логин (ник или E‑mail), пароль и токен двухфакторной аутентификации.

Параметры

• username (string) – Никнейм пользователя или его E‑mail (более предпочтительно).

• password (string) – Пароль пользователя или комбинация пароль:токен.

• clientToken (string) – Уникальный токен лаунчера пользователя.

• requestUser (bool) – Если поле передано как true, то в ответе сервера будет присутствовать поле user.

Система аккаунтов Ely.by поддерживает защиту пользователей посредством двухфакторной аутентификации. В оригинальном протоколе авторизации Mojang не предусмотрено возможности для передачи TOTP-токенов. Для решения этой проблемы и сохранения совместимости с реализацией сервера Yggdrasil, мы предлагаем передавать токен в поле password в формате пароль:токен.

К сожалению, не все пользователи осведомлены об этой возможности, поэтому будет лучше при получении ошибки о защищённости аккаунта пользователя двухфакторной аутентификацией явно запросить у него токен и склеить его программно.

Логика следующая:

1. Если пользователь указал верные логин и пароль, но для его аккаунта включена двухфакторная аутентификация, вы получите ответ с 401 статусом и следующим содержимым:

   {
       "error": "ForbiddenOperationException",
       "errorMessage": "Account protected with two factor auth."
   }
   

2. При получении этой ошибки, необходимо запросить у пользователя ввод TOTP‑токена, после чего повторить запрос на авторизацию с теми же учётными данными, добавив к паролю постфикс в виде :токен, где токен — это значение, введённое пользователем.

   Если пароль пользователя был «password123», а токен «123456», то после склейки поле password примет значение «password123:123456».

3. Если в результате этих действий вы получите ответ с 401 статутом и errorMessage «Invalid credentials. Invalid email or password.», то это будет свидетельствовать о том, что переданный токен неверен и его нужно перезапросить у пользователя.

Если все данные будут переданы верно, вы получите следующий ответ:

{
    "accessToken": "Длинная_строка_содержащая_access_token",
    "clientToken": "Переданный_в_запросе_client_token",
    "availableProfiles": [
        {
            "id": "UUID_пользователя_без_дефисов",
            "name": "Текущий_username_пользователя"
        }
    ],
    "selectedProfile": {
        "id": "UUID_пользователя_без_дефисов",
        "name": "Текущий_username_пользователя"
    },
    "user": { /* Только если передан параметр requestUser */
        "id": "UUID_пользователя_без_дефисов",
        "username": "Текущий_username_пользователя",
        "properties": [
            {
                "name": "preferredLanguage",
                "value": "ru"
            }
        ]
    }
}

POST /auth/refresh

Обновляет валидный accessToken. Этот запрос позволяет не хранить на клиенте его пароль, а оперировать только сохранённым значением accessToken для практически бесконечной возможности проходить авторизацию.

Параметры

• accessToken (string) – Уникальный ключ, полученный после авторизации.

• clientToken (string) – Уникальный идентификатор клиента, относительно которого получен accessToken.

• requestUser (bool) – Если поле передано как true, то в ответе сервера будет присутствовать поле user.

Примечание

В оригинальном протоколе так же передаётся значение selectedProfile, но в реализации Mojang он не влияет ни на что. Наша реализация сервера авторизации игнорирует этот параметр и опирается на значения accessToken и clientToken.

В случае получения какой-либо предусмотренной ошибки, следует заново запросить пароль пользователя и произвести обычную авторизацию.

Успешный ответ:

{
    "accessToken": "Новая_длинная_строка_ содержащая_access_token",
    "clientToken": "Переданный_в_запросе_client_token",
    "selectedProfile": {
        "id": "UUID_пользователя_без_дефисов",
        "name": "Текущий_username_пользователя"
    },
    "user": { /* Только если передан параметр requestUser */
        "id": "UUID_пользователя_без_дефисов",
        "username": "Текущий_username_пользователя",
        "properties": [
            {
                "name": "preferredLanguage",
                "value": "ru"
            }
        ]
    }
}

POST /auth/validate

Этот запрос позволяет проверить валиден ли указанный accessToken или нет. Этот запрос не обновляет токен и его время жизни, а только позволяет удостовериться, что он ещё действительный.

Параметры

accessToken (string) – Токен доступа, полученный после авторизации.

Успешным ответом будет являться пустое тело. При ошибке будет получен 400 или 401 статус. Пример ответа сервера при отправке истёкшего токена:

{
    "error": "ForbiddenOperationException",
    "errorMessage": "Token expired."
}

POST /auth/signout

Этот запрос позволяет выполнить инвалидацию всех выданных пользователю токенов.

Параметры

• username (string) – Никнейм пользователя или его E-mail (более предпочтительно).

• password (string) – Пароль пользователя.

Успешным ответом будет являться пустое тело. Ориентируйтесь на поле error в теле ответа.

POST /auth/invalidate

Запрос позволяет инвалидировать accessToken. В случае, если переданный токен не удастся найти в хранилище токенов, ошибка не будет сгенерирована и вы получите успешный ответ.

Входные параметры:

Параметры

• accessToken (string) – Уникальный ключ, полученный после авторизации.

• clientToken (string) – Уникальный идентификатор клиента, относительно которого получен accessToken.

Успешным ответом будет являться пустое тело. Ориентируйтесь на поле error в теле ответа.

Авторизация на сервере

Эти запросы выполняются непосредственно клиентом и сервером при помощи внутреннего кода или библиотеки authlib (начиная с версии 1.7.2). Они актуальны только в том случае, если вы уже произвели авторизацию и запустили игру с валидным accessToken. Вам остаётся только заменить пути внутри игры/библиотеки на приведённые ниже пути.

Поскольку непосредственно изменить что-либо в работе authlib или игры вы не можете, здесь не приводятся передаваемые значения и ответы сервера. При необходимости вы сможете найти эту информацию самостоятельно в интернете.

Через authlib

Важно

Эта часть документации описывает запросы, выполняемые через authlib в версии игры 1.7.2+. Для более старых версий смотрите раздел ниже.

Все запросы из этой категории выполняются на подуровень /session. Перед каждым из запросов указан тип отправляемого запроса.

POST /session/join

Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true.

GET /session/hasJoined

Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключиться, успешно выполнит join запрос. Текстуры будут подписаны ключом Ely.by.

Ключ для проверки подписи можно получить через сервер системы скинов.

Внимание

В редких случаях поле signature будет иметь значение Cg==. При таком значении поля подписи проводить её проверку не нужно, т.к. она всегда будет некорректной.

Для старых версий

Важно

Эта часть документации описывает запросы, выполняемые более старыми версиями Minecraft, в которых не применялась библиотека Authlib. Это все версии ниже 1.7.2.

Все запросы из этой категории выполняются на подуровень /session/legacy. Перед каждым из запросов указан тип отправляемого запроса.

Принцип обработки этих запросов такой же, как и для authlib, отличие только во входных параметрах и возвращаемых значения.

GET /session/legacy/join

Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true.

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.

GET /session/profile/{uuid}

Запрос на этот URL выполняется клиентом в одиночной игре на локальном сервере (созданном посредством самой игры). В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока в таком же формате, как и при hasJoined запросе.

Готовые библиотеки authlib

Внимание

Ely.by поддерживает библиотеку authlib-injector. Это наиболее простой и универсальный способ установки системы авторизации в игру и игровые сервера. За подробностями обратитесь в соответствующий раздел документации.

Поскольку самостоятельная реализация связана с трудностями поиска исходников, подключения зависимостей и в конце-концов с процессом компиляции, на странице загрузок нашей системы скинов вы можете загрузить уже готовые библиотеки со всеми необходимыми изменениями. Выберите в выпадающем списке необходимую версию и следуйте инструкции по установке, размещённой на той же странице ниже.

В более ранних версиях игры система скинов находилась внутри игрового клиента, так что библиотеки ниже обеспечивают лишь авторизацию:

• Minecraft 1.7.5 - authlib 1.3.1

• Minecraft 1.7.2 - authlib 1.3

Для установки вам необходимо заменить оригинальную библиотеку, располагающуюся по пути <директория установки minecraft>/libraries/com/mojang/authlib/. Убедитесь в том, что версии скачанного и заменяемого файлов совпадают.

Установка authlib на сервер

Сервер также использует authlib для выполнения авторизации игрока, поэтому соответствующие изменения должны быть также применены и к нему. Ниже приведены инструкции по установки authlib для различных реализаций сервера Minecraft.

Примечание

Если ни одна из приведённых ниже инструкций не подошла для вашей реализации сервера, пожалуйста, создайте новый issue и мы допишем инструкцию для вашего сервера.

Оригинальный сервер

С помощью архиватора откройте файл сервера minecraft_server.ВЕРСИЯ.jar. Таким же образом откройте архив с authlib для соответствующей версии сервера. Перед вами будет два окна: одно с файлами сервера, другое с файлами authlib. Вам необходимо «перетащить» из архива с authlib все файлы и папки, за исключением директории META-INF, и подтвердить замену.

Обратите внимание: «перетягивать» содержимое нужно ниже папок сервера (в область файлов .class).

После этих действий вы можете закрыть оба окна и в файле server.properties установить значение online-mode=true.

Bukkit/Spigot

Сперва выполните установку, как она описана для оригинального сервера. Затем скачайте библиотеки commons-io и commons-lang3, после чего аналогичным с authlib образом последовательно переместите содержимое скачанных архивов в файлы сервера.

Forge/Sponge

Прежде чем производить установку, необходимо определить, какой именно файл подлежит модификации:

• >=1.16: libraries/net/minecraft/server/ВЕРСИЯ-ЦИФРЫ/server-ВЕРСИЯ-ЦИФРЫ-extra.jar.

• 1.13-1.15: libraries/net/minecraft/server/ВЕРСИЯ/server-ВЕРСИЯ-extra.jar.

• <=1.12: minecraft_server.ВЕРСИЯ.jar.

Когда необходимый файл найден, выполните для него установку authlib, аналогично оригинальному серверу.

Paper (PaperSpigot)

Установка производится по аналогии с Bukkit/Spigot в файл cache/patched-ВЕРСИЯ.jar. После внесения изменений, запускать сервер нужно через jar-файл из директории cache, поскольку в противном случае Paper восстановит исходное состояние файла:

До: java -jar paper-ВЕРСИЯ-БИЛД.jar

После: java -jar cache/patched-ВЕРСИЯ.jar

BungeeCord

Подсказка

Вы можете воспользоваться библиотекой authlib-injector для установки системы авторизации без модификации внутренностей сервера.

Хотя BungeeCord и является проксирующим сервером, авторизацию игроков он выполняет самостоятельно. К сожалению, BungeeCord не опирается на использование Authlib, а реализует процесс авторизации самостоятельно, поэтому для установки системы авторизации Ely.by вам понадобится модифицировать скомпилированные .class файлы.

Для установки следуйте инструкции ниже:

1. Скачайте программу InClassTranslator (прямых ссылок не даём, но его легко найти).

2. С помощью архиватора откройте файл BungeeCord.jar.

3. Перейдите по пути net/md_5/bungee/connection и найдите там файл InitialHandler.class (без каких-либо символов $).

4. Распакуйте этот файл. В самом простом случае сделать это можно просто «вытянув» его из окна архиватора.

5. Откройте распакованный файл в программе InClassTranslator и замените в нём строку https://sessionserver.mojang.com/session/minecraft/hasJoined?username= на https://authserver.ely.by/session/hasJoined?username=, как показано на рисунке ниже:

   

6. Сохраните изменения и перетащите измененный файл обратно в архив сервера. Подтвердите замену.

   

После выполнения этих действий вы можете указать в файле конфигурации BungeeCord (config.yml) значение online_mode=true.

Важно

Мы также рекомендуем выполнить установку Authlib на все сервера позади BungeeCord. Это может быть необходимо для плагинов, которые используют API Mojang. Инструкция по установке на конечные сервера приведена выше.

При этом все сервера должны иметь в своей конфигурации (server.properties) значение online-mode=false, поскольку пользователи уже авторизованы силами BungeeCord.

Установка на версии ниже 1.7.2

Для более старых версий существует достаточно большое многообразие различных случаев, раскрыть которые в этой документации не представляется возможным. Вся установка заключается в замене определённых строк в определённых классах через InClassTranslator.

На форуме RuBukkit есть отличный пост, в котором собрана вся нужна информация по именам классов на различных версиях Minecraft. Переписывать его сюда не имеет смысла, так что просто перейдите на его страницу и найдите нужную версию.

RuBukkit - Список классов и клиентов для MCP.

Пример установки

Предположим, что вы хотите установить авторизацию на сервер версии 1.5.2.

Сначала вы переходите по вышеприведённой ссылке, выбираете нужную версию (1.5.2) и видите список классов:

• bdk.class - путь до joinserver

• jg.class - путь до checkserver

Затем вы должны взять .jar файл клиента и открыть его любым архиватором. После чего вам необходимо найти файл bdk.class. Для этого удобно воспользоваться поиском.

После того, как вы нашли файл, его нужно извлечь из архива - просто перетащите его оттуда в удобную для вас дирикторию.

Дальше запустите InClassTranslator и в нём откройте этот класс. Слева будет список найденных в файле строк, которые вы можете изменить. Нужно заменить только строку, отвечающую за запрос на подключение к серверу:

После этого вам нужно положить изменённый .class обратно в .jar файл игры.

Ту же самую операцию вам необходимо провести и с сервером, только заменить ссылку на hasJoined.

---

После этих действий вам нужно в настройках включить online-mode=true и сервер станет пускать на себя только тех игроков, которые будут авторизованы через Ely.by.