PAuth

PAuth

Account protection for Minecraft servers that must run with online-mode=false.
Server-side only — vanilla and modded clients connect without installing anything.

Why this mod exists

A server running in offline mode cannot verify who is connecting: the vanilla
handshake skips Mojang’s session check entirely, so any client can claim any
username and inherit that player’s inventory, permissions and land claims.
Servers end up in offline mode for reasons that have nothing to do with the
client: LAN and isolated networks with no route to sessionserver.mojang.com,
networks where Mojang’s endpoints are blocked or unreliable, staying online
during Mojang authentication outages, or classroom and event setups.

PAuth restores identity verification on those servers. Whenever the session
server is reachable, players are put through the real Mojang authentication
flow and their account ownership is proven cryptographically. When it is not —
or for a player Mojang cannot confirm — PAuth falls back to a per-server
password so that nobody can take over someone else’s username.

Features

• ⚡ Verified login — players are authenticated against Mojang’s session server exactly as an online-mode server would, then join with no password.
• 🛡️ Impersonation protection (strict mode) — a username that belongs to a real Mojang account can only be used by the person who can prove they own it. This is enforced by default.
• 🔒 Password fallback — /register and /login, hashed with PBKDF2-SHA256. No plaintext storage, no external libraries.
• 🧍 Limbo — until a player has been identified they are frozen, blinded and blocked from chat, commands, movement, block interaction, item pickup/drop and combat. Nothing can be touched by an unverified connection.
• 🌐 Outage handling — Mojang lookups are cached, and when the API is unreachable the server refuses unproven names (“try again later”) instead of handing the username to whoever asked first.
• 🆔 UUID mode — keep real Mojang UUIDs, or force offline-style UUIDs so player data stays stable if the server’s online-mode setting ever changes.
• 🧩 Server-side only — the mod advertises itself as not required to connect, so unmodified clients work as-is.

Configuration

config/pauth-common.toml:

| Option | Default | Description |
|—|—|—|
| verificationMode | STRICT | STRICT reserves every real Mojang username for its verified owner; LENIENT skips the ownership check for names that have never joined |
| kickOnApiError | true | When Mojang is unreachable, refuse unverified names rather than let a username be taken over |
| offlineUuidForVerified | false | Use offline-style UUIDs for verified players (stable player data, breaks skins) instead of their Mojang UUID |
| loginTimeoutSeconds | 60 | How long an unidentified player may stay before being disconnected |
| sessionMinutes | 30 | Skip /login on reconnect from the same IP within this window (0 disables) |
| maxLoginAttempts | 3 | Wrong-password attempts before a disconnect |
| mojangApiTimeoutMs | 5000 | Timeout for Mojang API requests |
| minPasswordLength | 4 | Minimum password length |
| applyBlindness | true | Blind players until they are identified |

Accounts are stored as JSON in config/pauth/users.json.

Tested versions

| Minecraft | Loader |
|—|—|
| 1.21.1 | NeoForge |
| 1.20.1 | Forge |
| 1.19.4 | Forge |
| 1.19.2 | Forge |
| 1.18.2 | Forge |

How verification works

1. A player connects and sends their username.
2. PAuth decides how to identify them: a previously verified account is asked to authenticate again; an account with a registered password uses the password flow; an unknown name triggers a Mojang API lookup.
3. Candidates for verification go through the real authentication handshake — encryption request, client session token, Mojang hasJoined. This is the same check an online-mode server performs and it cannot be spoofed: it requires a valid account token issued by Mojang. Verified owners are remembered and skip the lookup next time.
4. Anyone who has not been verified stays frozen in limbo until they complete /register or /login, and cannot interact with the world before that.

Security notes

• STRICT mode is the default and is what protects usernames: a name tied to a real Mojang account is unavailable to anyone who cannot prove ownership of it. LENIENT relaxes this for names with no account behind them.
• IP sessions (sessionMinutes) trust the client IP address. On shared IPs (household NAT, CGNAT, VPNs) another person behind the same address could resume a session without the password. Leave sessions disabled (0) unless you understand the trade-off.
• Verification itself cannot be spoofed — it relies on Mojang’s session server, which requires a valid account token.

PAuth does not bypass, replace or emulate Minecraft’s authentication, and it
does not remove any requirement to own the game. It adds identity checks to
servers that the vanilla offline mode leaves completely unprotected.