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 <password> <confirmPassword> to register when they first join.
• Registered offline players can use login <password> to log in.
• Players who are already in-game can use auth changepassword <password> <confirmPassword> 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

Option	Description
database.path	Base path for the H2 database. Relative paths are resolved against the server root directory. The default creates mixauth/mixauth.mv.db.
offline_login.max_login_attempts	Maximum number of incorrect password attempts allowed each time a player is awaiting login.
offline_login.temporary_block_minutes	Duration of the temporary ban imposed when the maximum number of incorrect password attempts is reached.
offline_login.trusted_login_window_hours	Passwordless login window for the same UUID and IP address.
offline_login.login_timeout_minutes	Time limit for a registered offline player to log in while awaiting authentication.
offline_login.prompt_interval_seconds	Interval between repeated registration or login prompts while awaiting authentication.
offline_login.bcrypt_cost	BCrypt cost factor used to hash offline passwords.
offline_login.min_password_length	Minimum password length (default 1, range 1–72). BCrypt input is limited to 72 bytes.
offline_login.max_password_length	Maximum password length (default 72, range 1–72). BCrypt input is limited to 72 bytes.
offline_login.password_blacklist_path	Path to the external password blacklist file. Use one password per line; lines starting with # are comments. If the file is missing on first startup, the mod creates it automatically from bundled resources. Relative paths are resolved against the server root directory. The default creates mixauth/password_blacklist.txt.
online_validation.connect_timeout_seconds	Timeout for connecting to Mojang services.
online_validation.request_timeout_seconds	Timeout for requests to Mojang services.
online_validation.pending_handshake_ttl_seconds	How long a pending online-mode handshake is kept during login.
localization.default_language	Default prompt language. Supported values: zh_cn, en_us, es_es, pt_br, ru_ru.
localization.auto_detect_player_language	Whether to display prompts in the player's client language after login, if that language is supported.

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:<username>, 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

Command	Description
register <password> <confirmPassword>	Set an offline password for the first time. Players who are already in-game but have not yet set an offline password can also use this command to create one.
login <password>	Log in using your offline password.
auth changepassword <password> <confirmPassword>	Change your offline password.

Administrator Commands

Command	Description
auth setpassword <UUID|username> <password> <confirmPassword>	Set or reset the offline password for the specified player.
auth remove <UUID|username>	Delete all stored data for the specified 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.