CraftLDAP

CraftLDAP

Мод для Minecraft, добавляющий вайтлист на основе LDAP

Craft-что?

LDAP — это своего рода многоплатформенный индекс пользователей. Он позволяет использовать один логин и пароль для множества сервисов и делает ваши различные личные данные (такие как имя и фамилия, отображаемое имя пользователя, контакты (email и/или телефон), аватар и т. д.) общими для этих сервисов. Основные пользователи LDAP:

• Самохостинг-гики (тип людей, которые запускают собственный NextCloud, федеративные штуки (Matrix, Mastodon, email и т. д.), сайт, Git-хостинг и прочее), желающие большей интеграции между всем, что они запускают.
• Организации (такие как компании, школы, НКО, госструктуры и т. д.), которые часто используют несколько внутренних приложений (например, программу учёта инвентаря, электронный журнал или систему голосования) и интегрируются с некоторыми внешними сервисами (например, Microsoft Teams), и для которых такая форма интеграции может означать тысячи сэкономленных средств на административных расходах (вместо обновления нескольких баз данных пользователей каждый раз, когда кого-то нанимают или кто-то уходит, им нужно изменить только одну). Следовательно, этот мод нацелен на:
• Людей, одержимых интеграцией и автоматизацией (как ваша покорная слуга), которые уже запускают свой самохостинг-стек, включая LDAP, и абсолютно НЕ МОГУТ смириться с мыслью, что их самостоятельно размещённый сервер Minecraft полностью оторван от их прекрасного клубка взаимосвязанных сервисов.
• Школы/университеты и т. п., которые запускают собственные серверы Minecraft. Эта тенденция стала популярной во времена Covid (даже школа автора этого мода была в это вовлечена, и она на самом деле была в команде разработчиков — хотя та школа использовала OAuth через Microsoft Services для центрального входа вместо LDAP, и поэтому их система входа в Minecraft была построена вокруг Discord-бота, интегрированного с этим OAuth, из-за чего этот мод появился только сейчас) и — в крошечной степени — по-видимому, всё ещё жива (если верить этому видео на YouTube). Если вы — какое-то учебное заведение (или любое учреждение, если на то пошло), которое всё ещё поддерживает это пламя, и вы также используете LDAP в качестве реестра студентов — пожалуйста, милости прошу! (К тому же, у вас наверняка куча денег, так что... Спонсорство, может быть? UwU :3) Напротив, этот мод НЕ нацелен на:
• Людей, которым нужен только быстрый и простой способ синхронизировать вайтлисты между серверами. Для этого обратите внимание на WhileList Sync 2 — он требует гораздо меньше накладных расходов, настройки и обслуживания по сравнению с запуском целого LDAP-сервера.
• Всех, у кого нет LDAP-сервера и кто хочет использовать этот мод для обучения его настройке. Этот мод был бы довольно ужасным введением в LDAP, так как документация умалчивает о некоторых важных частях того, как всё это работает; она также разбрасывает технический жаргон направо и налево и вставляет случайные тирады о CurseForge и плагинах Minecraft. Вам было бы гораздо лучше попробовать настроить что-то вроде LLDAP (самый простой LDAP-сервер из существующих) вместе с одним из их официально поддерживаемых потребителей, следуя одному из их руководств по настройке.
• ...Проще говоря, если вам пришлось прочитать этот раздел «Craft-что?», чтобы понять этот мод, то вы, вероятно, не его целевая аудитория.

Скачать

• С Modrinth
• На GitHub, пожалуйста, соберите из исходников или скачайте релиз.
• Поддержка CruseForge не планируется.

Установка

• Прежде чем что-либо делать, подготовьте ваш LDAP-сервер для нового потребителя. Пожалуйста, обратитесь к разделу ниже.

