EzAuth
适用于现代 Paper 和 Bukkit 服务器的即插即用身份验证插件,拥有精致的用户体验,支持独立或集成 TOTP 双因素认证(2FA),并提供灵活的存储方案。

概览
EzAuth 通过基于电子邮件的注册、密码登录以及限时会话来锁定服务器的出生点。玩家将在可配置的消息、多语言提示(默认提供英语、荷兰语、西班牙语)、视觉效果和提醒的引导下完成流程,而管理员则完全掌控存储后端、安全策略以及可选的 SMTP 设置。您可以在纯登录、可选的 2FA 或独立双因素模式之间切换;后者将 EzAuth 的 /2fa 体验叠加到任何现有的身份验证插件之上。新功能: 引导管理员完成游戏内安装过程,在安装完成后立即重新锁定所有活跃会话;利用新的会话缓存层实现登录后即时检查;并直接对接 Laravel、WordPress 或 XenForo 的用户表,使您的网站与服务器共享单一账户系统。
主要功能
- 以玩家为中心的入职流程 –
/register 验证电子邮件,强制执行可配置的密码长度,阻止重复的电子邮件或账户,并采用异步保存方式,确保玩家不会阻塞主线程。
- 游戏内安装向导 –
/ezauth install 指导工作人员进行开服当天的设置,可选择在准备好之前绕过登录守卫,并在标记安装完成后立即重新锁定每个活跃会话。
- 本地化消息 – 分发多种语言包(默认提供英语、荷兰语、西班牙语),设置默认语言,并允许玩家在加入时选择他们偏好的消息集合。
- 强化的登录体验 –
/login 遵循分阶段冷却时间,尊重绕过权限,缓存账户以加快检查速度,并在后台线程运行密码哈希处理,最后通过可选的特效庆祝登录成功。
- 内置 TOTP 双因素认证 –
/2fa 引导玩家完成设置、确认、验证、状态检查和禁用流程,同时 TwoFactorService 生成安全密钥并验证代码。将 security.yml 中的 authentication-type 设置为 two_factor,即可让 EzAuth 作为独立的 2FA 模块运行,可与 AuthMe 等插件或通过代理网络配合使用。
- 会话控制 – 在身份验证完成之前,移动、聊天和非白名单命令将被阻止,并提供五秒一次的提醒以及自动会话超时机制,可重新锁定闲置玩家。
- 会话缓存 – 按服务器和跨代理缓存活跃的身份验证信息,减少数据库访问次数,并确保受信任的玩家在快速重启期间保持在线。
- 书本式提示 – 启用
authentication-input: book 可通过交互式书本来捕获密码和 2FA 代码,如果玩家过早关闭书本,系统将自动重新提示。
- 庆祝性细节 – 可在
security.yml 中全局禁用或为每个事件单独开启粒子效果和声音。
- 灵活的存储 – 选择 YAML 文件、由 EzAuth 管理的 MySQL 表,或通过新的集成块直接对接 Laravel、WordPress 和 XenForo 架构,同时仍支持按 UUID 或用户名存储账户。
- 可配置的哈希算法 – 无需修改代码即可在 BCrypt(自定义轮数)、带椒盐的 SHA-256 或 WordPress PHPass 之间切换。
- 邮件就绪 –
email.yml 暴露了 SMTP 主机、端口、TLS/SSL、凭据、发件人身份以及任意邮件属性,让您在需要发送出站消息时随时准备就绪。
- 电子邮件验证 – 向新注册用户发送验证码,阻止未验证的登录,并允许玩家使用
/email 命令确认或重新发送验证码。
- 敏感命令过滤 – 通过在
security.yml 中列出敏感命令,从控制台日志中隐藏身份验证尝试,使工作人员聊天保持整洁,且日志过滤器会在重载时自动更新。
- 管理员监控 –
/ezauth players 打开一个分页的游戏内 GUI,显示账户电子邮件、创建时间和 2FA 状态,以便工作人员无需使用控制台命令即可禁用双因素认证或移除注册信息。

