
? BedrockPassport
为 Bedrock 玩家提供持久化的 Java 端身份标识 —— 在接入后端之前。
BedrockPassport 是 Geyser 服务器的预登录身份网关。一个 Bedrock/Xbox 账号可以拥有多个身份,并在后端登录开始前选择使用哪个 Java 端身份。
online-mode=false → LOCAL
online-mode=true → JAVA_ACCOUNT
- LOCAL — 已保存的服务端用户名、确定性的离线 UUID 以及 Floodgate 身份交接。
- JAVA_ACCOUNT — 经过验证的 Microsoft/Minecraft Java 账号及其真实的 Java 用户名和 UUID。
这不是一个昵称插件。
BedrockPassport 在后端创建玩家之前就改变了后端身份。
? 实时演示服务器
想在安装 BedrockPassport 之前看看 LOCAL 流程吗?
地址: 194.164.217.187
端口: 10007
演示服务器特意使用了 online-mode=false,以便直接测试 LOCAL 身份流程,而无需要求 Java 账号。
通过 JAVA_ACCOUNT 提供程序,BedrockPassport 也支持在 online-mode=true 服务器上使用的经验证的 Java 账号。
⚡ 概览
|
|
| ? 身份 |
后端登录前选定的 Java 端用户名 + UUID |
| ? UI |
原生 Bedrock 表单 |
| ? 账号 |
每个 Xbox 账号可拥有多个身份 |
| ? 在线模式 |
经验证的真实 Java 账号 |
| ? 离线模式 |
通过 Floodgate 的 LOCAL 身份 |
| ? Bedrock 访问 |
按游戏名或 XUID 的可选白名单 |
| ? 语言 |
每位玩家的 en_US、ru_RU、uk_UA、de_DE、es_ES |
| ? 保存的 Java 认证 |
AES-GCM 加密 |
| ? 存储 |
SQLite |
✨ 工作原理
LOCAL
Bedrock / Xbox 账号
↓
Geyser 持有环境
↓
选择服务端身份
↓
Java 用户名 + 离线 UUID
↓
Floodgate 身份交接
↓
认证插件
↓
游戏进行
JAVA_ACCOUNT
Bedrock / Xbox 账号
↓
选择或添加 Java 账号
↓
Microsoft / Minecraft 认证
↓
经验证的 Java 用户名 + 真实 UUID
↓
在线模式后端登录
↓
游戏进行
回归玩家将获得原生的 Bedrock 选择器:

