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

1. 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.
2. 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).
3. 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:

1. 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.
2. 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
3. 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.
4. 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.
5. filter, ldap-attr-mcuuid and ldap-attr-name will be described later, as special care is required to understand the relation between them.
6. 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.
7. 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).
8. 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