DirectAuth

DirectAuth is a server-side login system for Minecraft servers running in offline mode. Every player has to /register and /login with a password before they can play, so nobody can join under someone else's name and take over their character. Players who own a Minecraft account can verify it once with /online and get logged in automatically from then on.

It is available for NeoForge 1.21.1 and Forge 1.20.1. Clients don't need to install anything.

Why use it

A server in offline mode doesn't check who is connecting: anyone can join with any username, including an admin's. DirectAuth closes that gap with per-player passwords, without an external database or any setup, and without slowing the server down.

Features

• Server-side only: install it on the server and nothing else. It registers no network channels, so it works with any client and can be added to any modpack.
• No setup: uses an embedded SQLite database. No MySQL or external server.
• No lag: database access and password hashing run off the server thread.
• Secure passwords: PBKDF2WithHmacSHA256 (100,000 iterations) with a unique salt per player.
• Automatic login for account owners: /online verifies the player's Minecraft account against Mojang's servers. From then on that player skips the password, keeps their inventory, progress and every mod's data, and gets their real skin.
• Safe with other mods: whatever a player's client sends to other mods waits until they log in, so someone using another player's name can't release their Pokémon or pick their origin. Screens other mods open at first join (origin, Destiny, starter…) show up after /login instead of covering the chat.
• Session grace period: reconnecting from the same IP within a configurable time keeps you logged in.
• Brute-force and bot protection: limited login attempts with a lockout, a registration delay and a maximum number of accounts per IP.
• Strict restrictions until login: unauthenticated players cannot move, chat, use commands other than the login ones, interact with blocks or entities, drop, move or pick up items, attack, gain XP or regenerate health. Automation from other mods (fake players such as deployers) is never affected.
• Languages: English and Spanish included; every message can be edited.

Commands

Players

Admins (OP level 4)

Admin commands also work from the server console and over RCON.

Online Mode

/online only changes how a player logs in: automatically, through Mojang, instead of with a password. Their account keeps the UUID it already had, so their inventory, statistics, advancements and every mod's data (quests, teams, starter kits…) stay exactly as they were, and nothing on disk is moved.

Up to 1.3.0, /online moved the player's data to their Mojang UUID, and many mods overwrote it from memory. Those accounts keep playing with their Mojang UUID. If a player lost items or progress that way, it may still be on disk under their offline UUID (the world's playerdata folder and each mod's data).

Compatibility with other mods

Until a player logs in, DirectAuth keeps them away from other mods:

• What their client sends to other mods waits and runs once they log in; if they disconnect first, it never runs.
• Op-only vanilla packets (command blocks, structure blocks, NBT queries…) are ignored, even for an op's name.
• Chat is dropped as it arrives, so no mod reads it either.
• Screens other mods open at first join are shown after /register or /login. Built in: Origins, MCA Reborn (Destiny), Pixelmon, Dragon Survival (NeoForge) and Starter Kit. Menus the server opens (such as Tensura's race selection on NeoForge) also wait.
• First-join teleports of other mods are kept.

If another mod's first-join screen hides the chat, set logJailPayloads to true, run /directauth reload and join with a new account: the server log lists the packets that player received. Add the right one to deferredScreenPayloads and set logJailPayloads back to false.

Tested with a real client before each release: Origins, MCA Reborn, Pixelmon, Tensura: Reincarnated (NeoForge), Dragon Survival (NeoForge), Cobblemon, Vampirism, Werewolves, Epic Fight, Simple Voice Chat, The Aether, Skyblock Builder, Welcome Screen, Starter Kit and Female Gender.

Installation

1. Download the version for your loader.
2. Put it in the server's mods folder.
3. Restart the server.

The first start creates, in world/serverconfig/:

• DirectAuth-config.json: configuration.
• DirectAuth-lang-en.json and DirectAuth-lang-es.json: messages.
• directauth.db: the account database.

Configuration

DirectAuth-config.json lets you change:

• language: "en" or "es".
• Passwords and attempts: minPasswordLength, maxPasswordLength, maxLoginAttempts, loginCooldownMs, loginLockoutSeconds.
• loginTimeout: seconds a player has to log in before being kicked.
• Sessions: sessionGracePeriod, sessionCleanupInterval.
• Bots: registrationDelay, maxAccountsPerIP.
• Other mods: deferredScreenPayloads (screens shown after login), heldPayloadExceptions (packets a player's client may send before login) and logJailPayloads (see above).

Apply changes with /directauth reload. If the file has invalid JSON, the mod keeps the previous settings and doesn't overwrite your file.

Upgrading

When a new version changes the database, DirectAuth first saves a copy as directauth-backup-<date>.db. Passwords are stored in a format older versions can read, so going back to 1.1 or 1.2 only takes swapping the jar. One exception: on older versions, players who enabled Online Mode with 1.3.1 or newer join with their Mojang UUID and an empty inventory until you upgrade again (their data stays safe under their offline UUID; don't change their Online Mode on the older version).

Compatibility

• Loaders: NeoForge 1.21.1, Forge 1.20.1.
• Supported: dedicated servers and LAN worlds.
• Not supported: BungeeCord/Velocity networks that share player data across several servers, because accounts are stored in each world.

Support the project

DirectAuth is free and open source. If you find it useful, you can sponsor me on GitHub.

Source code and issues

GitHub repository · Report an issue

Licensed under the MIT License.