身份验证类型
- 登录 – 经典的 EzAuth 流程,包含
/register、/login 以及用于分层安全的可选 /2fa。
- 独立 2FA – 保留您现有的密码解决方案,但通过设置
authentication-type: two_factor 为玩家提供 EzAuth 精致的身份验证器设置、代码检查和管理员控制。非常适合那些标准化使用 AuthMe、MultiAuth 或代理级 SSO,但仍希望在游戏中实施 TOTP 强制验证的网络。
- 可选 – 让玩家在他们准备好的时候保护其账户,同时为您维持其他人的传统登录方式。
命令与权限
| 命令 |
用法 |
权限 |
默认值 |
| /register |
/register <email> <password> <password> |
ezauth.register |
所有人 |
| /login |
/login <password> |
ezauth.login |
所有人 |
| /2fa, /twofactor |
/2fa <setup |
confirm |
verify |
| /email |
/email <verify |
resend> |
ezauth.email |
| - |
- |
ezauth.2fa.admin |
OP |
| /ezauth |
/ezauth reload |
ezauth.reload |
OP |
| /ezauth install |
/ezauth install <status |
complete |
reset |
| - |
- |
ezauth.bypass |
OP |
安装
首次启动 EzAuth,让新的安装工作流承担繁重的工作:
- 使用
/ezauth install status 确认引导流程处于活动状态,并查看登录守卫是否暂时被绕过。
- 通过
/ezauth install config 在游戏内调整安装选项,以启用提醒、禁用绕过模式或稍后重新打开 GUI。
- 一旦您的存储、哈希和安全文件看起来正确无误,使用
/ezauth install complete 完成操作,这将重新锁定每个已连接的玩家,直到他们完成身份验证。
- 需要为新赛季重新进行入职流程吗?
/ezauth install reset 将重新打开流程,而不会影响现有账户。
快速配置预设
选择与您的部署相匹配的基线,并将代码片段复制到生成的配置文件中。
YAML 存储 + 密码登录
非常适合不需要数据库的单服务器设置。账户数据保存在磁盘上,并使用 BCrypt 确保密码安全。
# database.yml
storage-type: yml
account-identifier: uuid
yaml-file: registrations.yml
integration:
mode: none
# hashing.yml
algorithm: bcrypt
bcrypt:
rounds: 10
# security.yml
authentication-type: login
particles-enabled: false
sounds-enabled: false
托管 MySQL + 登录
将玩家数据存储到 EzAuth 的 MySQL 模式中,同时保留经典的 /register 和 /login 体验。
# database.yml
storage-type: mysql
account-identifier: uuid
host: localhost
port: 3306
name: ezauth
username: ezauth
password: changeme
jdbc-parameters: useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
integration:
mode: none
# hashing.yml
algorithm: bcrypt
bcrypt:
rounds: 12
# security.yml
authentication-type: login
session:
timeout-minutes: 15
particles-enabled: true
sounds-enabled: true
独立双因素认证模块
将 EzAuth 与其他身份验证插件配合使用,仅用于管理 /2fa。
# database.yml
storage-type: mysql
account-identifier: uuid
host: localhost
port: 3306
name: ezauth
username: ezauth
password: changeme
jdbc-parameters: useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
integration:
mode: none
# hashing.yml
# 在独立双因素认证模式下不使用哈希功能,但保留默认值以兼容旧版本。
algorithm: bcrypt
bcrypt:
rounds: 10
# security.yml
authentication-type: two_factor
two-factor:
standalone-mode: true
enforce-on-join: true
session:
timeout-minutes: 10
WordPress 集成 + 共享账户
将 Minecraft 登录连接到现有的 WordPress 网站,并同步可选的双因素认证状态。
# database.yml
storage-type: mysql
account-identifier: username
host: localhost
port: 3306
name: wordpress
username: wp_user
password: supersecret
jdbc-parameters: useSSL=false&characterEncoding=UTF-8
integration:
mode: wordpress
wordpress:
table-prefix: wp_
users-table: wp_users
user-meta-table: wp_usermeta
username-column: user_login
email-column: user_email
password-column: user_pass
uuid-meta-key: minecraft_uuid
two-factor-secret-meta-key: ezauth_2fa_secret
two-factor-confirmed-meta-key: ezauth_2fa_confirmed
# hashing.yml
algorithm: wordpress
# security.yml
authentication-type: login
two-factor:
optional: true
locale:
default-language: en_US
默认配置
database.yml 现在包含一个 integration 部分,允许您复用 Laravel、WordPress 或 XenForo 的数据表,同时保持 EzAuth 熟悉的命令操作。请根据实际部署更新表和列名,或者将模式设置为 none 以保持 EzAuth 管理的独立模式。
# EzAuth Storage Configuration
storage-type: yml
account-identifier: uuid
yaml-file: registrations.yml
host: localhost
port: 3306
name: ezauth
username: root
password: password
jdbc-parameters: useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
pool:
maximum-pool-size: 10
minimum-idle: 2
connection-timeout: 30000
idle-timeout: 600000
max-lifetime: 1800000
data-source-properties:
cachePrepStmts: "true"
prepStmtCacheSize: "250"
prepStmtCacheSqlLimit: "2048"
integration:
mode: none
laravel:
table: users
uuid-column: uuid
username-column: name
email-column: email
password-column: password
two-factor-secret-column: two_factor_secret
two-factor-confirmed-column: two_factor_confirmed
created-at-column: created_at
updated-at-column: updated_at
remember-token-column: remember_token
wordpress:
table-prefix: wp_
users-table: wp_users
user-meta-table: wp_usermeta
username-column: user_login
email-column: user_email
password-column: user_pass
created-at-column: user_registered
uuid-meta-key: minecraft_uuid
two-factor-secret-meta-key: ezauth_two_factor_secret
two-factor-confirmed-meta-key: ezauth_two_factor_confirmed
xenforo:
table-prefix: xf_
user-table: xf_user
user-auth-table: xf_user_authenticate
user-field-value-table: xf_user_field_value
user-profile-table: xf_user_profile
username-column: username
email-column: email
created-at-column: register_date
uuid-field-id: minecraft_uuid
two-factor-secret-field-id: ezauth_two_factor_secret
two-factor-confirmed-field-id: ezauth_two_factor_confirmed
在使用 WordPress 之前,需要进行一些额外的调整:
- 将
hashing.yml 中的 algorithm 更改为 WORDPRESS_PHPASS,以便 EzAuth 生成与 WordPress PHPass 实现兼容的哈希值。
- 保留 UUID 和双因素元键(默认为
minecraft_uuid、ezauth_two_factor_secret、ezauth_two_factor_confirmed),或者将其调整为与您现有数据匹配的值。
- 如果您的 WordPress 实例使用了自定义前缀,请更新表前缀或表名。
对于 XenForo 部署,应在 XenForo 控制面板中创建三个自定义文本用户字段,分别对应配置的 uuid-field-id、two-factor-secret-field-id 和 two-factor-confirmed-field-id。每当 EzAuth 更新账户时,它会确保 xf_user_field_value、xf_user_profile.custom_fields 和 xf_user_authenticate 中的数据保持一致。
Laravel 模式应暴露 UUID 和双因素列, alongside 框架默认的字段(remember_token、created_at、updated_at)。如果您使用的是 Jetstream 或 Breeze,请添加以下迁移脚本,以便 EzAuth 可以重用您的用户表而不丢失数据:
// Laravel 迁移文件
Schema::table('users', function (Blueprint $table) {
$table->uuid('uuid')->unique()->after('id');
$table->text('two_factor_secret')->nullable()->after('password');
$table->boolean('two_factor_confirmed')->default(false)->after('two_factor_secret');
});
EzAuth 在更新现有的 Laravel 用户时会保留双重验证相关值,并为新行填充时间戳和记住令牌(remember token)。
哈希默认设置
# hashing.yml
algorithm: BCRYPT
bcrypt:
rounds: 10
sha256:
pepper: ""
安全默认设置
# security.yml
require-email-validation: true
min-password-length: 8
session-timeout-seconds: 300
login-enabled: true
register-enabled: true
bypass-enabled: true
login:
cooldown:
enabled: true
stages:
- attempts: 3
cooldown-seconds: 10
- attempts: 5
cooldown-seconds: 60
two-factor:
enabled: false
issuer: EzAuth
required-for-login: false
secure-account-welcome-message:
- "%prefix%&a您的账户现已启用双重身份验证,%player%!"
allowed-commands-while-unauthenticated:
- login
- register
- 2fa
- twofactor
visual-effects:
enabled: true
login:
enabled: true
particle: VILLAGER_HAPPY
particle-count: 30
particle-offset-x: 0.0
particle-offset-y: 1.0
particle-offset-z: 0.0
particle-spread-x: 0.25
particle-spread-y: 0.35
particle-spread-z: 0.25
sound: ENTITY_PLAYER_LEVELUP
sound-volume: 1.0
sound-pitch: 1.2
register:
enabled: true
particle: FIREWORKS_SPARK
particle-count: 50
particle-offset-x: 0.0
particle-offset-y: 1.0
particle-offset-z: 0.0
particle-spread-x: 0.4
particle-spread-y: 0.6
particle-spread-z: 0.4
sound: UI_TOAST_CHALLENGE_COMPLETE
sound-volume: 1.0
sound-pitch: 1.0
安全模式(仅 2FA 模式)
# EzAuth Security Configuration (2FA-only mode)
require-email-validation: false
min-password-length: 8
session-timeout-seconds: 0
login-enabled: false
register-enabled: false
bypass-enabled: false
login:
cooldown:
enabled: false
stages: []
two-factor:
enabled: true
issuer: EzAuth
required-for-login: false
secure-account-welcome-message:
- "%prefix%&a您的账户现已启用双重身份验证,%player%!"
allowed-commands-while-unauthenticated:
- 2fa
- twofactor
visual-effects:
enabled: false
messages.yml(示例)
# messages.yml
default-language: en
languages:
en:
name: 'English'
file: 'messages/en.yml'
aliases:
- 'en_us'
- 'en-gb'
nl:
name: 'Nederlands'
file: 'messages/nl.yml'
aliases:
- 'nl_nl'
- 'nl-be'
es:
name: 'Español'
file: 'messages/es.yml'
aliases:
- 'es_es'
- 'es-mx'
prefix: '&7[&bEzAuth&7] '
register:
usage: '%prefix%&c用法:/register <email> <password> <password>'
success: '%prefix%&a您已使用 &f%email%&a 注册成功。欢迎!'
already-registered: '%prefix%&c您已注册。请使用 /login <password> 进行登录。'
email-in-use: '%prefix%&c该电子邮件地址已与另一个账户关联。'
invalid-email: '%prefix%&c请输入有效的电子邮件地址。'
password-mismatch: '%prefix%&c两次输入的密码不匹配。'
password-too-short: '%prefix%&c密码长度必须至少为 &f%length%&c 个字符。'
prompt: '%prefix%&e使用 &f/register <email> <password> <password> 创建账户'
disabled: '%prefix%&c当前禁用注册。请联系管理员以创建账户。'
login:
usage: '%prefix%&c用法:/login <password>'
success: '%prefix%&a您已成功登录。'
success-with-email: '%prefix%&a您已使用 &f%email%&a 登录。'
not-registered: '%prefix%&c未找到账户。请使用 /register <email> <password> <password> 进行注册。'
invalid-password: '%prefix%&c密码错误。请重试。'
already-logged-in: '%prefix%&c您已处于登录状态。'
cooldown-active: '%prefix%&c失败尝试次数过多。请等待 &f%seconds%&c 秒后再试。'
prompt: '%prefix%&e欢迎回来!请使用 &f/login <password> 登录'
bypass: '%prefix%&a已启用绕过:您已通过身份验证。'
disabled: '%prefix%&e此服务器当前禁用了密码登录。'
general:
no-permission: '%prefix%&c您没有权限使用此命令。'
players-only: '%prefix%&c只有玩家才能执行此命令。'
error: '%prefix%&c发生内部错误。请联系管理员。'
not-authenticated: '%prefix%&c请使用 %methods% 进行身份验证。'
already-authenticated: '%prefix%&c您已通过身份验证。'
admin:
reload:
usage: '%prefix%&e用法:/ezauth reload'
success: '%prefix%&aEzAuth 配置重新加载成功。'
failed: '%prefix%&cEzAuth 配置重新加载失败。请查看控制台以获取详细信息。'
twofactor:
disabled: '%prefix%&c此服务器未启用双因素认证。'
usage: '%prefix%&e用法:/2fa <setup|confirm|verify|disable|status>'
confirm-usage: '%prefix%&c用法:/2fa confirm '
verify-usage: '%prefix%&c用法:/2fa verify '
disable-usage: '%prefix%&c用法:/2fa disable <code|player>'
setup: '%prefix%&a使用下方的密钥或设置 URL,将此账户添加到你的身份验证器应用中。'
secret-line: '%prefix%&7密钥:&b&n%secret% &8(点击复制)'
secret-hover: '&b点击将你的 2FA 密钥复制到剪贴板。'
uri-line: '%prefix%&7设置 URL:&f%uri%'
already-enabled: '%prefix%&c双因素认证已启用。'
setup-required: '%prefix%&c在继续之前,你必须先通过 &f/2fa setup&c 设置双因素认证。'
setup-optional: '%prefix%&e当你准备好时,可以随时使用 &f/2fa setup&e 来保护你的账户。'
login-required: '%prefix%&c请输入有效的 2FA 代码以完成登录:&f/2fa verify &c。'
auth-required: '%prefix%&c请在使用 /2fa 命令前先通过 &f/login&c 登录。'
invalid-code: '%prefix%&c该 2FA 代码无效或已过期。请重试。'
enabled: '%prefix%&a双因素认证成功启用。'
verified: '%prefix%&a双因素认证已完成。你现在已登录。'
disabled-success: '%prefix%&a你的账户的双因素认证已禁用。'
admin-disabled-success: '%prefix%&a已为 &f%target%&a 禁用双因素认证。'
admin-disabled-notify: '%prefix%&c你的双因素认证已被 &f%admin%&c 禁用。'
admin-self-target: '%prefix%&c要禁用自己的双因素认证,请运行 &f/2fa disable &c。'
admin-target-not-found: '%prefix%&c未找到 &f%target%&c 的 EzAuth 账户。'
admin-target-not-enabled: '%prefix%&c&f%target%&c 未启用双因素认证。'
not-setup: '%prefix%&c你尚未生成双因素密钥。请先使用 /2fa setup。'
not-confirmed: '%prefix%&c你必须先通过 /2fa confirm 确认你的双因素密钥才能使用它。'
not-enabled: '%prefix%&c目前你的账户未启用双因素认证。'
no-account: '%prefix%&c未找到你的玩家对应的 EzAuth 账户。请先注册。'
status-enabled: '%prefix%&a你的账户已启用双因素认证。'
status-pending: '%prefix%&e双因素认证设置等待确认。'
status-disabled: '%prefix%&e你的账户目前未启用双因素认证。'
## 支持代理的会话存储
需要在服务器网络中保持玩家的身份状态?在 `security.yml` 中将 `proxy.enabled: true` 设为开启,EzAuth 将自动切换到基于共享 SQL 的会话存储。插件会创建所需的 `ezauth_sessions` 表,在各实例间同步登录状态,并遵循 `proxy.session-ttl-seconds` 配置,让你可以控制网络级登录的有效时长,超时后玩家需重新认证。将其设置为 `0` 则完全依赖由 `session-timeout-seconds` 定义的单服务器超时时间。
_此代理支持仍处于实验阶段,建议在部署到生产环境网络前进行充分测试。_
注意:分布式会话需要 `database.yml` 中定义的 MySQL 后端。如果你仅使用 YAML 存储,EzAuth 将拒绝启动代理缓存。
## 准备邮件通知
EzAuth 现在附带一个可选的 `email.yml` 配置文件,允许你在启用出站消息支持之前预先加载 SMTP 详情。如果不想配置,可将该部分保持禁用;如果启用,请提供主机、端口、传输协议(TLS/SSL)、凭据和发件人标识,以便在电子邮件验证或警报功能上线时,EzAuth 随时可用。
```yaml
smtp:
enabled: false
host: smtp.example.com
port: 587
username: no-reply@example.com
password: "changeme"
use-starttls: true
from-name: "EzAuth"
from-address: no-reply@example.com
- 在准备好填入有效凭据之前,请保持
enabled 为 false。
- 如果你的提供商要求使用隐式 SSL,请切换
use-starttls 或将 port 设置为 465。
- 将邮件通知与
/email 下的验证命令配合使用,可在玩家登录前阻止未验证的账户。
将 EzAuth 连接到你的网站登录
无论你是运行 Laravel、WordPress 还是 XenForo,EzAuth 都可以让玩家使用与你网站相同的凭据进行认证。在设置 storage-type: mysql 后,请按照以下步骤操作以适配你的平台。
Laravel 集成
- 打开
plugins/EzAuth/database.yml,并将 integration.mode 设置为 laravel。
- 将 MySQL 连接设置指向你的 Laravel 站点所使用的数据库(通常是
.env 中的值)。
- 确保
integration.laravel 块中的列名与你的 users 表匹配。如果你使用 UUID,请保留 uuid-column;否则将 account-identifier 设置为 username。
- 如果你依赖 Laravel 的 remember tokens 或双因素相关字段,请保持映射——当玩家登录或切换
/2fa 时,EzAuth 会自动读取和更新这些字段。
- 重载 EzAuth 或重启服务器。新注册的账户将通过 Laravel 的哈希算法(BCrypt)写回数据库,这样同一密码即可在网站和 Minecraft 服务器上通用。
WordPress 集成
- 将
storage-type 设置为 mysql,并将 integration.mode 设置为 wordpress。
- 使用来自
wp-config.php 的数据库凭据,以便 EzAuth 连接到与 WordPress 相同的 MySQL 实例。
- 如果你的安装使用了自定义前缀,请调整
integration.wordpress.table-prefix,然后确认 users 和 usermeta 表名。
- 将 EzAuth 的 UUID 和双因素认证(2FA)字段映射到已存在的元键上(或让 EzAuth 自动创建它们)。当你在
hashing.yml 中启用 hashing.algorithm: wordpress 时,密码将通过 WordPress 的 PHPass 算法进行校验。
- 重载 EzAuth。玩家现在可以使用他们的 WordPress 凭据执行
/login,可选的 /2fa 状态将同步到用户元数据行中。
XenForo 集成
- 将
integration.mode 切换为 xenforo,并提供 XenForo 所使用的相同 MySQL 详细信息。
- 确认
integration.xenforo 块中的表前缀和列名。EzAuth 将从 xf_user 读取用户名,并从 xf_user_authenticate 读取哈希密码。
- 如果你将 Minecraft UUID 或 2FA 密钥存储在自定义个人资料字段中,请更新
uuid-field-id 和 two-factor-* 标识符,以便 EzAuth 同步正确的值。
- 确保
hashing.yml 设置为 algorithm: xenforo,以便 EzAuth 能够正确验证 XenForo 的 bcrypt 变体。
- 重载 EzAuth 或重启服务器以应用更改。服务器登录现在将对 XenForo 账户进行验证,从而保持论坛和游戏中的凭据统一。
入门指南
- 将 jar 文件放入你的
/plugins 文件夹,并启动服务器一次以生成配置文件。
- 编辑
database.yml、hashing.yml 和 security.yml,使其匹配你的存储、哈希和安全策略。
- 如果计划稍后发送基于电子邮件的通知,请配置
email.yml。
- 调整
messages.yml 以符合你社区的语气,然后在游戏内运行 /ezauth reload。
- 邀请玩家使用
/register、/login,以及可选的 /2fa setup 以获得全面保护。
需要帮助?
EzAuth 正在积极开发中,因此你的反馈将直接塑造路线图。你可以 加入我们的 Discord 服务器 获取实时支持、功能请求和更新。

EzAuth
Drop-in authentication for modern Paper and Bukkit servers with polished UX, standalone or integrated TOTP 2FA, and flexible storage.

Overview
EzAuth locks down your server's spawn with email-backed registrations, password logins, and time-limited sessions. Players are guided through the process with configurable messages, multi-language prompts (English, Nederlands, Español out of the box), visual effects, and reminders while administrators retain full control over storage backends, security policy, and optional SMTP settings. Toggle between pure login, opt-in 2FA, or a standalone two-factor flow that layers EzAuth's /2fa experience onto any existing authentication plugin. New: guide administrators through an in-game installation that immediately re-locks every active session when setup finishes, tap into the new session caching layer for instant post-login checks, then hook directly into Laravel, WordPress, or XenForo user tables so your website and server share a single account system.
Key Features
- Player-first onboarding –
/register validates emails, enforces configurable password lengths, blocks duplicate emails or accounts, and saves asynchronously so players never stall the main thread.
- Guided ingame installation –
/ezauth install walks staff through launch day setup, optionally bypasses the login guard until you're ready, and re-locks every active session the moment installation is marked complete.
- Localized messaging – Ship multiple language packs (English, Nederlands, Español by default), set your default language, and let players opt into their preferred message set on join.
- Hardened logins –
/login honours staged cooldowns, respects bypass permissions, caches accounts for quicker checks, and runs password hashing off-thread before celebrating success with optional effects.
- Built-in TOTP two-factor –
/2fa walks players through setup, confirmation, verification, status checks, and disabling while the TwoFactorService generates secure secrets and verifies codes. Flip security.yml's authentication-type to two_factor to run EzAuth as a standalone 2FA module alongside plugins like AuthMe or via proxy networks.
- Session control – Movement, chat, and non-whitelisted commands are blocked until authentication completes, with five-second reminders and automatic session timeouts that can re-lock idle players.
- Session caching – Cache active authentications per-server and across proxies to trim database hits and keep trusted players online through quick restarts.
- Book-based prompts – Toggle
authentication-input: book to capture passwords and 2FA codes through an interactive written book, with automatic re-prompts if a player closes it early.
- Celebratory polish – Toggle per-event particles and sounds or disable them globally from
security.yml.
- Flexible storage – Choose YAML files, EzAuth-managed MySQL tables, or hook directly into Laravel, WordPress, and XenForo schemas via the new integration block while still storing accounts by UUID or username.
- Configurable hashing – Switch between BCrypt (custom rounds), SHA-256 with a pepper, or WordPress PHPass without touching code.
- Email-ready –
email.yml exposes SMTP host, port, TLS/SSL, credentials, sender identity, and arbitrary mail properties so you're ready when outbound messaging lands.
- Email verification – Send verification codes to new registrations, block unverified logins, and let players confirm or resend their code with
/email commands.
- Sensitive command filtering – Hide authentication attempts from console logs by listing sensitive commands in
security.yml so staff chats stay clean while log filters update automatically on reloads.
- Admin oversight –
/ezauth players opens a paginated in-game GUI with account email, creation time, and 2FA status so staff can disable two-factor or remove registrations without console commands.

Authentication Types
- Login – The classic EzAuth flow with
/register, /login, and optional /2fa for layered security.
- Standalone 2FA – Keep your existing password solution but give players EzAuth's polished authenticator setup, code checks, and admin controls by setting
authentication-type: two_factor. Perfect for networks standardising on AuthMe, MultiAuth, or proxy-level SSO that still want in-game TOTP enforcement.
- Optional – Let players secure their account when they're ready while you maintain traditional logins for everyone else.
Commands & Permissions
| Command |
Usage |
Permission |
Default |
| /register |
/register <email> <password> <password> |
ezauth.register |
Everyone |
| /login |
/login <password> |
ezauth.login |
Everyone |
| /2fa, /twofactor |
/2fa <setup |
confirm |
verify |
| /email |
/email <verify |
resend> |
ezauth.email |
| - |
- |
ezauth.2fa.admin |
OP |
| /ezauth |
/ezauth reload |
ezauth.reload |
OP |
| /ezauth install |
/ezauth install <status |
complete |
reset |
| - |
- |
ezauth.bypass |
OP |
Installation
Launch EzAuth for the first time and let the new installation workflow do the heavy lifting:
- Use
/ezauth install status to confirm the guided flow is active and view whether the login guard is temporarily bypassed.
- Tweak installation options in-game with
/ezauth install config to enable reminders, disable bypass mode, or re-open the GUI later.
- Once your storage, hashing, and security files look right, finish with
/ezauth install complete to re-lock every connected player until they authenticate.
- Need to re-run onboarding for a new season?
/ezauth install reset re-opens the flow without touching existing accounts.
Quick Configuration Presets
Choose the baseline that matches your deployment and copy the snippets into your generated configs.
YAML Storage + Password Login
Perfect for single-server setups that don't need a database. Accounts are saved to disk and BCrypt keeps passwords safe.
# database.yml
storage-type: yml
account-identifier: uuid
yaml-file: registrations.yml
integration:
mode: none
# hashing.yml
algorithm: bcrypt
bcrypt:
rounds: 10
# security.yml
authentication-type: login
particles-enabled: false
sounds-enabled: false
Managed MySQL + Login
Stores players in EzAuth's MySQL schema while retaining the classic /register + /login experience.
# database.yml
storage-type: mysql
account-identifier: uuid
host: localhost
port: 3306
name: ezauth
username: ezauth
password: changeme
jdbc-parameters: useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
integration:
mode: none
# hashing.yml
algorithm: bcrypt
bcrypt:
rounds: 12
# security.yml
authentication-type: login
session:
timeout-minutes: 15
particles-enabled: true
sounds-enabled: true
Standalone 2FA Module
Pair EzAuth with another authentication plugin and only use it for /2fa management.
# database.yml
storage-type: mysql
account-identifier: uuid
host: localhost
port: 3306
name: ezauth
username: ezauth
password: changeme
jdbc-parameters: useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
integration:
mode: none
# hashing.yml
# Hashing is unused in standalone 2FA mode but keep defaults for compatibility.
algorithm: bcrypt
bcrypt:
rounds: 10
# security.yml
authentication-type: two_factor
two-factor:
standalone-mode: true
enforce-on-join: true
session:
timeout-minutes: 10
WordPress Integration + Shared Accounts
Connect Minecraft logins to your existing WordPress site and sync optional two-factor status.
# database.yml
storage-type: mysql
account-identifier: username
host: localhost
port: 3306
name: wordpress
username: wp_user
password: supersecret
jdbc-parameters: useSSL=false&characterEncoding=UTF-8
integration:
mode: wordpress
wordpress:
table-prefix: wp_
users-table: wp_users
user-meta-table: wp_usermeta
username-column: user_login
email-column: user_email
password-column: user_pass
uuid-meta-key: minecraft_uuid
two-factor-secret-meta-key: ezauth_2fa_secret
two-factor-confirmed-meta-key: ezauth_2fa_confirmed
# hashing.yml
algorithm: wordpress
# security.yml
authentication-type: login
two-factor:
optional: true
locale:
default-language: en_US
Default Configuration
database.yml now includes an integration section so you can reuse Laravel, WordPress, or XenForo tables while keeping EzAuth's familiar commands. Update the table and column names to match your deployment or leave the mode on none to keep EzAuth's managed schema.
# EzAuth Storage Configuration
storage-type: yml
account-identifier: uuid
yaml-file: registrations.yml
host: localhost
port: 3306
name: ezauth
username: root
password: password
jdbc-parameters: useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
pool:
maximum-pool-size: 10
minimum-idle: 2
connection-timeout: 30000
idle-timeout: 600000
max-lifetime: 1800000
data-source-properties:
cachePrepStmts: "true"
prepStmtCacheSize: "250"
prepStmtCacheSqlLimit: "2048"
integration:
mode: none
laravel:
table: users
uuid-column: uuid
username-column: name
email-column: email
password-column: password
two-factor-secret-column: two_factor_secret
two-factor-confirmed-column: two_factor_confirmed
created-at-column: created_at
updated-at-column: updated_at
remember-token-column: remember_token
wordpress:
table-prefix: wp_
users-table: wp_users
user-meta-table: wp_usermeta
username-column: user_login
email-column: user_email
password-column: user_pass
created-at-column: user_registered
uuid-meta-key: minecraft_uuid
two-factor-secret-meta-key: ezauth_two_factor_secret
two-factor-confirmed-meta-key: ezauth_two_factor_confirmed
xenforo:
table-prefix: xf_
user-table: xf_user
user-auth-table: xf_user_authenticate
user-field-value-table: xf_user_field_value
user-profile-table: xf_user_profile
username-column: username
email-column: email
created-at-column: register_date
uuid-field-id: minecraft_uuid
two-factor-secret-field-id: ezauth_two_factor_secret
two-factor-confirmed-field-id: ezauth_two_factor_confirmed
WordPress setups need a few extra tweaks before going live:
- Switch
hashing.yml's algorithm to WORDPRESS_PHPASS so EzAuth produces hashes compatible with WordPress' PHPass implementation.
- Keep the UUID and two-factor meta keys (
minecraft_uuid, ezauth_two_factor_secret, ezauth_two_factor_confirmed by default) or adjust them to match your existing data.
- Update the table prefix or table names if your WordPress instance uses a custom prefix.
XenForo deployments should create three custom text user fields in the XenForo control panel matching the configured uuid-field-id, two-factor-secret-field-id, and two-factor-confirmed-field-id. EzAuth keeps the values in xf_user_field_value, xf_user_profile.custom_fields, and xf_user_authenticate aligned whenever it updates an account.
Laravel schemas should expose UUID and two-factor columns alongside the framework defaults (remember_token, created_at, updated_at). If you use Jetstream or Breeze, add the following migration so EzAuth can reuse your user table without data loss:
// Laravel migration
Schema::table('users', function (Blueprint $table) {
$table->uuid('uuid')->unique()->after('id');
$table->text('two_factor_secret')->nullable()->after('password');
$table->boolean('two_factor_confirmed')->default(false)->after('two_factor_secret');
});
EzAuth keeps the two-factor values intact when it updates an existing Laravel user and will fill in timestamps and the remember token for fresh rows.
Hashing defaults
# hashing.yml
algorithm: BCRYPT
bcrypt:
rounds: 10
sha256:
pepper: ""
Security defaults
# security.yml
require-email-validation: true
min-password-length: 8
session-timeout-seconds: 300
login-enabled: true
register-enabled: true
bypass-enabled: true
login:
cooldown:
enabled: true
stages:
- attempts: 3
cooldown-seconds: 10
- attempts: 5
cooldown-seconds: 60
two-factor:
enabled: false
issuer: EzAuth
required-for-login: false
secure-account-welcome-message:
- "%prefix%&aTwo-factor authentication is now enabled for your account, %player%!"
allowed-commands-while-unauthenticated:
- login
- register
- 2fa
- twofactor
visual-effects:
enabled: true
login:
enabled: true
particle: VILLAGER_HAPPY
particle-count: 30
particle-offset-x: 0.0
particle-offset-y: 1.0
particle-offset-z: 0.0
particle-spread-x: 0.25
particle-spread-y: 0.35
particle-spread-z: 0.25
sound: ENTITY_PLAYER_LEVELUP
sound-volume: 1.0
sound-pitch: 1.2
register:
enabled: true
particle: FIREWORKS_SPARK
particle-count: 50
particle-offset-x: 0.0
particle-offset-y: 1.0
particle-offset-z: 0.0
particle-spread-x: 0.4
particle-spread-y: 0.6
particle-spread-z: 0.4
sound: UI_TOAST_CHALLENGE_COMPLETE
sound-volume: 1.0
sound-pitch: 1.0
Security (2FA-only mode)
# EzAuth Security Configuration (2FA-only mode)
require-email-validation: false
min-password-length: 8
session-timeout-seconds: 0
login-enabled: false
register-enabled: false
bypass-enabled: false
login:
cooldown:
enabled: false
stages: []
two-factor:
enabled: true
issuer: EzAuth
required-for-login: false
secure-account-welcome-message:
- "%prefix%&aTwo-factor authentication is now enabled for your account, %player%!"
allowed-commands-while-unauthenticated:
- 2fa
- twofactor
visual-effects:
enabled: false
messages.yml (example)
# messages.yml
default-language: en
languages:
en:
name: 'English'
file: 'messages/en.yml'
aliases:
- 'en_us'
- 'en-gb'
nl:
name: 'Nederlands'
file: 'messages/nl.yml'
aliases:
- 'nl_nl'
- 'nl-be'
es:
name: 'Español'
file: 'messages/es.yml'
aliases:
- 'es_es'
- 'es-mx'
prefix: '&7[&bEzAuth&7] '
register:
usage: '%prefix%&cUsage: /register <email> <password> <password>'
success: '%prefix%&aYou are now registered with &f%email%&a. Welcome!'
already-registered: '%prefix%&cYou are already registered. Use /login <password> to authenticate.'
email-in-use: '%prefix%&cThat email address is already associated with another account.'
invalid-email: '%prefix%&cPlease enter a valid email address.'
password-mismatch: '%prefix%&cYour passwords do not match.'
password-too-short: '%prefix%&cPasswords must be at least &f%length%&c characters long.'
prompt: '%prefix%&eCreate an account with &f/register <email> <password> <password>'
disabled: '%prefix%&cRegistration is currently disabled. Please contact an administrator to create an account.'
login:
usage: '%prefix%&cUsage: /login <password>'
success: '%prefix%&aYou are now logged in.'
success-with-email: '%prefix%&aYou are now logged in with &f%email%&a.'
not-registered: '%prefix%&cNo account found. Use /register <email> <password> <password>.'
invalid-password: '%prefix%&cIncorrect password. Please try again.'
already-logged-in: '%prefix%&cYou are already logged in.'
cooldown-active: '%prefix%&cToo many failed attempts. Please wait &f%seconds%&c seconds before trying again.'
prompt: '%prefix%&eWelcome back! Log in with &f/login <password>'
bypass: '%prefix%&aBypass enabled: you are already authenticated.'
disabled: '%prefix%&ePassword login is currently disabled on this server.'
general:
no-permission: '%prefix%&cYou do not have permission to use this command.'
players-only: '%prefix%&cOnly players can run this command.'
error: '%prefix%&cAn internal error occurred. Please contact an administrator.'
not-authenticated: '%prefix%&cPlease authenticate using %methods%.'
already-authenticated: '%prefix%&cYou are already authenticated.'
admin:
reload:
usage: '%prefix%&eUsage: /ezauth reload'
success: '%prefix%&aEzAuth configuration reloaded successfully.'
failed: '%prefix%&cFailed to reload EzAuth configuration. Check console for details.'
twofactor:
disabled: '%prefix%&cTwo-factor authentication is not enabled on this server.'
usage: '%prefix%&eUsage: /2fa <setup|confirm|verify|disable|status>'
confirm-usage: '%prefix%&cUsage: /2fa confirm <code>'
verify-usage: '%prefix%&cUsage: /2fa verify <code>'
disable-usage: '%prefix%&cUsage: /2fa disable <code|player>'
setup: '%prefix%&aAdd this account to your authenticator app using the secret or setup URL below.'
secret-line: '%prefix%&7Secret: &b&n%secret% &8(Click to copy)'
secret-hover: '&bClick to copy your 2FA secret to the clipboard.'
uri-line: '%prefix%&7Setup URL: &f%uri%'
already-enabled: '%prefix%&cTwo-factor authentication is already enabled.'
setup-required: '%prefix%&cYou must set up two-factor authentication with &f/2fa setup&c before continuing.'
setup-optional: '%prefix%&eSecure your account any time with &f/2fa setup&e when you are ready.'
login-required: '%prefix%&cEnter a valid 2FA code using &f/2fa verify <code>&c to finish signing in.'
auth-required: '%prefix%&cPlease log in with &f/login&c before using /2fa commands.'
invalid-code: '%prefix%&cThat 2FA code is invalid or expired. Please try again.'
enabled: '%prefix%&aTwo-factor authentication has been enabled successfully.'
verified: '%prefix%&aTwo-factor authentication complete. You are now signed in.'
disabled-success: '%prefix%&aTwo-factor authentication has been disabled for your account.'
admin-disabled-success: '%prefix%&aTwo-factor authentication has been disabled for &f%target%&a.'
admin-disabled-notify: '%prefix%&cYour two-factor authentication has been disabled by &f%admin%&c.'
admin-self-target: '%prefix%&cTo disable your own two-factor authentication, run &f/2fa disable <code>&c.'
admin-target-not-found: '%prefix%&cNo EzAuth account found for &f%target%&c.'
admin-target-not-enabled: '%prefix%&cTwo-factor authentication is not enabled for &f%target%&c.'
not-setup: '%prefix%&cYou have not generated a two-factor secret yet. Use /2fa setup first.'
not-confirmed: '%prefix%&cYou must confirm your two-factor secret with /2fa confirm <code> before using it.'
not-enabled: '%prefix%&cTwo-factor authentication is not currently enabled for your account.'
no-account: '%prefix%&cNo EzAuth account found for your player. Please register first.'
status-enabled: '%prefix%&aTwo-factor authentication is enabled on your account.'
status-pending: '%prefix%&eTwo-factor authentication setup is pending confirmation.'
status-disabled: '%prefix%&eTwo-factor authentication is currently disabled for your account.'
Proxy-aware Session Storage
Need to keep players authenticated across a network of servers? Flip proxy.enabled: true inside security.yml and EzAuth will automatically switch to a shared SQL-backed session store. The plugin creates the required ezauth_sessions table, replicates login state between instances, and honours proxy.session-ttl-seconds so you can control how long a network-wide login remains valid before players must authenticate again. Set it to 0 to rely entirely on the per-server timeout defined by session-timeout-seconds.
This proxy support is still experimental, so test thoroughly before rolling it out across production networks.
Heads up: distributed sessions require the MySQL backend defined in database.yml. EzAuth will refuse to boot the proxy cache if you're running purely on YAML storage.
Preparing Email Notifications
EzAuth now ships with an optional email.yml that lets you preload SMTP details ahead of outbound messaging support. Leave the section disabled to skip configuration entirely, or enable it and provide your host, port, transport (TLS/SSL), credentials, and sender identity so EzAuth is ready the moment email verification or alerts go live.
smtp:
enabled: false
host: smtp.example.com
port: 587
username: no-reply@example.com
password: "changeme"
use-starttls: true
from-name: "EzAuth"
from-address: no-reply@example.com
- Keep
enabled set to false until you're ready to wire in valid credentials.
- Toggle
use-starttls or swap to implicit SSL by setting port to 465 if your provider requires it.
- Pair email notifications with the verification commands under
/email to block unverified accounts before they log in.
Connecting EzAuth to Your Website Login
Whether you're running Laravel, WordPress, or XenForo, EzAuth can authenticate players against the same credentials your website already uses. Follow the steps below for your platform after setting storage-type: mysql.
Laravel Integration
- Open
plugins/EzAuth/database.yml and set integration.mode to laravel.
- Point the MySQL connection settings at the database your Laravel site uses (usually the values from
.env).
- Ensure the column names in the
integration.laravel block match your users table. If you use UUIDs, keep uuid-column; otherwise set account-identifier to username.
- If you rely on Laravel's remember tokens or two-factor columns, keep them mapped—EzAuth reads and updates them automatically when players log in or toggle
/2fa.
- Reload EzAuth or restart the server. New registrations will write back through Laravel's hashing (BCrypt) so the same password works on both the site and Minecraft server.
WordPress Integration
- Set
storage-type to mysql and integration.mode to wordpress.
- Use the database credentials from
wp-config.php so EzAuth connects to the same MySQL instance as WordPress.
- Adjust
integration.wordpress.table-prefix if your installation uses a custom prefix, then confirm the users and usermeta table names.
- Map EzAuth's UUID and 2FA fields to meta keys that exist (or let EzAuth create them). Passwords are checked using WordPress' PHPass algorithm when you enable
hashing.algorithm: wordpress in hashing.yml.
- Reload EzAuth. Players can now
/login with their WordPress credentials, and optional /2fa status will sync to the user meta rows.
XenForo Integration
- Switch
integration.mode to xenforo and supply the same MySQL details XenForo uses.
- Confirm the table prefix and column names in the
integration.xenforo block. EzAuth will read usernames from xf_user and hashed passwords from xf_user_authenticate.
- If you store Minecraft UUIDs or 2FA secrets in custom profile fields, update the
uuid-field-id and two-factor-* identifiers so EzAuth syncs the correct values.
- Make sure
hashing.yml is set to algorithm: xenforo so EzAuth verifies XenForo's bcrypt variants correctly.
- Reload EzAuth or restart to apply changes. Server logins will now validate against XenForo accounts, keeping forum and in-game credentials unified.
Getting Started
- Drop the jar into your
/plugins folder and start the server once to generate configs.
- Edit
database.yml, hashing.yml, and security.yml to match your storage, hashing, and policy.
- Configure
email.yml if you plan to send email-based notifications later.
- Tune
messages.yml to fit your community tone, then run /ezauth reload in-game.
- Invite players to
/register, /login, and optionally /2fa setup for full protection.
Need Help?
EzAuth is in active development, so your feedback directly shapes the roadmap. You can join our Discord server for real-time support, feature requests and updates.

评论 0
登录后参与评分
还没有评论,来抢沙发吧