• Настройте себе сервер Minecraft на базе Fabric/Quilt (не Forge/NeoForge (по крайней мере, пока — возможно, когда-нибудь я перепишу этот мод на Architectury для поддержки нескольких загрузчиков, например, когда мне захочется захостить сервер на (Neo)Forge, или если будет большой спрос — о котором можно сообщить, открыв issue), не на плагинах (не планируется (как по «идеологическим» причинам (загрузчики плагинов — магниты для споров, а их мейнтейнеры в целом производят впечатление не самых приятных людей (обратитесь к... любой гневной тираде редстоунщика про PaperMC (большинство за карьеру написали хотя бы одну) за подробностями), так и из-за всей этой истории с «Bukkit сам себя взорвал», которая привела нас к нынешнему аду форков, и (как следствие) мне не особо хочется поддерживать ту экосистему; в то же время Fabric с Lithium, Noisium, ServerCore и парой других модов на оптимизацию/исправление багов может приблизиться к этим «профессиональным, сверхбыстрым» серверным бэкендам по производительности или даже превзойти их, но ему не хватает некоторых приятных эксклюзивных плагинов (например, WorldGuard), так что мне нравится идея «уравновесить» это уравнение, делая эксклюзивы на основе модлоадеров) и практическим причинам (мне нравится писать код на Fabric/Architectury; возвращаться к Bukkit — тоска)), если только не будет большого спроса — о котором можно сообщить, открыв issue), и не на ванильном Minecraft (по очевидным причинам). Клиент не поддерживается, потому что нет ни одной разумной причины когда-либо захотеть этот мод на клиенте (хотя — концептуально — он МОГ БЫ там работать без изменений; просто поменяйте сторону в fabric.mod.json этого мода внутри JAR). Мод ориентирован на новейшую стабильную версию Minecraft (на момент написания это 1.21.11), но (если этот проект когда-нибудь заленится с обновлениями, как многие другие) наши dependencies указывают, что любая более новая версия сервера тоже должна работать (поскольку этот мод на самом деле полагается всего на 4 ванильных класса, которые вряд ли изменятся в ближайшем будущем — по крайней мере, в том, что касается нашего их использования). Если вы найдёте версию, помеченную как поддерживаемая, но она не работает, пожалуйста, создайте issue. Если вы хотите использовать более низкую версию или снапшот, можете воспользоваться Dependency Overrides в Fabric, но делаете это на свой страх и риск!
• Поместите JAR этого мода и JAR FabricAPI (или JAR Quilted FabricAPI, если он наконец вышел для современной версии MC — если нет, то Quilt, увы, пока нельзя использовать с этим модом, дайте им пару месяцев/лет, чтобы догнать) в папку mods вашего сервера.
• Запустите его!

Использование

Сначала стоит объяснить, КАК этот мод на самом деле работает: каждый раз, когда игрок входит в игру, мод проверяет, есть ли у какого-либо LDAP-пользователя (из числа подходящих под заданный пользователем фильтр, вероятно, что-то вроде группы minecraft) в качестве атрибута привязан Minecraft UUID этого игрока. Если совпадение найдено, игрок входит в игру «как» этот LDAP-пользователь. Если совпадение не найдено, попытка входа игрока отклоняется. Как видите, это НЕВЕРОЯТНО простая схема. Здесь нет команды /login или чего-то подобного. По сути, это работает как белый список на основе LDAP. В будущем мы также планируем подтягивать некоторые дополнительные атрибуты из LDAP в Minecraft (например, уровень прав оператора и т. д.), а также добавить несколько служебных команд (для перезагрузки конфига на лету, просмотра своего LDAP-пользователя прямо в игре и, может быть, кое-чего ещё — в частности, команда /login или подобная ей никогда не появится по задумке, см. ниже), но это ещё впереди.

В LDAP

1. Вам нужно создать ещё один атрибут — тот, который будет хранить Minecraft UUID пользователя, в вашей схеме пользователя. Рекомендуется назвать его mcuuid, чтобы не пришлось менять конфиг по умолчанию.
2. Вам ОЧЕНЬ СТОИТ (но технически не обязательно, подробнее об этом ниже) создать хотя бы одну новую группу для игроков Minecraft. Если вы хостите несколько серверов и не хотите, чтобы пользователи одного сервера смешивались с пользователями другого, можете также создать несколько групп. Или — если вы хотите независимо контролировать, является ли кто-то игроком Minecraft и на какой сервер он может заходить — можете создать «общую группу» и подгруппы для каждого сервера (и настроить фильтр каждого сервера (подробнее об этом ниже) так, чтобы он проверял наличие в обеих). В общем, в плане группировки возможности безграничны. Просто знайте, что должен быть способ однозначно отличить игроков от не-игроков (подробнее об этом ниже).
3. Дайте своим пользователям какой-нибудь способ указать свой Minecraft UUID. Это просто, если вы используете сервер вроде LLDAP, где есть веб-интерфейс, в котором любой пользователь может редактировать свои атрибуты. Просто отметьте атрибут mcuuid как редактируемый пользователем, опубликуйте руководство по конвертации ника в UUID (например, ссылку на NameMC) — и дело в шляпе. Если ваша система LDAP не предоставляет удобного способа самостоятельного редактирования, вы предоставлены сами себе. Скорее всего, вы уже используете какой-нибудь дополнительный инструмент для управления LDAP (хотя бы для аватарок и смены паролей), так что, возможно, сможете расширить его, чтобы разрешить изменение ещё одного атрибута. Если нет (то есть вы явно разрешаете изменять записи LDAP только уполномоченному персоналу), вам придётся либо поручить персоналу вручную добавлять UUID ваших пользователей, либо создать какой-нибудь внутренний фронтенд для автоматизации этого. Этот проект предоставляет доступ к LDAP только для чтения, и это сделано намеренно (он задуман совместимым с LLDAP, который для любого внешнего сервиса работает только на чтение, позволяя вносить изменения лишь через свой WebUI), так что здесь нет — и никогда не будет — чего-то вроде команды /login для добавления записи прямо из игры.

В самом моде

После первого запуска в [папка сервера]/config/ldap.properties будет создан файл конфигурации. Он должен выглядеть примерно так:

#Файл конфигурации для CraftLDAP. Документацию смотри на странице Modrinth или в README на GitHub.
#[CREATION DATE]
base-dn=ou\=people,dc\=example,dc\=com
bind-dn=cn\=[какой-нибудь пользователь, который может читать индекс],ou\=people,dc\=example,dc\=com
bind-pass=[пароль этого пользователя]
bugreport-url=https\://example.com/
filter=(&(objectclass\=person)(memberOf\=cn\=[какая-нибудь группа],ou\=groups,dc\=example,dc\=com))
host=ldap
ldap-attr-mcuuid=mcuuid
ldap-attr-name=uid
message-error=Что-то пошло не так с авторизацией CraftLDAP. ЭТО НЕ ВАША ВИНА, пожалуйста, сообщите об этой ошибке администратору сервера!!!
message-unauthorized=У вас нет прав играть на этом сервере.
port=3890

Поля означают следующее:

1. base-dn: Понятия не имею, что это делает. Значение выше (то есть ou=people,dc=example,dc=com, где example.com заменяется на ваш собственный домен, например guziohub.ovh -> ou=people,dc=guziohub,dc=ovh) взято прямо из документации LLDAP, и оно работает для Matrix, UnboundID (это библиотека, которую CraftLDAP использует внутри) и Nextcloud. Просто поменяйте домен, помня, что все = нужно экранировать как \= (как видно выше), и всё будет хорошо. Впрочем, если вы достаточно продвинутый LDAP-админ, который знает, как работает Base DN, и вы по какой-то причине изменили это поведение на своём сервере, вы наверняка знаете, как обновить это и здесь.
2. bind-dn — это ваш «сервисный логин». Если у вас есть пользователь с именем admin, который может читать всех остальных пользователей LDAP (или пользователь с именем minecraftservice, который может читать всех пользователей, связанных с Minecraft), и ваш домен — guziohub.ovh или someuniversity.gov, вы укажете это здесь так: cn=admin,ou=people,dc=guziohub,dc=ovh или cn=minecraftservice,ou=people,dc=someuniversity,dc=gov. Только помните, что = нужно экранировать, так что на самом деле получится: cn\=admin,ou\=people,dc\=guziohub,dc\=ovh или cn\=minecraftservice,ou\=people,dc\=someuniversity,dc\=gov
3. bind-pass — это пароль для пользователя, указанного выше в bind-dn. Однако учтите, что просто вставлять пароли в открытом виде — не лучшая практика безопасности. Настоятельно рекомендуется использовать какой-нибудь менеджмент секретов. Один из способов — запускать сервер с помощью этого Docker-образа, следуя их руководству по подстановке переменных окружения.
4. bugreport-url — это корректный URI (только не забудьте экранировать :, как выше), который передаётся клиенту, если его попытка входа отклонена из-за ошибки CraftLDAP. НЕ следует указывать его напрямую на CraftLDAP — пожалуйста, пусть пользователи сначала сообщают о проблемах вам, так как скорее всего то, что происходит, вызвано вашей настройкой. Даже если это не так, эта ошибка не говорит нам абсолютно ничего, ведь все «ценные» логи находятся на вашем сервере. Поэтому, даже если баг вызван самим CraftLDAP, сообщение о проблеме всё равно должно сначала идти к вам, и только потом (если вы застряли при отладке или обнаружили баг в CraftLDAP) стоит открывать issue, дав нам больше информации, чем когда-либо мог бы дать пользователь. Учтите, что, похоже, хотя клиенты и ожидают это поле данных, сейчас они его не отображают в интерфейсе. Можно было бы ожидать кнопку «сообщить о баге» на экране отключения или что-то в этом роде, но, похоже, пока это не так. Возможно, это добавили в подготовке к будущему обновлению, не знаю.
5. filter, ldap-attr-mcuuid и ldap-attr-name будут описаны позже, так как для понимания связи между ними требуется особая внимательность.
6. host и port вместе образуют URI вашего LDAP-сервера. Например, если он доступен по ldap://example.com:3890, то host будет example.com, а port — 3890. port должен быть числом, а host может быть публичным (например, example.com) или локальным (например, ldap — значение по умолчанию) доменным именем либо IP-адресом.
7. message-error отправляется клиенту, если его попытка входа отклонена из-за ошибки CraftLDAP. Действуют те же «правила», что и с bugreport-url (то есть просите сообщать вам, а не нам).
8. message-unauthorized отправляется клиенту, если его попытка входа отклонена из-за того, что его UUID не найден привязанным ни к одному пользователю на вашем LDAP-сервере.

Разбор фильтров

На вашем LDAP-сервере может быть много пользователей. Некоторые из них могут не быть игроками Minecraft — и, соответственно, у них явно нет Minecraft UUID. Это очень плохо для CraftLDAP, потому что он ожидает, что атрибуты, указанные в ldap-attr-mcuuid (здесь хранится имя вашего атрибута Minecraft UUID, например mcuuid, как описано выше) и ldap-attr-name (здесь хранится имя атрибута, значение которого выводится в консоль сервера, когда кто-то успешно заходит; по умолчанию это uid, который является атрибутом логина в LLDAP, но вы можете захотеть установить его в значение логина вашего собственного LDAP-сервера или даже вообще не использовать логины, полагаясь, например, на display-names), будут присутствовать у каждого пользователя LDAP, которого он просматривает. Какое решение? Мы следим за тем, чтобы он никогда не просматривал тех пользователей, у которых этих атрибутов может не быть!

Введите фильтры: они ограничивают результаты LDAP-запроса лишь подмножеством пользователей. Самый важный фильтр — memberOf, который позволяет фильтровать по принадлежности к группе. Именно он даст вам гарантию, что ни один пользователь без нужных атрибутов не проскочит: можно создать группу для игроков Minecraft и добавлять в неё только тех, у кого с атрибутами всё в порядке. Если вы выполнили шаг 2 руководства по использованию LDAP, эта группа у вас уже должна быть. Чтобы её использовать, просто замените [some group] на имя этой группы (а также обновите example.com на свой домен и не забудьте экранировать = — но это вы уже должны знать). Например: (&(objectclass\=person)(memberOf\=cn\=minecraft,ou\=groups,dc\=guziohub,dc\=ovh)).

Фильтры также можно выстраивать в цепочки, что даёт невероятную гибкость. Точный синтаксис здесь объясняться не будет (это лучше подходит для отдельной статьи), только некоторые идеи. Например, можно использовать несколько групп в конфигурации с несколькими серверами — 2 концепции для этого приведены в шаге 2 руководства по настройке LDAP. Можно также создать «основную» группу Minecraft и группу администраторов Minecraft и фильтровать по наличию в любой из них на основном сервере, но только по админам на dev-сервере. Или можно перевернуть отношение с ног на голову: опираться на существующую группу админов в LDAP и фильтровать по ней + minecraft в конфиге dev-сервера, но проверять только minecraft на продакшн-сервере. Чёрт, можно вообще игнорировать фильтры! Просто пометьте оба атрибута как всегда обязательные и не возитесь с настройкой групп для «тех, у кого они есть» и «тех, у кого их нет». Возможно также задать фильтр, проверяющий наличие заданного атрибута вместо использования группы, но это требует дальнейшего тестирования. В целом — простор безграничен! LDAP-фильтры умеют многое.

Лицензия

• Код и бинарники лицензированы под MIT. Бинарник также включает JAR с библиотекой UnboundID LDAP, лицензированной под Apache2.
• Да, это значит, что вы можете использовать это в модпаках (Если... Вам зачем-то это понадобилось. По... Какой-то причине. Нет, серьёзно, если только это не приватный пак для конкретного сообщества, и у этого сообщества случайно нет LDAP-сервера — зачем вам это вообще?). Да, даже в паках за пределами Modrinth — хотя (чтобы соблюсти требования лицензии MIT) вам нужно будет указать этот мод, «включив его лицензию в производную работу». В идеале это простая ссылка на лицензию с именем автора и названием мода прямо в сноске о лицензии в README вашего пака (как эта) — а не закопанная на два слоя ZIP-архивов (сначала пак, потом мод), даже если это технически всё ещё включение.
• Не перезаливайте (или не перекомпилируйте+заливайте, если только не были внесены значительные изменения (и/или этот мод не заброшен и вы хотите поддерживать его актуальным), в рамках полного форка) этот мод как есть на другие хостинги, в частности на 9Minecraft (*включая вирус, это не считается «значительными изменениями») или CurseForge. Нет, CurseForge, мне плевать, насколько технически законно это было бы по MIT. Если вы отказываетесь удалять чьи-либо подделки, то позвольте мне назвать эту маленькую строчку текста «юридически обязывающей» (Потому что она технически говорит «Лицензия» выше, так можем ли мы быть уверены, что она не так же действительна, как файл LICESNE на GitHub или привязанная лицензия на Modrinth? В смысле... Конечно, нет (это всего лишь пояснительная сноска), но — знаете ли — можете ли вы действительно быть уверены?) и посмотрим, как вы запоёте...
• Логотип вдохновлён официальной иконкой LDAP (в той мере, в какой «4 треугольника цвета R203G32B38, накрывающих друг друга»), но в остальном это собственная работа CraftLDAP (как в замысле (то есть: это была моя идея — превратить их в пиксель-арт определённым образом, сделать их остроконечными и добавить инициалы C.L. для CraftLDAP), так и в исполнении — он нарисован с нуля) от начала и до конца, и как таковой он (в форме как PNG, так и исходников Krita) лицензирован под CC BY-NC-ND 4.0 (извините за чрезмерную строгость, мы более чем готовы снизить это до CC BY-SA 4.0 (что-то вроде GPL для изображений; я даже включил исходники Krita именно для этой цели), если найдутся желающие его изменить — только пообещайте, что не воспользуетесь этим правом, чтобы выдавать себя за нас). Коммерческим использованием в данном случае будет любая «выдача себя за нас» (поскольку — даже если это не ведёт к прямой финансовой выгоде — это может каким-то образом повысить ваш статус на какой-нибудь платформе, что может привести к «коммерческому преимуществу», не разрешённому лицензией). Также — раз уж речь о выдаче себя за других — вы не можете переиспользовать имя CraftLDAP (по крайней мере, добавьте какой-нибудь суффикс или что-то такое) для любого форка или (особенно) не связанных проектов.

Вот и всё!

Надеюсь, вам понравится этот дурацкий маленький проект :3