离线模式登录模组
为处于离线模式的 NeoForge 服务器添加登录身份验证功能。
主要特性:
- 自动区分正版玩家与离线玩家。
- 即使在离线模式服务器上,也能通过 Mojang 对正版玩家进行身份验证。
- 离线玩家在移动、交互、聊天或查看其真实物品栏之前,必须先注册或登录。
特性
1. 自动登录模式选择
- 当玩家首次加入时,模组会自动判断应使用在线模式还是离线模式,并将结果记录在已知玩家列表中。
- 在后续登录时,模组会根据该列表选择登录模式。正版玩家会在握手阶段完成身份验证,而离线玩家则需在服务器上注册或登录。
- 管理员可以使用
auth remove <UUID|username> 删除某位玩家的所有存储数据:包括其在已知玩家列表中的条目、离线密码、封禁记录以及免密登录记录。下次该玩家加入时,模组会将其视为首次加入的新玩家。
2. 正版玩家身份验证
- 在登录过程中,模组会发起在线模式握手,并与 Mojang 验证玩家的会话状态。
- 验证通过后,玩家将以已验证的身份加入游戏,如同在在线模式服务器上一样。
- 经过验证的正版玩家使用的是在线模式的 UUID,而非由离线模式服务器生成的 UUID。这使得依赖在线模式 UUID 的模组(如 Figura 和 FTB Chunks)以及官方账号皮肤能够正常工作。
3. 离线玩家注册与密码登录
- 未注册的离线玩家在首次加入时,可使用
register <password> <confirmPassword> 进行注册。
- 已注册的离线玩家可使用
login <password> 进行登录。
- 已在游戏中的玩家可使用
auth changepassword <password> <confirmPassword> 更改其离线密码。
4. 离线玩家的免密登录窗口
- 已注册的离线玩家成功登录后,模组会为“账户 UUID + IP 地址”组合保存一条可信登录记录。
- 如果在配置的时间窗口内,玩家使用相同的 UUID 和 IP 地址再次加入,则无需输入密码即可登录。将时间窗口设置为
0 可禁用免密登录功能。
- IP 冲突保护:如果在该时间窗口内,某个 IP 地址关联了多个 UUID,则所有这些 UUID 都将失去免密登录资格,必须改用密码登录。
5. 离线玩家身份验证前的限制
在离线玩家完成注册或登录之前,他们将保持在待验证状态。在此期间,模组:
- 将玩家切换为旁观者模式。
- 将玩家锁定在当前坐标,并持续施加失明效果。
- 发送空的物品栏视图以隐藏真实的物品栏内容。
- 禁止聊天、攻击、方块交互、容器访问、丢弃物品及其他游戏内操作。
- 仅允许使用
register 和 login 认证命令。
6. 安全机制
- 加盐 BCrypt 密码存储:离线密码在数据库中均以加盐的 BCrypt 哈希值形式存储,绝不以明文保存。每个哈希值均使用全新的随机盐值。成本因子可配置,默认值为 12。
- 密码长度限制:注册、修改密码以及管理员分配密码时,均强制执行相同的最小和最大长度检查。当密码以 UTF-8 编码超过 72 字节时也会被拒绝,以确保符合 BCrypt 的输入限制。
- 密码黑名单:被列入黑名单的常见弱密码将通过不区分大小写的匹配方式被拒绝。黑名单文件会在首次启动时自动生成,管理员可直接编辑该文件,每行一个密码。
- 登录尝试次数限制与临时封禁:在单次待处理的登录会话中达到最大错误密码尝试次数后,玩家将断开连接,且该账户的离线登录功能将被临时封禁,从而限制反复猜测密码的行为。尝试次数上限和封禁时长均可配置。
- 登录超时:已注册的离线玩家必须在配置的时限内完成登录,否则将被断开连接,防止其无限期停留在待认证状态。
- 无密码登录记录失效:更改离线密码或由管理员重置密码时,会清除玩家现有的可信登录记录,防止这些记录被用于无密码登录。
配置
配置文件
- 服务器配置文件名为
mixauth-server.toml。
- NeoForge 会根据其 SERVER 配置规则加载此文件。
- 建议在修改配置后重启服务器,以确保所有更新的认证设置生效。
默认配置
[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
[本地化]
默认语言 = "en_us"
自动检测玩家语言 = true
### 键配置选项
| 选项 | 说明 |
| --- | --- |
| `database.path` | H2 数据库的基础路径。相对路径将相对于服务器根目录解析。默认情况下会创建 `mixauth/mixauth.mv.db`。 |
| `offline_login.max_login_attempts` | 允许玩家在等待登录时输入错误密码的最大次数。 |
| `offline_login.temporary_block_minutes` | 当达到最大错误密码尝试次数时,临时封禁的持续时间(分钟)。 |
| `offline_login.trusted_login_window_hours` | 相同 UUID 和 IP 地址的免密登录窗口时长(小时)。 |
| `offline_login.login_timeout_minutes` | 已注册的离线玩家等待身份验证时的登录时限(分钟)。 |
| `offline_login.prompt_interval_seconds` | 在等待身份验证期间,重复显示注册或登录提示之间的间隔时间(秒)。 |
| `offline_login.bcrypt_cost` | 用于哈希离线密码的 BCrypt 成本因子。 |
| `offline_login.min_password_length` | 最小密码长度(默认值为 1,范围 1–72)。BCrypt 输入限制为 72 字节。 |
| `offline_login.max_password_length` | 最大密码长度(默认值为 72,范围 1–72)。BCrypt 输入限制为 72 字节。 |
| `offline_login.password_blacklist_path` | 外部密码黑名单文件的路径。每行一个密码;以 `#` 开头的行为注释。如果首次启动时文件不存在,模组会自动从捆绑资源中创建该文件。相对路径将相对于服务器根目录解析。默认情况下会创建 `mixauth/password_blacklist.txt`。 |
| `online_validation.connect_timeout_seconds` | 连接至 Mojang 服务的超时时间(秒)。 |
| `online_validation.request_timeout_seconds` | 向 Mojang 服务发送请求的超时时间(秒)。 |
| `online_validation.pending_handshake_ttl_seconds` | 登录期间保留待处理的在线模式握手的时间(秒)。 |
| `localization.default_language` | 默认的提示语言。支持的值:`zh_cn`、`en_us`、`es_es`、`pt_br`、`ru_ru`。 |
| `localization.auto_detect_player_language` | 如果玩家客户端的语言受支持,是否在登录后以该语言显示提示。 |
其他说明:
- 在握手阶段无法可靠地确定玩家的语言,因此此阶段始终使用 `localization.default_language`。
- 服务器始终通过哈希 `OfflinePlayer:<username>` 从用户名生成离线玩家的 UUID,确保同一用户名每次登录时获得相同的 UUID。
- 更改离线密码或由管理员重置密码会清除现有的可信登录记录。
## 命令
### 玩家命令
| 命令 | 说明 |
| --- | --- |
| `register <password> <confirmPassword>` | 首次设置离线密码。已经在游戏中但尚未设置离线密码的玩家也可以使用此命令来创建密码。 |
| `login <password>` | 使用离线密码登录。 |
| `auth changepassword <password> <confirmPassword>` | 更改你的离线密码。 |
### 管理员命令
| 命令 | 说明 |
| --- | --- |
| `auth setpassword <UUID\|username> <password> <confirmPassword>` | 为指定玩家设置或重置离线密码。 |
| `auth remove <UUID\|username>` | 删除指定玩家的所有存储数据:其已知玩家列表条目、离线密码、封禁记录和免密登录记录。下次他们加入游戏时,模组会将其视为首次登录的玩家。 |
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. |
评论 0
登录后参与评分
还没有评论,来抢沙发吧