每个 Xbox 账号可以在加入 Java 后端之前保留多个已保存的身份,在它们之间切换,添加新身份并移除旧条目。
默认账号限制:
identity:
max-accounts-per-xuid: 3
从 BedrockPassport 中移除条目 不会 删除 Java/Microsoft 账号或服务端玩家数据。
? 真实后端身份
所选账号不是显示名称、TAB 栏昵称、前缀或外观别名。
由于身份是在后端玩家创建之前解析的,绑定 UUID 的数据从会话开始就属于所选身份:
- 玩家数据
- 物品栏
- 权限
- 统计信息
- 领地声明
- 白名单条目
- 其他绑定 UUID 的插件数据
LOCAL
所选用户名将接收与普通离线模式 Java 客户端相同的确定性离线 UUID。
因此,使用相同用户名的 Java 客户端和 Bedrock 客户端可以代表同一个服务端身份。
LOCAL 身份仍然只是一个身份快捷方式 —— 并非所有权的证明。
JAVA_ACCOUNT
BedrockPassport 通过 Microsoft/Minecraft 认证验证真实的 Java 账号,并使用其真实的:
- Java 用户名
- Java UUID
- 已认证的 Java 会话
JAVA_ACCOUNT 不会生成离线 UUID。
? Bedrock/Xbox 白名单
BedrockPassport 可以将 Passport 流程限制为选定的 真实 Bedrock/Xbox 身份。
access:
allowlist:
enabled: false
players: []
xuids: []
启用后,如果连接的游戏名匹配 players 或其 XUID 匹配 xuids,则允许该连接。
此检查发生在 Passport 选择器和后端玩家创建之前,因此选择另一个已保存的 Java 身份无法绕过它。
- Java 客户端不受影响。
- 游戏名匹配不区分大小写。
- XUID 可用作稳定标识符。
- 启用白名单且两个列表均为空时,将拒绝所有 Bedrock 连接。
? 本地化
BedrockPassport 可以自动使用每位 Bedrock 玩家的客户端语言来面向玩家展示 Passport 流程。
language:
config: en_US
messages: en_US
use-player-locale: true
player-locale-fallback: en_US
面向玩家的语言环境:
en_US — English
ru_RU — Русский
uk_UA — Українська
de_DE — Deutsch
es_ES — Español
当 use-player-locale: true 时,BedrockPassport 会独立检测每个 Bedrock 连接的语言。因此,使用不同客户端语言的两位玩家可以同时收到不同的 Passport 表单。
区域变体按语言族进行匹配,例如:
en_GB → en_US
ru_KZ → ru_RU
es_MX → es_ES
如果客户端语言不受支持,则使用 player-locale-fallback。
当 use-player-locale: false 时,面向玩家的文本如常工作,并使用 language.messages。
language.messages 仍然是管理员和操作消息的默认语言。
language.config 控制写入 config.yml 中的解释性注释,目前支持 en_US 和 ru_RU。
仍可通过 messages.overrides 自定义单个消息。
? 认证与信任
LOCAL
BedrockPassport 选择 使用哪个服务端身份。它并不证明对该 LOCAL 身份的所有权。
单独的认证插件随后可以进行密码/注册验证。
在常规的 Bukkit 身份验证插件做出登录决定之前,Passport 身份信息以**不受信任(untrusted)**状态暴露,而真实的 Xbox 用户名、XUID 和 Bedrock 上下文信息仍然可用。
AuthMeReloaded 作为一个独立的本地身份验证层运行,无需特定的 BedrockPassport 适配器。
本地用户名在生成离线 UUID 之前会进行规范化处理:如果 AuthMe 已经拥有该账户,则使用其注册的大小写形式,因此 Steve 和 steve 永远不会变成两个不同的 UUID。
JAVA_ACCOUNT
JAVA_ACCOUNT 条目仅在 Microsoft/Minecraft 身份验证成功后创建。
保存的 Java 身份验证链在 passport.db 中使用 AES-GCM 进行加密。
每个账户一个设备代码,实现无缝登录。 Microsoft 刷新令牌会在后续加入时自动续期,并在后端连接建立前将轮换后的令牌写回数据库。
仅当 Microsoft 真正拒绝保存的登录信息时才会请求新的设备代码:例如刷新令牌过期或已撤销、密码更改、授权被撤销,或者该账户不再拥有 Minecraft。网络错误、超时以及 Microsoft/Xbox 的服务中断绝不会清除保存的登录信息。BedrockPassport 会进行重试,如果 Microsoft 仍然不可用,则会将玩家返回到选择器界面并显示一条消息。
Microsoft 刷新令牌在未使用的情况下大约会在 90 天后过期,因此超过这个时间未加入的账户需要再进行一次设备代码验证。
? 加密密钥位置
密钥按以下顺序查找:
BEDROCKPASSPORT_KEY 环境变量(base64 编码,32 字节)
config.yml 中的 security.credentials-key-path
plugins/BedrockPassport/credentials.key(自动生成)
openssl rand -base64 32
插件永远不会生成、覆盖或轮换外部密钥。如果密钥缺失或无效,JAVA_ACCOUNT 会因安全原因失败,并在控制台输出清晰的错误信息,而不是创建一个会导致保存的登录信息无法读取的新密钥。/bp status 命令会显示密钥来源,但不会泄露密钥本身。
备份: 使用外部密钥时,请分别备份 passport.db 和密钥文件。泄露的数据库如果没有密钥是无法解密的。
?️ 会话保护与断开连接清理
启用 security.first-session-wins: true 后,已经拥有或预留了 LOCAL 身份的连接将保留该身份。
BedrockPassport 可防止常见的登录竞争问题:
- Bedrock 无法夺取已在线的身份
- Java 无法使用相同身份替换活跃的 Bedrock Passport 会话
- 两个 Bedrock 连接不能预留相同的 LOCAL 身份
- 同一个 XUID 不能同时打开两个 LOCAL Passport 流程
如果 Bedrock 客户端在未完成 Passport 流程期间断开连接,临时选择器、预留状态和交接状态将通过 Geyser 会话生命周期进行清理。
? 皮肤处理
皮肤处理属于 LOCAL / Floodgate 路径。
skins:
policy: preserve
| 策略 |
行为 |
preserve |
保留有意义的现有皮肤;否则允许正常的 Floodgate/SkinsRestorer 结果 |
refresh |
允许最终的 Floodgate/SkinsRestorer 皮肤替换当前皮肤 |
off |
禁用 BedrockPassport 的皮肤处理功能 |
SkinsRestorer 是可选的。当可用时,BedrockPassport 可以在选定的 LOCAL 身份达到 Bukkit 加入条件后重新应用存储的皮肤。
确认 Bedrock 皮肤后,最多等待约两分钟,因为 Geyser 的全局皮肤服务可能需要一段时间来处理自定义皮肤的签名。
? Bedrock 检测、Floodgate 和反作弊
更改 Java 端的身份不会使 Bedrock 连接变成 Java 客户端。
在 LOCAL 模式下,Floodgate 参与后端交接,且正常的 Bedrock 上下文仍然可用。选择器在 Geyser 的暂存环境中运行,在后端连接打开之前,因此玩家选择账户永远不会阻塞其他玩家的连接。
在 JAVA_ACCOUNT 模式下,后端登录是一个真正的已认证 Java 配置文件。Floodgate 可能仍然安装,但其后端登录处理程序会被排除在经过验证的 Java 账户交接过程之外。
支持 Bedrock 的集成应使用受支持的 Geyser/Floodgate API,而不是仅依赖用户名前缀或猜测的 UUID 格式。
? AuthMeReloaded 和 AlixSystem
AuthMeReloaded
作为 LOCAL 的独立身份验证层非常有用。
BedrockPassport 首先执行身份交接;然后 AuthMe 执行其正常的密码/注册验证。
AlixSystem
BedrockPassport 在 LOCAL 身份交接中排在 AlixSystem 之前。
Alix 的兼容性仍取决于安装的 Alix 版本是否与安装的 Geyser 版本兼容。
? 管理命令
权限:bedrockpassport.admin — 默认由 OP(管理员)拥有。
/bp status
/bp who <javaName>
/bp reload
/bp reset-login <javaName>
/bp reset-login --all confirm
/bp status — 运行时信息、提供程序、凭据密钥来源、白名单、语言和会话信息。
/bp who <javaName> — 检查活动或待处理的身份。
/bp reload — 迁移/重载配置并重建运行时环境。
/bp reset-login <javaName> — 移除单个保存的 JAVA_ACCOUNT 的可重用身份验证状态。
/bp reset-login --all confirm — 移除所有保存的 Java 身份验证状态并轮换 credentials.key(外部密钥留给管理员处理)。
重置命令会保留 Passport 身份记录和经过验证的 Java UUID。
? 配置与存储
BedrockPassport 使用版本化的配置迁移和 SQLite 模式迁移。
当前配置方案:v5。
自动迁移旧版受支持的配置,包括将受支持的用户界面文本本地化至 messages.overrides。
当 BedrockPassport 引入新的配置选项时,缺失的设置会被添加到现有的 config.yml 中,同时保留管理员自定义的值。配置文件注释会根据所选的 language.config 区域设置重新生成。
在更新过程中,通常无需删除或重建 config.yml 或 passport.db。
护照数据:
plugins/BedrockPassport/passport.db
JAVA_ACCOUNT 加密密钥(默认位置,环境变量或自定义路径请参阅上方的 Encryption key location):
plugins/BedrockPassport/credentials.key
? 安装
- 安装 Geyser-Spigot。
- 对于
LOCAL 模式,安装 Floodgate 并设置 online-mode=false。
- 对于
JAVA_ACCOUNT 模式,使用 online-mode=true;Floodgate 可保持安装状态。
- 将 BedrockPassport 放入
plugins/ 目录。
- 启动服务器。
BedrockPassport 会在启动时检查所需的 Geyser 集成能力,如果缺少必需的后端集成点,则会阻止启动。
? 兼容性
| 软件 |
支持情况 |
| Paper |
✅ |
| Folia |
✅ |
| Purpur |
✅ |
| Leaf |
✅ |
| Geyser-Spigot |
✅ 必需 |
| Floodgate |
✅ LOCAL / ? JAVA_ACCOUNT 下可选 |
| SkinsRestorer |
? 可选 |
| AuthMeReloaded |
✅ LOCAL 认证层 |
| AlixSystem |
? 需要兼容 Geyser 的版本 |
需要 Java 25 或更高版本。
BedrockPassport 不依赖 Minecraft NMS。
与 BedrockPassport 配合使用的其他插件必须自行提供对 Folia 的兼容性。
? 为什么选择 BedrockPassport?
Geyser 使基岩版客户端能够兼容 Java 版服务器。
BedrockPassport 在后端玩家实体存在之前,补充了缺失的身份选择机制。
- 没有虚假显示名称。
- 不会强制使用 Xbox 游戏昵称作为服务器账号。
- 不会因为有人切换游戏版本就产生重复的玩家数据。
- LOCAL 身份验证与所有权验证相互独立。
- 开启在线模式的服务器可以使用真实且经过验证的 Java 版账号。
为 Geyser 服务器提供清晰的前后端身份交接流程。

