Minecraft Session Validator

Описание

Minecraft Session Validator — это сервис, предназначенный для прохождения первых этапов входа на Minecraft сервер. Как и mc-oauth, он предназначен для использования в сторонних проектах. Однако, в отличие от mc-oauth, он реализует клиентскую часть, а не сервер. Для выполнения запроса необходимо передать accessToken сессии Minecraft, никнейм, UUID, а также данные о сервере.

---

Как это работает?

Основные функции

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

Процесс входа

Сервис реализует клиентскую сторону фазы логина Minecraft Protocol:

1. Через REST API создается запрос с данными клиента и сервера.
2. Сервис авторизуется через серверы Mojang, чтобы подтвердить лицензионность сессии.
3. После прохождения необходимых этапов авторизации и подключения к серверу клиент отключается, возвращая в API данные, полученные от сервера.

Сервис намеренно не реализует пакет login_acknowledged, чтобы исключить возможность полного входа на сервер.

Если подключение невозможно (например, из-за невалидной сессии или других ошибок), сервис возвращает подробное описание ошибки.

Основные сценарии использования

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

---

Особенности реализации

Этот сервис не должен быть доступен публично, для предотвращения DoS атак на сервера Minecraft. Вместо этого, он должен быть запущен на локальном интерфейсе, а доступ к нему должен осуществляться через другой API враппер.

Обращения к врапперу должен производить Minecraft мод, который так же будет осуществлять аутентификацию на уровне API враппера. Мод должен получить у клиента accessToken, имя пользователя и его UUID и отправить на промежуточный API. API, в свою очередь должен сделать POST запрос на этот сервис с данными, которые он получил от клиента.

Warning

НАШ СЕРВИС НЕ СОБИРАЕТ ВАШИ ЛИЧНЫЕ ДАННЫЕ! ВСЕ ТОКЕНЫ ДОСТУПА УДАЛЯЮТСЯ СРАЗУ ПОСЛЕ ВЫПОЛНЕНИЯ ПОПЫТКИ ПОДКЛЮЧЕНИЯ К СЕРВЕРУ. ТАКЖЕ СЕРВИС НЕ МОЖЕТ ПОДКЛЮЧИТЬСЯ К СЕРВЕРУ ВМЕСТО ВАС, ТАК КАК ЭТО НЕ ВХОДИТ В ЕГО ЗАДАЧИ. ОДНАКО МЫ НЕ НЕСЕМ ОТВЕТСТВЕННОСТИ ЗА ВСЕ СТОРОННИЕ МОДИФИКАЦИИ НАШЕГО СЕРВИСА, СТОРОННИЕ API ИЛИ МОДЫ! ВСЕ ДОВЕРЕННЫЕ ПРОЕКТЫ, КОТОРЫЕ ДОБРОСОВЕСТНО ВЫПОЛНЯЮТ ТРЕБОВАНИЯ КОНФИДЕНЦИАЛЬНОСТИ НАШИХ ПОЛЬЗОВАТЕЛЕЙ БУДУТ ОПУБЛИКОВАНЫ В САМОМ КОНЦЕ ЭТОГО ФАЙЛА.

---

Работа с API

Для выполнения запроса сделайте POST запрос на эндпоинт /connect с JSON в теле:

{
    "accessToken": "<accessToken>",
    "nickname": "AndcoolSystems",
    "UUID": "1420c63c-b111-4453-993f-b3479ba1d4c6",
    "server": {
        "ip": "mycoolserver.net",
        "port": 25565,
        "protocolVersion": 769
    }
}

Поля запроса:

• accessToken — Токен сессии Minecraft (Можно получить через MinecraftClient.getInstance().getSession().getAccessToken() в Fabric).
• nickname — Никнейм аккаунта, совпадающий с никнеймом в профиле Minecraft.
• UUID — UUID аккаунта Minecraft (обязательно с тире).
• server — Объект с информацией о сервере:
  • ip — IP-адрес или доменное имя сервера.
  • port — Порт сервера.
  • protocolVersion — Версия протокола (доступна здесь).

Примечание: Возможны проблемы с SRV записями в DNS. Убедитесь, что порт совпадает с портом в записи.

Пример успешного ответа

Код ответа 200 указывает на успешную авторизацию и подключение:

{
    "nickname": "AndcoolSystems",
    "UUID": "1420c63c-b111-4453-993f-b3479ba1d4c6"
}

Ошибки

Ошибки парсинга JSON Body

• 422 — Неправильный формат JSON:

  {
      "message": "Couldn't parse JSON body"
  }

• 400 — Отсутствует обязательное поле:

  {
      "message": "Field with key `{key}` not found"
  }

Ошибки при входе

• Ошибка авторизации через Mojang:

  {
      "message": "Mojang API error"
  }

• Ошибка подключения к серверу:

  • 500 — Истекло время ожидания ответа от сервера или сервер прервал соединение без сообщения:

    {
        "message": "Server unexpectedly closed the connection"
    }

  • 400 — Хост не может быть разрешен:

    {
        "message": "Unknown host"
    }

• Отключение от сервера: Код статуса всегда 403

  {
      "cause": "Whitelist",
      "raw": "You not whitelisted on this server!"
  }

  Ключ raw содержит сырое сообщение, которое было получено от сервера.
  Ключ cause содержит предполагаемую причину отключения. Так как сервера могут быть настроены по-разному, причина может отражать неправильную информацию. Если определить причину не получается, он будет иметь значение Disconnected.

---

Warning

ЭТОТ ПРОЕКТ НАХОДИТСЯ В РАННЕЙ БЕТЕ И ОШИБКИ БУДУТ ИСПРАВЛЯТЬСЯ В ПРОЦЕССЕ РАЗРАБОТКИ!

---

by AndcoolSystems with ❤, January 8, 2025