Ely by ошибка

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

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

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

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

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

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

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

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

POST /auth/authenticate

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

Parameters

• 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 для практически бесконечной возможности проходить авторизацию.

Parameters

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

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

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

Note

В оригинальном протоколе так же передаётся значение 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 или нет. Этот запрос не обновляет токен и его время жизни, а только позволяет удостовериться, что он ещё действительный.

Parameters

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

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

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

POST /auth/signout

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

Parameters

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

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

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

POST /auth/invalidate

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

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

Parameters

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

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

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

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

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

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

Одиночная игра¶

По сути, одиночная игра — это локальный сервер, созданный для одного игрока. По крайней мере это так, начиная с версии 1.6, в которой и был представлен механизм локальных серверов.

Тем не менее, описанный ниже запрос актуален только для Minecraft 1.7.6+, когда для загрузки скинов стала использоваться так же Authlib.

GET /session/profile/{uuid}

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

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

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

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

• Minecraft 1.7.5 — authlib 1.3.1

• Minecraft 1.7.2 — authlib 1.3

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

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

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

BungeeCord¶

Хотя 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.

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

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

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

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