?
Host a serverModrinth App
Sign in
ModsResource PacksData PacksShadersModpacksPluginsServers
Settings
BedrockPassport

BedrockPassport

Let Bedrock players choose and save real Java-side server identities before joining through Geyser and Floodgate.

94downloads
0followers
94downloads
0followers

Compatibility

Minecraft: Java Edition

26.3
26.2

Platforms

Links

Report issues View source

Tags

Creators

Details

Published 2 weeks ago
Updated last week

BedrockPassport-Banner

๐Ÿชช 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:

BedrockPassport-Passport

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.

JAVA_ACCOUNT

JAVA_ACCOUNT entries are created only after Microsoft/Minecraft authentication succeeds.

Saved Java authentication chains are encrypted with AES-GCM.

plugins/BedrockPassport/passport.db
plugins/BedrockPassport/credentials.key

Back up both files together and treat them as sensitive server data.

A new device-code login is only needed when saved authentication can no longer be refreshed or re-authentication is required.

๐Ÿ›ก๏ธ 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.

๐Ÿง  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.

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, 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.

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: v4.

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:

plugins/BedrockPassport/credentials.key

๐Ÿ“ฆ Installation

  1. Install Geyser-Spigot.
  2. For LOCAL, install Floodgate and use online-mode=false.
  3. For JAVA_ACCOUNT, use online-mode=true; Floodgate may remain installed.
  4. Put BedrockPassport in plugins/.
  5. 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.