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 joins with their official UUID and skips the password.
• Data migration: switching to the official UUID moves the player's data (inventory, ender chest, advancements, statistics and several common mods) to the new UUID, and rolls everything back if a step fails.
• 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

Command	Description
/register <password>	Creates your account. Required on your first join.
/login <password>	Logs you in.
/logout	Logs you out and disconnects you.
/changepassword <old> <new>	Changes your password and logs out your other sessions.
/unregister <password>	Deletes your account.
/online <password>	Verifies your Minecraft account to enable automatic login. Moves your data to your official UUID: see below.
/directauth confirm	Confirms a pending action when the mod asks for it.

Admins (OP level 4)

Command	Description
/directauth online <player> <true|false>	Turns automatic login on or off for a player, migrating their data.
/directauth resetpass <player> <password>	Resets a password, ends the player's sessions and lifts any lockout.
/directauth unregister <player>	Deletes a player's account.
/directauth reload	Reloads the config and language files without restarting.
/directauth resetlang	Regenerates the language files from the defaults.

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

⚠️ Before players use /online

Verifying an account changes the player's UUID, so DirectAuth moves their data to the new one. By default it migrates vanilla data plus graves, FTB Quests and SkinRestorer. If your server has other mods that store data per player, add their folders to migrationMap in the config first, or that progress may be lost. Always back up your world before migrating on a heavily modded server.

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.
• migrationMap: data folders to migrate and how. RENAME renames a file named after the UUID, DIRECTORY moves a folder, and TEXT_REPLACE also replaces the UUID inside the file.

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.

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.