
CraftLDAP
基于LDAP的Minecraft白名单模组
CraftLDAP
基于 LDAP 的 Minecraft 白名单模组
Craft-什么?
LDAP 是一种多平台的用户索引。它允许一个登录名+密码在多个服务间通用,并让你各种各样的个人数据(比如名字和姓氏、显示用用户名、联系方式(邮箱和/或电话)、头像等)在这些服务之间共享。
LDAP 的主要用户是:
- 自托管爱好者(那种会自己搭建 NextCloud、联邦式服务(Matrix、Mastodon、电子邮件等)、网站、Git 托管等的人),他们希望自己运行的所有东西之间能有更深的集成。
- 组织(比如公司、学校、非政府组织、政府等),它们通常运行多个内部应用(例如库存追踪程序、电子成绩册或投票系统),并与一些外部服务(例如 Microsoft Teams)集成,而对它们来说,这种集成形式可能意味着节省数千美元的管理成本(不必每次有人入职/离职时更新多个用户数据库,只需改动一个)。
因此,本模组面向的是:
- 痴迷于集成与自动化的人(比如笔者本人),他们已经在运行自己的自托管栈(包括 LDAP),并且绝对无法忍受自己自托管的 Minecraft 服务器与那堆美妙地相互交织的服务完全脱节。
- 自建 Minecraft 服务器的高中/大学等机构。这一潮流在新冠疫情期间流行起来(甚至本模组的作者所在的学校也参与其中,而她实际上就在其背后的开发团队里——不过那所学校用的是 Microsoft 服务的 OAuth 来做集中登录而非 LDAP,所以他们的 Minecraft 登录系统围绕着一个集成了该 OAuth 的 Discord 机器人构建,这也是本模组直到现在才问世的原因)——而且据说(如果这个 YouTube 视频可信的话)这一潮流在某种程度上依然存在。如果你是某个仍在延续这一火种的教育机构(或任何机构),并且恰好使用 LDAP 作为学生名册——请便,尽管用!(另外,你们大概钱多得是,所以……赞助一下,也许?UwU :3)
相反,本模组并不面向:
- 只需要一种快速简单的方式来在多个服务器间同步白名单的人。请看看 WhileList Sync 2——与运行一整个 LDAP 服务器相比,它所需的开销、配置和维护要少得多。
- 任何没有 LDAP 服务器、想借本模组来学习如何搭建一个的人。本模组会是个相当糟糕的 LDAP 入门,因为文档略过了一些关于整套东西如何运作的主要部分;它还左一个右一个地塞了一堆技术术语,并且穿插着关于 CurseForge 和 Minecraft 插件的随机吐槽。你最好去尝试搭建 LLDAP(最简单的 LDAP 服务器)之类的东西,并搭配其官方支持的某个消费者,按照他们的某份配置指南来做。
- ……简单来说,如果你得读这个“Craft-什么?”章节才能理解本模组,那你大概不是它的目标受众。
下载
- 从 Modrinth 下载
- 在 GitHub 上,请从源码构建或下载一个发布版。
- 不计划支持 CurseForge。
安装
- 在做任何事之前,先为你的 LDAP 服务器准备好接纳一个新的消费者。 请参阅下面的章节。
- 给自己配置一个基于 Fabric/Quilt** 的 Minecraft 服务器**(不是 Forge/NeoForge(至少目前还不是——以后某个时候我可能会用 Architectury 重写本模组以实现多加载器支持(即:等到哪天我想在 (Neo)Forge 上自托管服务器时,或者如果有足够多的人要求——你可以通过开 issue 来表达),也不是基于插件的(不计划(既是出于“意识形态”原因(因为插件加载器是争议磁铁,某些主要插件加载器的维护者总体上给人的印象有点像混蛋(请参考……任何一个 Redstoner 关于 PaperMC 的吐槽(大多数人职业生涯中至少会做一次)以了解更多),还有那桩“Bukkit 把自己炸了”的事把我们带进了今天的 fork 地狱,因此我并不特别期待去支持那个生态;与此同时,Fabric 搭配 Lithium、Noisium、ServerCore 以及其他几个优化/修 bug 模组,在性能上可以接近甚至超越那些“专业的、超快的”服务器后端,但缺少一些好用的独占插件(例如 WorldGuard),所以我喜欢通过做基于模组加载器的独占功能来“平衡”这个等式),也是出于实际原因(我喜欢在 Fabric/Architectury 里写代码;回到 Bukkit 感觉糟透了)),除非有足够多的人要求——你可以通过开 issue 来表达),也不是原版 Minecraft(原因显而易见))。不支持客户端,因为你绝不会有什么正当理由想把这个模组装在客户端上(不过——从概念上讲——它不做修改也能在客户端工作;只需在 JAR 里本模组的
fabric.mod.json中改一下 side 即可)。本模组瞄准最新的稳定 Minecraft 版本(撰写时为 1.21.11),但(万一本项目哪天在更新上变懒了,就像许多项目那样)我们的dependencies指定任何更新的服务器版本也应该能用(因为本模组实际上只依赖 4 个原版类,而它们短期内不太可能改变——至少就我们对它们的使用而言)。如果你发现某个被标记为支持的版本却不能用,请提交 issue。如果你想用更低的版本或快照,你可以使用 Fabric 的 Dependency Overrides,但风险自负! - 把本模组的 JAR 和 FabricAPI 的 JAR(或 Quilted FabricAPI 的 JAR,如果它终于为现代 MC 版本发布了的话——如果没有,那很遗憾,Quilt 暂时还不能与本模组一起使用,请给他们几个月/几年时间追赶)放进服务器的
mods文件夹。 - 启动它!
用法
首先,我们应该解释本模组实际是如何工作的:每当有玩家登录时,它会检查是否有任何 LDAP 用户(在匹配用户指定过滤器的那些用户之中,过滤器大概是类似 minecraft 组这样的东西)把该玩家的 Minecraft UUID 作为某个属性附加在自己身上。如果找到匹配,玩家就“以”该 LDAP 用户的身份登录。如果没找到匹配,玩家的登录尝试就被拒绝。
如你所见,这是一个极其简单的流程。没有 /login 命令或任何类似的东西。它本质上就像一个由 LDAP 支撑的白名单。将来,我们还计划从 LDAP 拉取一些额外属性到 Minecraft(比如 OP 权限等级等),并添加一些实用命令(用于热重载配置、在游戏内查看你自己的 LDAP 用户,以及一些其他东西,也许——值得注意的是,按设计 /login 命令或类似物永远不会出现,见下文),但那是以后的事。
在 LDAP 中
- 你需要在你的用户 schema 中再创建一个属性,用来存放用户的 Minecraft UUID。建议把它叫做
mcuuid,以免不得不改动默认配置。 - 你非常应该(但技术上并非必需,详见下文)至少创建一个新组,用于 Minecraft 玩家。 如果你托管多个服务器,且不希望一个服务器的用户混进另一个,你也可以创建多个组。或者——如果你想独立控制某人是否为 Minecraft 玩家以及他们能加入哪个服务器——你可以创建一个“总组”和每服务器的子组(并调整每个服务器的过滤器(详见下文)以查找两者中的成员资格)。总的来说,就分组而言,天高任鸟飞。只要知道应该有一种方法能明确区分玩家和非玩家(详见下文)。
- 给你的用户提供某种指定其 Minecraft UUID 的方式。 如果你运行的是 LLDAP 这类服务器,这很简单,因为它有一个 Web UI,任何用户都能在其中编辑自己的属性。只需把你的
mcuuid属性标记为用户可编辑,发一份关于如何把昵称转换为 UUID 的指南(比如一个 NameMC 链接),就大功告成了。如果你的 LDAP 系统没有提供用户友好的自助编辑方式,那你就得靠自己了。最有可能的是,你已经在运行某个额外的 LDAP 管理工具(至少用于头像和密码修改),所以也许你可以扩展它,允许修改一个额外属性。如果不行(即你明确只允许授权的员工修改 LDAP 记录),你要么需要指示你的员工手动添加用户的 UUID,要么需要构建某种内部前端来自动化这件事。本项目提供对 LDAP 的只读访问,这是有意为之的(它旨在兼容 LLDAP,而 LLDAP 对任何外部服务都是只读的,只允许通过其 WebUI 修改),所以不会有——也永远不会有——类似/login命令来从游戏内添加记录的功能。
在模组本身中
首次启动后,会在 [服务器目录]/config/ldap.properties 生成一个配置文件。它应该看起来像这样:
#Config file for CraftLDAP. Refer to the Modrinth-page or GitHub README for documentation.
#[CREATION DATE]
base-dn=ou\=people,dc\=example,dc\=com
bind-dn=cn\=[some user that can read the index],ou\=people,dc\=example,dc\=com
bind-pass=[the password of that user]
bugreport-url=https\://example.com/
filter=(&(objectclass\=person)(memberOf\=cn\=[some group],ou\=groups,dc\=example,dc\=com))
host=ldap
ldap-attr-mcuuid=mcuuid
ldap-attr-name=uid
message-error=Something went wrong with CraftLDAP auth. THIS IS NOT YOUR FAULT, please report this error to the server admin instead\!\!\!
message-unauthorized=You're not authorized to play on this server.
port=3890
各字段如下:
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 如何工作,并且出于某种原因在你自己的服务器上改过这一行为,那你大概也知道该怎么在这里更新它。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\=govbind-pass是上面bind-dn中指定用户的密码。但请注意,直接把明文密码粘贴进去并不被认为是最佳安全实践。强烈建议做某种密钥管理。 实现这一点的一种方式是使用这个 Docker 镜像运行你的服务器,同时遵循他们关于环境变量替换的指南。bugreport-url是一个有效的 URI(记得像上面那样转义:),当玩家的登录尝试因 CraftLDAP 错误而被拒绝时,它会被传给客户端。你不应该把它直接指向 CraftLDAP——请让用户先向你提交 issue,因为无论发生了什么问题,都很可能是你的设置造成的。即使不是,这个错误也完全说明不了什么,因为所有“有价值的”日志都在你的服务器上。因此,即使 bug 是 CraftLDAP 直接造成的,问题报告也应该先发给你,只有之后(如果你在调试中卡住或发现了 CraftLDAP 的 bug)你才应该开 issue,并给我们提供远超用户所能提供的信息。请注意,看起来——尽管客户端期望这个数据字段——它们目前并不在 UI 中渲染它。人们可能会期待断开连接界面上有个“报告 bug”按钮之类的,但目前似乎并非如此。也许这是为将来某次更新预先加上的,我也不知道。filter、ldap-attr-mcuuid和ldap-attr-name稍后描述,因为理解它们之间的关系需要特别留意。host和port共同构成你 LDAP 服务器的 URI。例如,如果它可通过ldap://example.com:3890访问——那么host就是example.com,port 就是3890。port必须是数字,而host可以是公共(例如example.com)或本地(例如ldap——默认值)域名,或一个 IP 地址。message-error在玩家的登录尝试因 CraftLDAP 错误而被拒绝时发送给客户端。与bugreport-url适用相同的“规则”(即请他们报告给你,而不是我们)。message-unauthorized在玩家的登录尝试因其 UUID 未找到与你的 LDAP 服务器上任何用户关联而被拒绝时发送给客户端。
过滤器详解
你的 LDAP 服务器上可能有很多用户。其中一些可能不是 Minecraft 玩家——因此,他们显然没有 Minecraft UUID。这对 CraftLDAP 来说非常糟糕,因为它期望由 ldap-attr-mcuuid(这个属性存放你的 Minecraft UUID 属性的名称,例如上面描述的 mcuuid)和 ldap-attr-name(这个属性存放某个属性的名称,其值会在有人成功加入时打印到服务器控制台;它默认为 uid,即 LLDAP 上的登录属性,但你可能想把它设为你自己 LDAP 服务器的登录值,甚至完全不用登录名,而改用例如显示名)指定的属性出现在它扫描的每个 LDAP 用户身上。 解决办法是什么?我们确保它永远不会扫描那些可能没有这些属性的用户!
轮到过滤器登场了:它们把 LDAP 查询的结果限制为用户的一个子集。 最重要的过滤器是 memberOf,它让你能基于组归属进行过滤。这就是能让你确保不会有未设置必要属性的用户漏网的东西:你可以为 Minecraft 玩家建一个组,只把那些属性情况已经妥当的人加进去。如果你遵循了 LDAP 用法指南的第 2 步,你应该已经有那个组了。要使用它,只需把 [some group] 替换为那个组的名称(同时也把 example.com 更新为你的域名,并记住转义 =——但你现在应该已经知道了)。例如:(&(objectclass\=person)(memberOf\=cn\=minecraft,ou\=groups,dc\=guziohub,dc\=ovh))。
过滤器还可以串联起来,实现惊人的灵活性。 其确切语法不在此解释(因为这更适合另写一篇文章),只讲一些思路。例如,你可以在多服务器设置中使用多个组——第 2 步中给出了两个概念。你还可以创建一个“主要”Minecraft 组和一个 Minecraft 管理员组,在你的主服务器上过滤两者中任一的存在,但在你的开发服务器上只过滤管理员。或者你可以把关系反过来:依赖你 LDAP 中已有的管理员组,在开发服务器的配置中过滤它+minecraft,而在生产服务器上只检查 minecraft。见鬼,你甚至可以完全忽略过滤器!只需把两个属性都标记为始终必需,就不用费心去设置“有这些属性的人”和“没有的人”的组了。也可能可以设置一个检查给定属性是否存在的过滤器,而不用组,但这需要进一步测试。总的来说,天高任鸟飞!LDAP 过滤器能做很多事。
许可证
- 代码和二进制文件以 MIT 许可。二进制文件还内嵌了一个包含 UnboundID LDAP 库的 JAR,该库以 Apache2 许可。
- 是的,这意味着你可以把它用在整合包里(如果……你觉得有必要这么做的话。出于……某种原因。不,说真的,除非这是一个私人的、特定社区用的整合包,且那个社区碰巧有 LDAP 服务器——否则你干嘛要这么做?)。是的,即使在 Modrinth 之外的整合包里也行——不过(为遵守 MIT 许可要求),你需要通过“在其衍生作品中包含其许可证”来署名本模组。理想情况下,那应该是在你整合包 README 的许可证脚注里,直接放一个带有作者和模组名称的许可证链接(就像这个一样)——而不是深埋在两层 ZIP(先是整合包,然后是模组)里,即使那样技术上仍算包含。
- 不要把本模组原样重新上传(或重新编译+上传,除非做了重大改动(和/或本模组被废弃而你想让它保持更新),作为完整 fork 的一部分)到其他托管平台,尤其是 9Minecraft(*附带一个病毒不算“重大改动”)或 CurseForge。不,CurseForge,我不管这在 MIT 下技术上有多合法。如果你拒绝下架任何冒充者,那就让我把这一小段文字称为“具有法律约束力”吧(因为上面技术上写着 License,所以我们真能确定它不如 GitHub 上的
LICESNE文件或 Modrinth 上链接的许可证有效吗?我是说……当然不是(这只是一个解释性脚注),但是——你知道——你真的能确定吗?)然后看看你会怎样…… - 徽标灵感来自 LDAP 的官方图标(就“4 个 R203G32B38 颜色的三角形相互覆盖”而言),但除此之外完全是 CraftLDAP 自己的作品(无论构思(即:把它们以特定方式像素艺术化、做成尖角、并加上 CraftLDAP 首字母缩写的想法是我的)还是执行,即它是从头画起的),因此,它(无论 PNG 还是 Krita 源文件形式)以
CC BY-NC-ND 4.0许可(抱歉太严格了,如果有愿意修改它的人,我们非常愿意把它降到CC BY-SA 4.0(这就像图片界的 GPL;我甚至为此附上了 Krita 源文件)——只要承诺你不会用那些权利来冒充我们)。在这种情况下,商业使用将指任何形式的“冒充”(因为——即使它不带来直接的经济收益——它也可能以某种方式提升你在某个平台上的地位,从而带来许可证所不允许的“商业优势”)。另外——说到冒充——你不能把 CraftLDAP 这个名字(至少加个后缀什么的)用于任何 fork 或(尤其是)无关项目。
就这些!
希望你喜欢这个傻乎乎的小项目 :3
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。