? BedrockPassport
Persistent Java-side identities for Bedrock players — before they ever enter the backend.
BedrockPassport is a pre-login identity gateway for Geyser servers. A Bedrock/Xbox account can keep multiple identities and choose which Java-side identity to use before backend login begins.
online-mode=false → LOCAL
online-mode=true → JAVA_ACCOUNT
- LOCAL — saved server usernames, deterministic offline UUIDs and Floodgate identity handoff.
- JAVA_ACCOUNT — verified Microsoft/Minecraft Java accounts with their real Java username and UUID.
Not a nickname plugin.
BedrockPassport changes the backend identity before the backend creates the player.
? Live demo server
Want to see the LOCAL flow before installing BedrockPassport?
Address: 194.164.217.187
Port: 10007
The demo server intentionally uses online-mode=false so the LOCAL identity flow can be tested directly without requiring a Java account.
BedrockPassport also supports verified Java accounts on online-mode=true servers through the JAVA_ACCOUNT provider.
⚡ At a glance
|
|
| ? Identity |
Java-side username + UUID selected before backend login |
| ? UI |
Native Bedrock forms |
| ? Accounts |
Multiple identities per Xbox account |
| ? Online mode |
Verified real Java accounts |
| ? Offline mode |
LOCAL identities through Floodgate |
| ? Bedrock access |
Optional allowlist by gamertag or XUID |
| ? Languages |
Per-player en_US, ru_RU, uk_UA, de_DE, es_ES |
| ? Saved Java auth |
AES-GCM encrypted |
| ? Storage |
SQLite |
✨ How it works
LOCAL
Bedrock / Xbox account
↓
Geyser holding environment
↓
Choose a server identity
↓
Java username + offline UUID
↓
Floodgate identity handoff
↓
Authentication plugin
↓
Gameplay
JAVA_ACCOUNT
Bedrock / Xbox account
↓
Choose or add a Java account
↓
Microsoft / Minecraft authentication
↓
Verified Java username + real UUID
↓
Online-mode backend login
↓
Gameplay
Returning players get a native Bedrock selector:

