ServerAUTH
适用于 Paper/Purpur 26.3 的密码 + TOTP 双因素认证
版本 2.1.0 · Minecraft 26.3 · Java 25 · 服务端插件
ServerAUTH 是一款专为 离线模式(offline-mode)和代理架构 设计的登录/注册插件,在这些场景下原版客户端的身份无法被信任。玩家需使用密码注册,每次加入服务器时都要重新登录,并可通过 TOTP 第二因素(如 Google Authenticator、Authy 等)保护其账户。密码和恢复问题答案均使用 BCrypt 进行哈希处理;2FA 设置页面由内置的本地 Web 服务器提供,玩家可以在浏览器中扫描二维码完成设置。
功能特性
- 密码认证:采用 BCrypt 哈希(可配置成本为 10-16),并在注册时进行密码确认匹配。
- TOTP 双因素认证:符合 RFC 6238 标准,兼容 Google Authenticator,支持哈希存储的备用代码以及基于每个账户的验证失败锁定机制。
- 内置 Web 服务器:用于 2FA 设置:QR 码和密钥均在本地生成(绝不会发送给第三方),并在一个你可以置于反向代理后面的页面上展示。
- 未认证玩家登录锁定:移动、聊天、命令、物品栏和交互行为将被冻结,可选开启失明效果,并将玩家传送至可配置的登录出生点,该出生点可以隐藏真实坐标。
- 重连宽限期:如果在限定时间窗口内从同一 IP 重连,则无需重新输入密码(但 2FA 始终会重新挑战,绝不会被跳过)。
- 四层自动登录(用户名 / UUID / IP / 客户端指纹):详细文档说明了在离线模式服务器上每一层验证的实际价值。
- 账户恢复:通过安全问题/答案 或 有效的 2FA 代码进行恢复,两者均设有速率限制和锁定机制。
- 基岩版跨平台游玩支持:可选地为 Floodgate 玩家启用自动登录(在其到达服务器前已验证其 Xbox Live 身份)。
- 管理工具:
/authadmin(需要 OP 权限且管理员自身必须启用 2FA),用于查询、重置或删除账户。
- 安全日志记录:包含敏感命令脱敏,可选地在登录失败和 UUID 不匹配时向 OP 发送警报。
- 存储后端:SQLite(默认)或 MySQL,通过连接池实现带版本控制的数据库模式迁移。
- 策略控制:要求 OP/管理员启用 2FA,限制每 IP 账户数量,会话超时及非活动超时。
离线模式 / 代理说明
在离线模式服务器上,玩家的 UUID 是根据其用户名派生的,因此 UUID 和客户端指纹检查仅作为 纵深防御(defence-in-depth) 手段,容易被伪造。在这些服务器上,密码才是真正的关卡,而 2FA 是强有力的第二因素 —— 鼓励玩家启用 2FA 并保持较低的登录尝试次数限制。捆绑的 config.yml 文件中详细记录了这些权衡取舍。
命令
| 命令 |
描述 |
权限节点 |
/register <password> <password> |
注册账户 |
serverauth.use |
/login <password> |
登录 |
serverauth.use |
/changepassword <old> <new> <confirm> (别名 /cpw) |
更改密码 |
serverauth.use |
/logout |
登出 |
serverauth.use |
/autologin <on|off|status> |
可信 IP 自动登录开关 |
serverauth.use |
/recovery <setquestion|setanswer|status> |
配置账户恢复信息 |
serverauth.use |
/recover |
恢复账户(通过问题答案或 2FA 代码) |
serverauth.use |
/2fa <setup|confirm|code|verify|disable|status> (别名 /twofa, /totp) |
管理双因素认证 |
serverauth.use |
/authhelp |
认证帮助 |
serverauth.use |
/help |
/authhelp 的别名(仅在 override-help-command 启用时生效) |
serverauth.use |
/authadmin <lookup|setpassword|delete|reset2fa|reload> <player> [args] |
管理员账户管理 |
serverauth.admin |
权限节点
| 节点 |
描述 |
默认值 |
serverauth.use |
使用认证相关命令 |
true |
serverauth.admin |
使用 /authadmin(还需具备 OP 权限及管理员自身的 2FA) |
op |
配置
config.yml 中的关键部分:
password:
min-length: 6
require-confirm-match: true
security:
max-login-attempts: 5
login-lockout-seconds: 300
bcrypt-cost: 12 # 范围 10-16;数值越高 = 越慢且更安全
two-factor:
enabled: true
backup-code-count: 8
max-verify-attempts: 5
verify-lockout-seconds: 300
setup-token-expiry-minutes: 15
# 用于 2FA 设置页面的内置 Web 服务器
web-server:
enabled: true
port: 8921
host: "0.0.0.0" # 127.0.0.1 = 仅限本地(更安全)
public-url: "http://localhost:8921"
storage:
type: sqlite # sqlite 或 mysql
sqlite:
file: "auth.db"
mysql:
host: "localhost"
port: 3306
database: "minecraft"
username: "root"
password: ""
use-ssl: false
Web 服务器(2FA 设置页面)
该插件运行一个小型 HTTP 服务器(默认端口 8921),用于渲染 2FA 设置页面。QR 码在本地生成,因此 TOTP 密钥永远不会离开你的机器 —— 但该页面本身使用的是纯 HTTP。
port —— 设置页面监听的 TCP 端口。
host —— 绑定地址。0.0.0.0 会在所有网络接口上暴露服务;127.0.0.1 将其限制在本地机器上(如果玩家从服务器主机设置 2FA,或者反向代理也在本地运行,推荐此选项)。
public-url —— 玩家在聊天中看到的 URL。请将其设置为你的域名/IP。
推荐的加固措施: 如果玩家需要远程访问设置页面,请将 Web 服务器置于反向代理(nginx/Caddy)后面以终止 HTTPS,将插件绑定到 127.0.0.1,并将 public-url 设置为 https:// 地址。避免将原始 HTTP 端口暴露在公共互联网上。
config.yml 中其他重要的内联文档部分包括:lockdown(冻结行为、登录出生点、允许的命令)、autologin 和 fingerprint(四层验证)、floodgate(基岩版自动登录)以及 policy(要求 OP/管理员启用 2FA、max-accounts-per-ip、非活动超时)。
安装
- 需要 Paper 或 Purpur 26.3 以及 Java 25(2.0.0 版运行于 26.2,1.x 版运行于 1.21.x)。
- 将 JAR 文件放入
plugins/ 文件夹,然后启动服务器一次以生成 config.yml。
- 检查
web-server、security 和 storage 部分,然后运行 /authadmin reload(或重启服务器)。
依赖项
- Floodgate (可选) — 启用 Bedrock 跨平台自动登录。未安装时,Bedrock 玩家将像 Java 玩家一样注册/登录。
- PlayerSettings (可选) — 如果已安装,支持按玩家设置语言选择。
无强制依赖;SQLite/MySQL 驱动及加密库均已内置。
支持 / 源码
源代码:
ServerAUTH
Password + TOTP two-factor authentication for Paper/Purpur 26.3
Version 2.1.0 · Minecraft 26.3 · Java 25 · Server-side
ServerAUTH is a login/registration plugin built for offline-mode and proxy
setups, where the vanilla client identity cannot be trusted. Players register
with a password, log in on every join, and can protect their account with a
TOTP second factor (Google Authenticator, Authy, etc.). Passwords and recovery
answers are hashed with BCrypt; the 2FA setup page is served by a built-in
local web server so players can scan a QR code in their browser.
Features
- Password authentication with BCrypt hashing (configurable cost 10-16) and
confirm-match on registration.
- TOTP two-factor authentication (RFC 6238, Google Authenticator compatible)
with hashed backup codes and per-account verify lockout.
- Built-in web server for 2FA setup: the QR code and secret are generated
locally (never sent to a third party) and shown on a page you can put behind a
reverse proxy.
- Login lockdown for unauthenticated players: movement, chat, commands,
inventory and interactions are frozen, optional blindness, and teleport to a
configurable login spawn that can hide real coordinates.
- Reconnect grace period: reconnect from the same IP within a window without
re-entering the password (2FA is always re-challenged, never skipped).
- 4-layer auto-login (username / UUID / IP / client fingerprint) with clear
documentation of what each layer is worth on offline-mode servers.
- Account recovery via a security question/answer or a valid 2FA code,
both rate-limited with lockout.
- Bedrock crossplay: optional auto-login for Floodgate players (their Xbox
Live identity is verified before they reach the server).
- Admin tooling:
/authadmin (requires OP and the admin's own 2FA) to look
up, reset or delete accounts.
- Security logging with sensitive-command redaction, optional OP alerts on
failed logins and UUID mismatches.
- Storage: SQLite (default) or MySQL, via a connection pool with versioned
schema migrations.
- Policies: require 2FA for OPs/admins, limit accounts per IP, session and
inactivity timeouts.
Offline-mode / proxy note
On offline-mode servers a player's UUID is derived from their name, so UUID and
client-fingerprint checks are defence-in-depth only and can be spoofed. On
these servers the password is the real gate and 2FA is the strong second
factor — encourage players to enable 2FA and keep login attempt limits low.
The bundled config.yml documents these trade-offs in detail.
Commands
| Command |
Description |
Permission |
/register <password> <password> |
Register an account |
serverauth.use |
/login <password> |
Log in |
serverauth.use |
/changepassword <old> <new> <confirm> (alias /cpw) |
Change your password |
serverauth.use |
/logout |
Log out |
serverauth.use |
/autologin <on|off|status> |
Trusted-IP auto-login toggle |
serverauth.use |
/recovery <setquestion|setanswer|status> |
Configure account recovery |
serverauth.use |
/recover |
Recover an account (question answer or 2FA code) |
serverauth.use |
/2fa <setup|confirm|code|verify|disable|status> (aliases /twofa, /totp) |
Manage two-factor auth |
serverauth.use |
/authhelp |
Authentication help |
serverauth.use |
/help |
Alias for /authhelp (only when override-help-command is enabled) |
serverauth.use |
/authadmin <lookup|setpassword|delete|reset2fa|reload> <player> [args] |
Admin account management |
serverauth.admin |
Permissions
| Node |
Description |
Default |
serverauth.use |
Use the authentication commands |
true |
serverauth.admin |
Use /authadmin (also requires OP + the admin's own 2FA) |
op |
Configuration
Key sections of config.yml:
password:
min-length: 6
require-confirm-match: true
security:
max-login-attempts: 5
login-lockout-seconds: 300
bcrypt-cost: 12 # 10-16; higher = slower & stronger
two-factor:
enabled: true
backup-code-count: 8
max-verify-attempts: 5
verify-lockout-seconds: 300
setup-token-expiry-minutes: 15
# Built-in web server for the 2FA setup page
web-server:
enabled: true
port: 8921
host: "0.0.0.0" # 127.0.0.1 = local only (safer)
public-url: "http://localhost:8921"
storage:
type: sqlite # sqlite or mysql
sqlite:
file: "auth.db"
mysql:
host: "localhost"
port: 3306
database: "minecraft"
username: "root"
password: ""
use-ssl: false
Web server (2FA setup page)
The plugin runs a small HTTP server (default port 8921) that renders the 2FA
setup page. The QR code is produced locally, so the TOTP secret never leaves
your machine — but the page itself is plain HTTP.
port — the TCP port the setup page listens on.
host — bind address. 0.0.0.0 exposes it on all interfaces;
127.0.0.1 restricts it to the local machine (recommended if players set
up 2FA from the server host, or if a reverse proxy runs locally).
public-url — the URL players see in chat. Set it to your domain/IP.
Recommended hardening: if players need remote access to the setup page, put
the web server behind a reverse proxy (nginx/Caddy) that terminates HTTPS,
bind the plugin to 127.0.0.1, and set public-url to the https:// address.
Avoid exposing the raw HTTP port to the public internet.
Other important sections documented inline in config.yml: lockdown (freeze
behaviour, login spawn, allowed commands), autologin and fingerprint
(4-layer verification), floodgate (Bedrock auto-login), and policy
(require-2fa-for-ops/admins, max-accounts-per-ip, inactivity timeout).
Installation
- Requires Paper or Purpur 26.3 and Java 25 (2.0.0 runs on 26.2, 1.x on 1.21.x).
- Drop the JAR into your
plugins/ folder and start the server once to
generate config.yml.
- Review the
web-server, security and storage sections, then run
/authadmin reload (or restart).
Dependencies
- Floodgate (optional) — enables Bedrock crossplay auto-login. Without it,
Bedrock players simply register/log in like Java players.
- PlayerSettings (optional) — per-player language selection, if installed.
No hard dependencies; SQLite/MySQL drivers and the crypto libraries are bundled.
Support / Source
Source code:
评论 0
登录后参与评分
还没有评论,来抢沙发吧