MixAuth

Offline-Mode Login Mod

Adds login authentication to NeoForge servers running in offline mode.

Main features:

• Automatically distinguishes between premium and offline players.
• Authenticates premium players through Mojang, even on an offline-mode server.
• Offline players must register or log in before they can move, interact, chat, or view their real inventory.

Features

1. Automatic Login Mode Selection

• When a player first joins, the mod automatically determines whether to use online or offline mode and records the result in the known player list.
• On subsequent logins, the mod selects the login mode based on that list. Premium players are authenticated during the handshake, while offline players register or log in on the server.
• Administrators can use auth remove <UUID|username> to delete all stored data for a player: their known player list entry, offline password, ban records, and passwordless login records. The next time they join, the mod treats them as a first-time player.

2. Premium Player Authentication

• During login, the mod initiates the online-mode handshake and verifies the player's session with Mojang.
• Once verified, the player joins with their authenticated account identity, just as they would on an online-mode server.
• Authenticated premium players use their online-mode UUID instead of a UUID generated by the offline-mode server. This allows mods that rely on online-mode UUIDs, such as Figura and FTB Chunks, as well as official account skins, to work correctly.

3. Offline Player Registration and Password Login

• Unregistered offline players can use `register ` to register when they first join.
• Registered offline players can use `login ` to log in.
• Players who are already in-game can use `auth changepassword ` to change their offline password.

4. Passwordless Login Window for Offline Players

• After a registered offline player logs in successfully, the mod saves a trusted login record for the combination of their account UUID and IP address.
• The player can log in again without entering a password if they use the same UUID and IP address within the configured time window. Set the window to 0 to disable passwordless login.
• IP collision protection: if an IP address is associated with multiple UUIDs within that window, all of those UUIDs lose eligibility for passwordless login and must use a password instead.

5. Restrictions Before Offline Player Authentication

Until an offline player registers or logs in, they remain in a pending authentication state. During this time, the mod:

• Switches the player to spectator mode.
• Locks the player at their current position and continuously applies the Blindness effect.
• Sends an empty inventory view to hide the real inventory contents.
• Blocks chat, attacks, block interaction, container access, item dropping, and other gameplay actions.
• Allows only the register and login authentication commands.

6. Security Mechanisms

• Salted BCrypt password storage: Offline passwords are stored in the database as salted BCrypt hashes, never as plaintext. Each hash uses a fresh random salt. The cost factor is configurable and defaults to 12.
• Password length limits: Registration, password changes, and administrator password assignments all enforce the same minimum and maximum length checks. Passwords exceeding 72 bytes when encoded as UTF-8 are also rejected to stay within BCrypt's input limit.
• Password blacklist: Common weak passwords listed in the blacklist are rejected using case-insensitive matching. The blacklist file is created automatically on first startup, and administrators can edit it directly with one password per line.
• Login attempt limits and temporary bans: Reaching the maximum number of incorrect password attempts during a single pending login session disconnects the player and temporarily bans offline login for that account, limiting repeated password guessing. Both the attempt limit and ban duration are configurable.
• Login timeout: Registered offline players must log in within the configured time limit or they are disconnected, preventing them from remaining indefinitely in the pending authentication state.
• Passwordless login record invalidation: Changing an offline password or having an administrator reset it clears the player's existing trusted login records, preventing those records from being reused for passwordless login.

Configuration

Configuration File

• The server configuration file is named mixauth-server.toml.
• NeoForge loads this file using its SERVER configuration rules.
• We recommend restarting the server after changing the configuration to ensure that all updated authentication settings take effect.

Default Configuration

[database]
path = "mixauth/mixauth"

[offline_login]
max_login_attempts = 3
temporary_block_minutes = 5
trusted_login_window_hours = 24
login_timeout_minutes = 5
prompt_interval_seconds = 5
bcrypt_cost = 12
min_password_length = 1
max_password_length = 72
password_blacklist_path = "mixauth/password_blacklist.txt"

[online_validation]
connect_timeout_seconds = 10
request_timeout_seconds = 10
pending_handshake_ttl_seconds = 120

[localization]
default_language = "en_us"
auto_detect_player_language = true

Key Configuration Options

Additional notes:

• The player's language cannot be determined reliably during the handshake, so this phase always uses localization.default_language.
• The server always generates offline player UUIDs from the username by hashing `OfflinePlayer:`, ensuring that the same username receives the same UUID on every login.
• Changing an offline password or having an administrator reset it clears existing trusted login records.

Commands

Player Commands

Administrator Commands