Each Xbox account can keep several saved identities, switch between them, add new ones and remove old entries before joining the Java backend.
Default account limit:
identity:
max-accounts-per-xuid: 3
Removing an entry from BedrockPassport does not delete Java/Microsoft accounts or server playerdata.
? Real backend identities
The selected account is not a display name, TAB nickname, prefix or cosmetic alias.
Because the identity is resolved before backend player creation, UUID-bound data belongs to the selected identity from the beginning of the session:
- player data
- inventory
- permissions
- statistics
- claims
- whitelist entries
- other UUID-bound plugin data
LOCAL
The selected username receives the same deterministic offline UUID that a normal offline-mode Java client would receive.
A Java and Bedrock client using the same username can therefore represent the same server identity.
A LOCAL identity is still only an identity shortcut — not proof of ownership.
JAVA_ACCOUNT
BedrockPassport verifies a real Java account through Microsoft/Minecraft authentication and uses its real:
- Java username
- Java UUID
- authenticated Java session
No offline UUID is generated for JAVA_ACCOUNT.
? Bedrock/Xbox allowlist
BedrockPassport can restrict the Passport flow to selected real Bedrock/Xbox identities.
access:
allowlist:
enabled: false
players: []
xuids: []
When enabled, a connection is allowed if either its Xbox/Bedrock gamertag matches players or its XUID matches xuids.
The check happens before the Passport selector and before backend player creation, so selecting another saved Java identity cannot bypass it.
- Java clients are unaffected.
- Gamertag matching is case-insensitive.
- XUIDs can be used as stable identifiers.
- Enabling the allowlist with both lists empty denies all Bedrock connections.
? Localization
BedrockPassport can automatically use each Bedrock player's client language for the player-facing Passport flow.
language:
config: en_US
messages: en_US
use-player-locale: true
player-locale-fallback: en_US
Player-facing locales:
en_US — English
ru_RU — Русский
uk_UA — Українська
de_DE — Deutsch
es_ES — Español
With use-player-locale: true, BedrockPassport detects the language of each Bedrock connection independently. Two players using different client languages can therefore receive different Passport forms at the same time.
Regional variants are matched by language family, for example:
en_GB → en_US
ru_KZ → ru_RU
es_MX → es_ES
If the client language is not supported, player-locale-fallback is used.
With use-player-locale: false, player-facing text works as before and uses language.messages.
language.messages remains the default language for administrator and operational messages.
language.config controls explanatory comments written into config.yml and currently supports en_US and ru_RU.
Individual messages can still be customized through messages.overrides.
? Authentication and trust
LOCAL
BedrockPassport selects which server identity to use. It does not prove ownership of that LOCAL identity.
A separate authentication plugin can perform password/register verification afterwards.
Before normal Bukkit authentication plugins make their login decision, the Passport identity is exposed as untrusted, while the real Xbox username, XUID and Bedrock context remain available.
AuthMeReloaded works as a separate LOCAL authentication layer without a BedrockPassport-specific adapter.
LOCAL usernames are canonicalized before the offline UUID is generated: when AuthMe already has the account, its registered letter-case is used, so Steve and steve can never become two different UUIDs.
JAVA_ACCOUNT
JAVA_ACCOUNT entries are created only after Microsoft/Minecraft authentication succeeds.
Saved Java authentication chains are encrypted with AES-GCM in passport.db.
One device code per account, then seamless sign-in. The Microsoft refresh token is renewed automatically on later joins and the rotated token is written back to the database before the backend connection.
A new device code is requested only when Microsoft really rejects the saved sign-in: expired or revoked refresh token, password change, revoked consent, or the account no longer owns Minecraft. Network errors, timeouts and Microsoft/Xbox outages never wipe the saved sign-in. BedrockPassport retries and, if Microsoft is still unavailable, returns the player to the selector with a message.
A Microsoft refresh token expires after roughly 90 days without use, so an account that has not joined for that long needs one more device code.
? Encryption key location
The key is looked up in this order:
BEDROCKPASSPORT_KEY environment variable (base64, 32 bytes)
security.credentials-key-path in config.yml
plugins/BedrockPassport/credentials.key (generated automatically)
openssl rand -base64 32
An external key is never generated, overwritten or rotated by the plugin. If it is missing or invalid, JAVA_ACCOUNT fails closed with a clear console error instead of creating a new key that would make saved sign-ins unreadable. /bp status shows the key source without revealing the key.
Backups: with an external key, back up passport.db and the key separately. A leaked database without the key cannot be decrypted.
?️ Session protection and disconnect cleanup
With security.first-session-wins: true, the connection that already owns or has reserved a LOCAL identity keeps it.
BedrockPassport prevents common login races:
- Bedrock cannot take an identity that is already online
- Java cannot replace an active Bedrock Passport session using the same identity
- two Bedrock connections cannot reserve the same LOCAL identity
- the same XUID cannot open two simultaneous LOCAL Passport flows
If the Bedrock client disconnects during an unfinished Passport flow, temporary selector, reservation and handoff state is cleaned through the Geyser session lifecycle.
? Skin handling
Skin handling belongs to the LOCAL / Floodgate path.
skins:
policy: preserve
| Policy |
Behaviour |
preserve |
Keep a meaningful existing skin; otherwise allow the normal Floodgate/SkinsRestorer result |
refresh |
Allow the final Floodgate/SkinsRestorer skin to replace the current one |
off |
Disable BedrockPassport skin handling |
SkinsRestorer is optional. When available, BedrockPassport can re-apply a stored skin after the selected LOCAL identity reaches Bukkit join.
The confirmed Bedrock skin is awaited for up to about two minutes after join, because Geyser's global skin service can take a while to sign custom skins.
? Bedrock detection, Floodgate and anti-cheats
Changing the Java-side identity does not turn a Bedrock connection into a Java client.
In LOCAL, Floodgate participates in the backend handoff and normal Bedrock context remains available. The selector runs in Geyser's holding environment before the backend connection opens, so a player choosing an account never blocks connections of other players.
In JAVA_ACCOUNT, the backend login is a real authenticated Java profile. Floodgate may remain installed, but its backend login handler is kept out of the verified Java-account handoff.
Bedrock-aware integrations should use supported Geyser/Floodgate APIs instead of relying only on username prefixes or guessed UUID formats.
? AuthMeReloaded and AlixSystem
AuthMeReloaded
Useful as a separate authentication layer for LOCAL.
BedrockPassport performs the identity handoff first; AuthMe then performs its normal password/register verification.
AlixSystem
BedrockPassport is ordered before AlixSystem for the LOCAL identity handoff.
Alix compatibility still depends on the installed Alix build being compatible with the installed Geyser version.
? Administration commands
Permission: bedrockpassport.admin — OP by default.
/bp status
/bp who <javaName>
/bp reload
/bp reset-login <javaName>
/bp reset-login --all confirm
/bp status — runtime, provider, credential key source, allowlist, language and session information.
/bp who <javaName> — inspect an active or pending identity.
/bp reload — migrate/reload configuration and rebuild the runtime.
/bp reset-login <javaName> — remove reusable auth state for one saved JAVA_ACCOUNT.
/bp reset-login --all confirm — remove all saved Java auth state and rotate credentials.key (an external key is left to the administrator).
Reset commands keep Passport identity records and verified Java UUIDs.
? Configuration and storage
BedrockPassport uses versioned configuration migration and SQLite schema migration.
Current configuration schema: v5.
Older supported configurations are migrated automatically, including supported custom UI text into localized messages.overrides.
When BedrockPassport introduces new configuration options, missing settings are added to the existing config.yml while administrator-defined values are preserved. Configuration comments are regenerated using the selected language.config locale.
You should not normally need to delete or recreate config.yml or passport.db when updating.
Passport data:
plugins/BedrockPassport/passport.db
JAVA_ACCOUNT encryption key (default location, see Encryption key location above for env / custom path):
plugins/BedrockPassport/credentials.key
? Installation
- Install Geyser-Spigot.
- For
LOCAL, install Floodgate and use online-mode=false.
- For
JAVA_ACCOUNT, use online-mode=true; Floodgate may remain installed.
- Put BedrockPassport in
plugins/.
- Start the server.
BedrockPassport performs a startup capability check for the Geyser integration it needs and fails closed if a required pre-backend integration point is unavailable.
? Compatibility
| Software |
Support |
| Paper |
✅ |
| Folia |
✅ |
| Purpur |
✅ |
| Leaf |
✅ |
| Geyser-Spigot |
✅ Required |
| Floodgate |
✅ LOCAL / ? optional in JAVA_ACCOUNT |
| SkinsRestorer |
? Optional |
| AuthMeReloaded |
✅ LOCAL authentication layer |
| AlixSystem |
? Requires a Geyser-compatible build |
Java 25 or newer is required.
BedrockPassport does not depend on Minecraft NMS.
Other plugins used alongside BedrockPassport must provide their own Folia compatibility.
? Why BedrockPassport?
Geyser makes Bedrock clients compatible with Java servers.
BedrockPassport adds the missing identity choice before the backend player exists.
- No fake display names.
- No forced Xbox gamertag as the server account.
- No duplicate playerdata just because somebody switched editions.
- LOCAL identities stay separate from ownership verification.
- Online-mode servers can use real verified Java accounts.
A clean pre-backend identity handoff for Geyser servers.
评论 0
登录后参与评分
还没有评论,来抢沙发吧