CraftLDAP
基于 LDAP 的 Minecraft 白名单模组
Craft-什么?
LDAP 是一种跨平台的用户索引系统。它允许使用一套登录名和密码在多个服务中通用,并使您的各种个人数据(如姓名、显示用户名、联系方式(电子邮件和/或电话)、头像等)在这些服务之间共享。
LDAP 的主要用户包括:
- 自托管极客(即那些会运行自己的 NextCloud、联邦网络服务(Matrix、Mastodon、电子邮件等)、网站、Git 托管等的人),他们希望将自己运行的所有服务更好地整合在一起。
- 组织机构(如公司、学校、非政府组织、政府机构等),这些机构通常运行多个内部应用程序(例如库存跟踪程序、电子成绩册或投票系统),并与一些外部服务集成(如 Microsoft Teams)。对于这些机构而言,这种形式的集成可以节省数千美元的行政成本(与其每次有人入职或离职时更新多个用户数据库,不如只需更改一个地方)。
因此,本模组旨在服务于:
- 痴迷于集成与自动化的人(比如 我自己),他们已经运行了自己的自托管技术栈,包括 LDAP,并且绝对 不能忍受 自己精心打造的相互交织的服务集群中,唯独 Minecraft 服务器完全独立存在的情况。
- 运营自有 Minecraft 服务器的中学/大学等教育机构。这一趋势在新冠疫情期间流行开来(甚至连本模组的作者所在的学校也参与其中,她实际上是该模组背后开发团队的一员——尽管该校使用的是通过微软服务的 OAuth 进行集中登录而非 LDAP,因此其 Minecraft 登录系统围绕一个与该 OAuth 集成的 Discord 机器人构建,这也是为什么本模组直到今天才问世的原因)。据某些 YouTube 视频所示,这一趋势以 微小的规模 似乎仍在持续。如果您是仍坚持这一做法的教育机构(或其他任何机构),并且恰好使用 LDAP 作为学生注册表——请随意使用!
(另外,你们可能资金紧张,所以……也许可以考虑赞助?UwU :3)
相反,本模组 不 适用于以下人群:
- 只需要一种快速简单的方式来同步服务器白名单的人。请查看 WhiteList Sync 2 —— 与运行整个 LDAP 服务器相比,它所需的开销、配置和维护要少得多。
- 没有 LDAP 服务器并希望借此模组学习如何搭建 LDAP 的人。本模组将是一个极其糟糕的 LDAP 入门教程,因为文档忽略了一些关于整体工作原理的重要部分;它还充斥着大量的技术术语,左一句右一句中间还穿插着对 CurseForge 和 Minecraft 插件的随机吐槽。您最好尝试按照他们的 配置指南 设置像 LLDAP(最简单的 LDAP 服务器)这样的东西,并搭配其官方支持的使用者之一。
- ……简单来说,如果您必须阅读这个“Craft-什么?”部分才能理解本模组,那么您可能不是它的目标受众。
下载
安装
- 在执行任何操作之前,请为新的消费者(consumer)准备好你的 LDAP 服务器。 请参阅下面的章节。
- 配置一个基于 Fabric / Quilt 的 Minecraft 服务器(不支持 Forge/NeoForge(目前还不支持——我可能会稍后在 Architectury 下重写此模组,即当我想自己在 (Neo)Forge 上托管服务器时,或者如果存在某些普遍需求——你可以通过提交 issue 来表明这一点,以支持多加载器),不支持基于插件的方式(暂无计划——出于“意识形态”原因:由于插件加载器通常是争议焦点,一些主要插件加载器的维护者通常表现得有些傲慢(请参考像 Redstoner 那样对 PaperMC 的抱怨(大多数人在职业生涯中至少会发过一次牢骚)了解更多)以及整个“Bukkit 自我毁灭”导致我们陷入分叉地狱的问题;因此,我不太期待支持那个生态系统;与此同时,配合 Lithium、Noisium、ServerCore 和其他几个优化/修复模组,Fabric 在性能方面可以接近甚至超越那些“专业、超快”的服务器后端,但缺少一些优秀的独占插件(例如 WorldGuard),所以我喜欢通过制作模组加载器独占内容来“平衡”这一方程的想法;以及实际原因:我喜欢用 Fabric/Architectury 编程;回到 Bukkit 感觉糟透了)),除非有某些普遍需求——你可以通过提交 issue 来表明这一点),或者是原版 Minecraft(出于显而易见的原因)。不支持客户端,因为没有任何合理的理由让你想在客户端上使用此模组(尽管——概念上——它可以在不修改的情况下在客户端运行;只需更改 JAR 文件中此模组的
fabric.mod.json 内的 side 即可)。该模组针对的是最新的稳定版 Minecraft 版本(在撰写本文时为 1.21.11),但是(以防这个项目像许多项目一样在更新上变得懒惰),我们的 dependencies 指定任何更新的服务器版本也应该可以工作(归功于此模组实际上仅依赖 4 个原版的类,这些类在未来不太可能发生变化,至少就我们对它们的使用而言是这样)。如果你发现某个标记为支持的版本无法工作,请提交 issue。如果你想使用较低版本或快照,你可以使用 Fabric 的依赖覆盖,但后果自负!
- 将此模组的 JAR 和 FabricAPI 的 JAR(如果是现代 MC 版本且已发布 Quilted FabricAPI 的 JAR,则使用该 JAR;如果没有,Quilt 暂时无法与此模组一起使用,请给他们几个月/几年的时间来赶上)放入服务器的
mods 文件夹中。
- 启动它!
用法
首先,我们应该解释此模组是如何工作的:每当玩家登录时,它会检查是否有任何 LDAP 用户(在匹配用户指定过滤器的那些用户中,可能是类似 minecraft 组)将该玩家的 Minecraft UUID 作为属性附加。如果找到匹配项,玩家将以该 LDAP 用户的身份登录。如果未找到匹配项,则拒绝玩家的登录尝试。
正如你所见,这是一个极其简单的流程。没有 /login 命令或类似的东西。它本质上就像一个基于 LDAP 的白名单。未来,我们还计划从 LDAP 中提取一些额外属性到 Minecraft(如 OP 权限级别等),并添加一些实用命令(用于实时重载配置、在游戏中检查你自己的 LDAP 用户以及其他一些东西——值得注意的是,出于设计原因,永远不会出现 /login 命令或类似命令,详见下文),但这还有待实现。
在 LDAP 中
- 你需要在用户模式中创建一个额外的属性,用于存储用户的 Minecraft UUID。 建议将其命名为
mcuuid,以避免更改默认配置。
- 你 REALLY SHOULD(但在技术上不需要,下面会详细说明)至少创建一个新的组,用于 Minecraft 玩家。 如果你托管多个服务器,并且不希望一个服务器的用户与另一个服务器的用户混合在一起,你也可以创建多个组。或者——如果你想独立控制某人是否是 Minecraft 玩家以及他们可以加入哪个服务器——你可以创建一个“总体组”和每个服务器的子组(并调整每个服务器的过滤器(详见下文)以查找两者中的存在)。总体而言,你的分组方式没有限制。只需知道应该有一种明确区分玩家和非玩家的方法(详见下文)。
- 为用户提供指定其 Minecraft UUID 的途径。 如果你运行像 LLDAP 这样的服务器,其中有一个 Web UI,任何用户都可以编辑他们的属性,这很简单。只需将你的
mcuuid 属性标记为用户可编辑,并发布一些关于如何将昵称转换为 UUID 的指南(如 NameMC 链接),然后一切就绪。如果你的 LDAP 系统没有提供用户友好的自我编辑方式,那就只能靠自己了。最有可能的是,你已经运行了一些用于 LDAP 管理的额外工具(至少用于头像和密码更改),所以你可能能够扩展它以允许修改一个额外的属性。如果没有(即你明确只允许授权员工更改 LDAP 记录),那么你将需要指示你的员工手动添加用户的 UUID,或者你需要构建一些内部前端来自动化这个过程。该项目提供对 LDAP 的只读访问,这是出于设计考虑(旨在与 LLDAP 兼容,LLDAP 对外部服务是只读的,仅允许通过他们的 WebUI 进行更改),因此不存在——也永远不会存在——像 /login 命令那样从游戏内添加记录的功能。
模组内部配置
首次启动后,会在 [服务器目录]/config/ldap.properties 中生成一个配置文件。其内容应类似于如下所示:
#CraftLDAP 的配置文件。请参阅 Modrinth 页面或 GitHub README 以获取文档。
#[创建日期]
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
各字段说明如下:
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\=gov
bind-pass 是上述 bind-dn 中指定用户的密码。然而请注意,直接将明文密码粘贴进去并不被视为最佳的安全实践。强烈建议采用某种形式的密钥管理方案。 实现这一点的一种方法是使用 这个 Docker 镜像 运行你的服务器,并遵循其关于 环境变量替换 的指南。
bugreport-url 是一个有效的 URI(记得像上面那样对 : 进行转义),当客户端因 CraftLDAP 错误导致登录被拒绝时,该 URL 会被传递给客户端。你不应该将其指向 CraftLDAP 本身——请让用户先向你提交问题反馈,因为很可能出现的问题是由你的配置引起的。即使并非如此,这种错误对我们来说毫无意义,因为所有“有价值”的日志都在你的服务器上。因此,即使错误确实由 CraftLDAP 直接引起,也应该首先向你报告,只有当你调试陷入困境或在 CraftLDAP 中发现 bug 时,你才应向我们要开 Issue,并提供比普通用户更多的信息。请注意,尽管客户端期望接收此数据字段,但目前它们并未在 UI 中渲染它。人们可能会预期在断开连接界面看到一个“报告 Bug”按钮之类的功能,但目前似乎并非如此。也许这是为了未来的更新而提前添加的,我也不确定。
filter、ldap-attr-mcuuid 和 ldap-attr-name 将在稍后介绍,因为理解它们之间的关系需要特别小心。
host 和 port 共同构成了你的 LDAP 服务器的 URI。例如,如果可以通过 ldap://example.com:3890 访问——那么 host 将是 example.com,端口将是 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))。
过滤器也可以链式连接以实现极大的灵活性。 此处不详细解释其确切语法(因为这更适合一篇专门的文章),只提供一些思路。例如,在多台服务器设置中可以使用多个组——LDAP 设置指南的第 2 步提供了两种相关概念。你还可以创建一个“主”Minecraft 组和一个 Minecraft 管理员组,在主服务器上过滤任一组的成员,而在开发服务器上仅过滤管理员。或者你可以颠倒关系:依赖 LDAP 中现有的管理员组,并在开发服务器的配置中过滤该组+minecraft,但在生产服务器上仅检查 minecraft。甚至,你可以完全忽略过滤器!只需将两个属性标记为始终必需,而无需为“拥有它们的用户”和“不拥有它们的用户”设置组。也可能存在一种检查给定属性是否存在而非使用组的过滤器方法,但这需要进一步测试。总之,潜力无限!LDAP 过滤器功能强大。
许可证
- 代码和二进制文件根据 MIT 许可证授权。该二进制文件还嵌入了一个 JAR,其中包含UnboundID LDAP 库,根据 Apache2 许可证授权。
- 是的,这意味着你可以在整合包中使用此模组(如果……你觉得有必要这样做。出于……某些原因。不,但说真的,除非这是一个特定于私人社区的整合包,且该社区恰好拥有 LDAP 服务器——否则你为什么要这么做呢?)。是的,即使在 Modrinth 之外的整合包中也行——尽管(为了符合 MIT 许可证要求),你需要通过“在衍生作品中包含其许可证”来署名此模组。理想情况下,这应该是一个简单的链接,直接指向你的整合包 README 的许可证脚注中的许可证、作者和模组名称(就像这个脚注一样)——而不是深埋在两层 ZIP 文件中(首先是整合包,然后是模组),即使这在技术上仍算作包含。
- 不要原样上传(或重新编译+上传,除非进行了重大更改(和/或此模组已被弃用而你希望保持其更新),作为完整分支的一部分)此模组到其他主机,特别是 9Minecraft(包括植入病毒不算作“重大更改”)或 CurseForge。不,CurseForge,我不在乎这在 MIT 下技术上是否合法。如果你拒绝下架任何冒充者,那么让我称这段文字为“具有法律约束力”(因为它技术上在上面写着许可证,所以我们能确定它不如 GitHub 上的
LICESNE 文件或 Modrinth 上链接的许可证有效吗?我的意思是……当然不是(这只是一个解释性脚注),但是——你知道——你能真正确定吗?)然后看看你会怎么做……
- 徽标灵感来源于LDAP 的官方图标(仅限于“4个 R203G32B38 颜色的三角形相互覆盖”这一方面),但除此之外,CraftLDAP 的徽标是其独立完成的作品(无论是构思上(即:由我决定以特定方式将其像素化、使其尖锐,并为 CraftLDAP 添加 C.L. 首字母)还是执行上,即从头绘制完成),因此它(包括 PNG 和 Krita 源文件形式)根据
CC BY-NC-ND 4.0 许可证授权(抱歉过于严格,如果有人愿意修改它,我们非常乐意将其降低至 CC BY-SA 4.0(这类似于图像的 GPL;为此我还包含了 Krita 源文件),只要你承诺不会利用这些权利假装是我们即可。在这种情况下,商业使用将是任何形式的“冒充”(因为——即使它不会带来直接的经济利益——但它可能会以某种方式提升你在某个平台上的地位,从而导致许可证不允许的“商业优势”)。另外——说到冒充——你不能对任何分支或(尤其是)无关项目重用 CraftLDAP 名称(至少添加一些后缀,或其他什么)。
就是这样!
希望你享受这个愚蠢的小项目 :3
CraftLDAP
LDAP-based whitelist mod for Minecraft
Craft-what?
LDAP is a kind of multi-platform user index. It allows one login+password to be used across many services, and makes your various personal data (like name and surname, displayed username, contacts (email and/or phone), profile pic, etc.) shared between said services.
Main users of LDAP are:
- Self-hosting nerds (the type of people who'd run their own NextCloud, federated stuff (Matrix, Mastodon, email, etc.), website, Git hosting, etc.), who want some greater integration between all the stuff they run.
- Organizations (such as companies, schools, NGOs, governments, etc.), that often run multiple internal applications (for example, an inventory tracking program, an electronic grade-book or a voting system) and integrate with some external services (eg. Microsoft Teams), and for whom this form of integration may mean thousands saved in administrative costs (instead of updating several user databases every time someone is hired/leaves, they only need to change one).
By consequence, this mod is aimed at:
- Integration'n'automation-obsessed people (like yours truly), who already run their own self-hosting stack, including LDAP, and absolutely canNOT stand the idea that their self-hosted Minecraft server is completely detached from their beautiful clusterfuck of inter-mingling services.
- Highschools/universities/etc. who run their own Minecraft servers. This trend was popularized around Covid (even this mod's author's school was involved with it, and she was actually on the dev-team behind it - although that schools used OAuth via Microsoft Services for a central login instead of LDAP, and so their Minecraft login system was centered around a Discord bot that integrated with that OAuth, which is why this mod only came to exist now) and - in some tiny capacity - is apparently still alive (if this YouTube video is to be beleived). If you're some educational institution (or any institution, for that matter) that's still keeping this flame going, and you also happen to be using LDAP as your student registry - please, be my guest!
(Also, you're probably strapped with cash, so... Sponshorship, maybe? UwU :3)
On the contrary, this is NOT aimed at:
- People who only need a quick'n'simple way to sync whitelists across servers. Please check out WhileList Sync 2 for that - it requires much less overhead, config, and maintenance, compared to running a whole LDAP server.
- Anyone who doesn't have an LDAP server and wants to use this mod for a learning experience in setting up one. This mod would be a pretty horrible introduction to LDAP, as the documentation glosses over some major parts of how the whole thing works; it also tosses in a bunch of technical jargon left, right, n'center, and also interjects random rants about CurseForge and Minecraft plugins. You'd be much better off trying to set up something like LLDAP (the simplest LDAP server out there) along with one of their officially-supported consumers, by following one of their config guides.
- ...In simpler terms, if you had to read this „Craft-what?” section to understand this mod, then you're probably not its intended audience.
Download
- From Modrinth
- On GitHub, please build from source or download a release.
- CruseForge support is not planned.
Installation
- Before doing anything, prepare your LDAP server for a new consumer. Please refer to the section below.
- Configure yourself a Fabric-/Quilt-based Minecraft server (not Forge/NeoForge (not yet, at least - I may rewrite this mod in Architectury at some point later (ie. whenever I'll feel like self-hosting a server on (Neo)Forge, or if there is some popular demand - which you can signal, by opening an issue), for multi-loader support), plugin-based (not planned (for both „ideological” reasons (due to plugin loaders being controversy magnets, between maintainers of some major plugin loaders generally somewhat coming off as assholes (please refer to, like... any Redstoner's rant about PaperMC (most will have made at least one during their career) for more) and the whole „Bukkit blew itself up” thing that got us into the fork-hell we have today, and (as such) I'm not exactly looking forward to supporting that ecosystem; meanwhile, Fabric with Lithium, Noisium, ServerCore and a few other optimization/bugfix mods can get close to or even surpass those „professional, ultra-fast” server backends in terms of performance, but lack some nice exclusive plugins (eg. WorldGuard), so I like the idea of „balancing out” this equation by making modloader-based exclusives instead) and practical ones (I like coding in Fabric/Architectury; going back to Bukkit feels dreadful)), unless there is some popular demand - which you can signal, by opening an issue), or vanilla Minecraft (for obvious reasons)). Client isn't supported, because there is no sane reason you'd ever want this mod on a client (although - conceptually - it COULD work there without modification; just change the side inside this mod's
fabric.mod.json in the JAR). The mod targets whichever stable Minecraft version is the newest (which is 1.21.11, at the time of writing this), but (in case this project ever gets lazy with updates, as so many do) our dependencies specify that any newer server version should also work, too (by the virtue of this mod really only relying on 4 vanilla classes, that are unlikely to change in the near future, at least as far as our usage of them goes). If you find a version that is marked as supported, but doesn't work, please file an issue. If you want to use a lower version or a snapshot, you may use Fabric's Dependency Overrides, but you're doing it at your own risk!
- Place this mod's JAR and FabricAPI's JAR (or Quilted FabricAPI's JAR, if it's finally out for a modern MC version - if not, Quilt sadly cannot be used with this mod yet, please give them a couple of months/years to catch up) in your server's
mods folder.
- Launch it!
Usage
First, we should explain HOW does this mod actually work: Anytime a player logs in, it checks whether any LDAP user (from among those matching a user-specified filter, probably something like a minecraft group) has that player's Minecraft UUID attached as an attribute. If a match is found, the player logs in „as” that LDAP user. If no match is found, the player's login attempt is rejected.
As you can see, this is an INCREDIBLY simple flow. There is no /login command, or anything like that. It works, essentially, like an LDAP-backed white-list. In the future, we also plan to pull some extra attributes from LDAP to Minecraft (like OP permission level, etc.), as well as add some utility commands (to live-reload config, inspect your own LDAP user in-game, and some other stuff, maybe - notably, a /login command or similar is never coming by design, see below), but that's yet to come.
In LDAP
- You need to create one more attribute, the one that'll hold a user's Minecraft UUID, in your user schema. It's recommended to call it
mcuuid, to avoid having to change the default config.
- You REALLY SHOULD (but technically don't need to, more on that below) create at least one new group, for Minecraft players. If you host multiple servers and wouldn't want one server's users blending in with another, you may also create multiple groups. Or - if you want to independently control whether someone is a Minecraft player and what server they can join - you may create an „overarching group” and per-server subgroups (and adjust every server's filter (more on that below) to look for presence in both). Overall, the sky is the limit, as far as your grouping goes. Just know that there should be a way to unambiguously differentiate between players and non-players (more on that below).
- Give some way for your users to specify their Minecraft UUID. This is simple if you run a server like LLDAP, where there is a web UI in which any user can edit their attributes. Just mark your
mcuuid attribute as user-editable, post some guide on converting a nickname to UUID (like a NameMC link), and Bob's Your Uncle. If your LDAP system doesn't provide a user-friendly way of self-editing, you're on your own. Most likely, you already run some additional tool for LDAP management (at least for profile pictures and password changes), so you might be able to extend it to allow for the modification of one extra attribute. If not (ie. you explicitly only allow authorized staff to alter LDAP records), you'll either need to instruct your staff to add your users' UUID manually, or you'll need to build some internal front-end to automate that. This project provides read-only access to LDAP, and this is by design (it's meant to be compatible with LLDAP, which is read-only for any external service, only allowing changes via their WebUI), so there is not - and will never be - something like a /login command to add a record from in-game.
In the mod itself
After the first launch, a config file will be created in [server directory]/config/ldap.properties. It should look something like this:
#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
Fields are as follows:
base-dn: I have no idea what that does. The value above (ie. ou=people,dc=example,dc=com, where example.com is replaced with your own domain, eg. guziohub.ovh -> ou=people,dc=guziohub,dc=ovh) is ripped straight from LLDAP documentation, and it works for Matrix, UnboundID (which is the library that CraftLDAP uses internally) and Nextcloud. Just update the domain, keeping in mind that any = must be escaped as \= (as can be seen above), and you'll be fine. Otherwise, if you're an advanced-enough LDAP admin who knows how Base DN works, and you changed this behaviour on your own server for whatever reason, you'll probably also know how to update it here.
bind-dn is your „service login”. If you have a user called admin who can read all other LDAP users (or a user called minecraftservice who can read all Minecraft-related users) and your domain is guziohub.ovh or someuniversity.gov - you'd specify that here, as follows: cn=admin,ou=people,dc=guziohub,dc=ovh or cn=minecraftservice,ou=people,dc=someuniversity,dc=gov. Just keep in mind that =s need escaping, so it'd actually become: cn\=admin,ou\=people,dc\=guziohub,dc\=ovh or cn\=minecraftservice,ou\=people,dc\=someuniversity,dc\=gov
bind-pass is the password for the user specified above in bind-dn. Please be aware, however, that just directly pasting in plaintext passwords isn't considered the best security practice. It is highly advised to do some sort of secret management. One way to achieve that would be to run your server using this Docker image, while following their guide on envar replacement.
bugreport-url is a valid URI (just remember to escape the :, like above) that's passed to the client, if their login attempt is rejected due to a CraftLDAP error. You should NOT point it to CraftLDAP directly - please let users file issues with you first, as it's more than likely that whatever problem is happening is caused by your setup. Even if it's not, this error tells us absolutely nothing, as all the „valuable” logs are on your server. As such, even if the bug is caused by CraftLDAP directly, an issue report should still go to you first, and only then (if you get stuck while debugging or discover a bug in CraftLDAP) should you open an issue, while giving us more info than a user ever could. Please note that it seems like - even though clients expect this data field - they don't currently render it in the UI. One could expect a „report bug” button on the disconnect screen, or something like that, but this doesn't seem to be the case quite yet. Perhaps this was added in preparation for a future update, I dunno.
filter, ldap-attr-mcuuid and ldap-attr-name will be described later, as special care is required to understand the relation between them.
host and port form, together, the URI of your LDAP server. For example, if it's accessible at ldap://example.com:3890 - then host will be example.com and port will be 3890. port must be a number, while host can be a public (eg. example.com) or local (eg. ldap - the default) domain name, or an IP address.
message-error is sent to the client if their login attempt is rejected due to a CraftLDAP error. Same „rules” as with bugreport-url apply (ie. ask them to report to you, not to us).
message-unauthorized is sent to the client if their login attempt is rejected due to their UUID not being found tied to any user on your LDAP server.
Filters explained
You may have a lot of users on your LDAP server. Some of them may not be Minecraft players - and, as such, they obviously don't have a Minecraft UUID. This is very bad for CraftLDAP because it expects the attributes specified by ldap-attr-mcuuid (this one holds the name of your Minecraft UUID attribute, for example mcuuid, as described above) and ldap-attr-name (this one holds the name of an attribute, whose value is printed to the server console, whenever someone joins succesfully; it defaults to uid which is the login attribute on LLDAP, but you may want to set it to your own LDAP server's login value, or even not use logins at all, instead relying on eg. display-names) to be present on every LDAP user is scans through. What's the solution? We make sure that it never scans through those users who may not have those attributes!
Enter filters: They limit the results of an LDAP query to only a subset of users. The most important filter is memberOf, which lets you filter based on group belonging. This is what will let you ensure that no user without the necessary attributes set slips through the cracks: You can make a group for Minecraft players, and only add to it those who have their attribute situation in order. If you followed step 2 of the LDAP usage guide, you should have that group already. To use it, simply replace [some group] with the name of that group (and also update example.com to your domain, and remember to escape = - but you should know this by now). For example: (&(objectclass\=person)(memberOf\=cn\=minecraft,ou\=groups,dc\=guziohub,dc\=ovh)).
Filters can also be daisy-chained to allow for incredible flexibility. The exact syntax of that will not be explained here (as that's something better-suited for a dedicated article), only some ideas. For example, you could use multiple groups in a multi-server setup - 2 concepts for that were provided in step 2 of the LDAP setup guide. You can also create a "main" Minecraft group and a Minecraft admin group, and filter for presence in either on your main server, but only for admins on your dev-server. Or you could flip the relation on its head: Rely on your existing admin group in LDAP, and filter for it+minecraft in the dev-server's config, but only check for minecraft on your production server. Hell, you can even ignore filters altogether! Just mark both attributes as always-required, and not bother with setting up groups for „those who have them” and „those who don't”. It may also be possible to set a filter that checks for the presence of a given attribute, instead of using a group, but that needs further testing. Overall, the sky is the limit! LDAP filters can do a lot.
License
- The code and the binaries are licensed under MIT. The binary also embeds a JAR with the UnboundID LDAP library, licensed under Apache2.
- Yes, that means that you can use this in modpacks (If... You feel the need to do that. For... Some reason. No, but seriously, unless this is a private community-specific pack, and that community happens to have an LDAP server - why would you ever do that?). Yes, even in packs outside Modrinth - although (to comply with MIT license requirements), you'd need to credit this mod, by „including its license in derived work”. Ideally, that'd be a simple link to the license, with the author's and the mod's name, directly in your pack's README's license footnote (like this one) - not buried deep within 2 layers of ZIPs (first the pack, then the mod), even if that's technically still inclusion.
- Do not reupload (or recompile+upload, unless significant changes were made (and/or this mod got abandoned and you want to keep it updated), as part of a complete fork) this mod as-is onto other hosts, notably 9Minecraft (*including a virus doesn't count as „significant changes”) or CurseForge. No, CurseForge, I don't care how technically legal it would be under MIT. If you refuse to take down any impersonators, then let me call this little string of text „legally binding” (Because it technically says License above, so can we really be sure that it's not as valid as the
LICESNE file on GitHub or the linked license on Modrinth? I mean... Of course it's not (this is merely an explainer footnote), but - you know - can you really be sure?) and see how you roll...
- The logo is inspired by LDAP's official icon (in so far as „4 R203G32B38-colored triangles covering each other”), but it's otherwise CraftLDAP's own work (in both mind (as in: it was my idea to pixel-art-ify them in a specific way, make them pointy, and add C.L. initials for CraftLDAP) and execution, as in it was drawn from scratch) from-start-to-finish, and as such, it (in both PNG and Krita sources form) is licensed under
CC BY-NC-ND 4.0 (sorry for being too strict, we're more than willing to lower this down to CC BY-SA 4.0 (which is like GPL for images; I even included Krita sources for this purpose), if there are people willing to modify it - just promise that you won't use those right to pretend to be us). Commercial use would in this case be any kind of „impersonation” (as - even if it doesn't lead to direct financial gain - it may somehow increase your standing on some platform, which could lead to „commercial advantage” not allowed by the license). Also - speaking of impersonation - you cannot reuse the CraftLDAP name (at least add some suffix, or something) for any fork or (especially) unrelated projects.
That's all!
Hope you enjoy this silly little project :3
评论 0
登录后参与评分
还没有评论,来抢沙发吧