IdentityBridge

# IdentityBridge IdentityBridge is a small admin utility plugin for Paper servers that normally run in online mode, but sometimes need to be switched to offline mode temporarily because Mojang/Microsoft authentication is unavailable or the server cannot reach it. The common emergency workaround for a login outage is to stop the server, set `online-mode=false`, and restart so players can keep playing. The problem is that offline mode gives Java players a different, name-derived UUID. Since Minecraft stores inventory, position, stats, advancements, and many plugin files by UUID, players can appear to have lost their progress. IdentityBridge exists for that outage window. It learns real online UUIDs while your server is healthy, restores known players to those UUIDs while the server is temporarily offline, records new temporary offline identities, and helps migrate any offline-mode data back to the correct account once authentication is available again. **Important:** offline mode is unauthenticated. Anyone can connect using any username while `online-mode=false`. IdentityBridge cannot make offline mode secure; it can only preserve identity continuity and player data when you deliberately choose to run offline for a short period. Keep offline mode brief, use a whitelist or firewall when exposed, and consider the IP-match and unknown-player blocking options. IdentityBridge is not intended for permanently offline servers. ## When IdentityBridge Helps Use IdentityBridge when an online-mode server is temporarily cut off from Minecraft authentication: - Mojang/Microsoft login or session outages. - A home or LAN-hosted server where local players can still reach the server but the host has lost internet access. - Planned ISP maintenance or network work. - Rural, satellite, mobile, or otherwise unreliable internet connections. - Temporary LAN, classroom, venue, or off-grid setups where players should keep using their existing Java account data. In all of these cases the goal is the same: let people play during the outage without splitting their progress across online-mode and offline-mode UUIDs. ## What It Does - Learns authenticated Java player identities during normal online-mode play. - Restores known Java players to their real online UUID while the server is temporarily in offline mode. - Records unknown outage players under temporary offline identities so their data can be migrated later. - Can optionally block never-before-seen players during an outage. - Monitors Mojang/auth endpoint availability and advises admins when a manual mode switch may be needed. - Never edits `server.properties`, never changes online/offline mode, and never restarts the server. - Migrates UUID-keyed player data safely, with dry-runs, backups, conflict handling, and lossless stat/advancement merging. - Supports optional Bedrock/Floodgate bookkeeping without requiring Floodgate on Java-only servers. - Stores its own identity cache atomically to reduce the chance of corruption during shutdowns or crashes. - Admin commands tab-complete natively (subcommands, cache types, cached names/UUIDs, and flags), via Paper's Brigadier command framework. ## Requirements - **Server:** Paper or a Paper-compatible fork such as Purpur. - **Not supported:** stock Spigot/CraftBukkit, because IdentityBridge relies on Paper profile APIs. - **Not supported:** Folia, because the plugin uses the standard Bukkit scheduler and refuses to load there. - **Minecraft API floor:** built against Paper 1.20.6 with `api-version: '1.20.6'`. This is a compatibility floor, not a strict cap. Servers older than 1.20.6 will not load it. Test on your exact Paper build before depending on it in production. (Older 1.0.x releases supported a 1.20.1 floor; on Paper 1.20.1–1.20.5, use the 1.0.x line.) - **Java:** the plugin jar targets Java 21 bytecode, matching the runtime Paper 1.20.6+ requires. - **Floodgate:** optional. Java-only servers work normally without it. ## Installation 1. Download the IdentityBridge jar from this project page. 2. Put the jar in your server's `plugins/` folder. 3. Start the server in normal online mode first. 4. Let players join normally so IdentityBridge can learn their real online UUIDs. 5. Optionally review `plugins/IdentityBridge/config.yml`. IdentityBridge is most useful when it was installed before an outage. If you install it during an outage, it can still record temporary offline players, but it will not already know returning players' online UUIDs unless it can discover them from existing data or you add them manually. ## Basic Outage Workflow When authentication looks down and players cannot join: 1. Run `/idb check` or review the advisory from IdentityBridge. 2. If you decide offline mode is necessary, stop the server. 3. Set `online-mode=false` in `server.properties`. 4. Restart the server. 5. Known players should load their normal data because IdentityBridge restores their real online UUIDs. 6. New players are either recorded under temporary offline UUIDs or blocked, depending on your config. When authentication recovers: 1. Run `/idb check` or review the recovery advisory. 2. Stop the server. 3. Set `online-mode=true` in `server.properties`. 4. Restart the server. 5. Returning outage players are auto-migrated on rejoin by default. 6. Use `/idb cache list offline` and `/idb migrate ` for any pending manual migration work. IdentityBridge intentionally leaves the mode switch and restart in your hands. It only advises and preserves data. ## Commands Base command: `/identitybridge` Aliases: `/idbridge`, `/idb` All commands require `identitybridge.admin`. - `/idb help` - show available commands and migration flags. - `/idb status` - show server mode, monitoring state, cache counts, last auth check, and current advisory. - `/idb check` - probe configured auth endpoints and show per-endpoint status, HTTP code, and latency. - `/idb lookup ` - show known Java, offline, and Bedrock identity information, plus live Mojang lookup information when enabled. - `/idb cache list [] [page]` - list cached identities. - `/idb cache add java [onlineUuid] [--force]` - manually remember a Java player. - `/idb cache remove ` - remove one cached identity. - `/idb migrate [flags]` - migrate offline-mode data for a Java username to the correct online UUID. Dry-run by default. - `/idb migrate-uuid [flags]` - migrate data between explicit UUIDs. - `/idb reload` - save runtime identity data, then reload config and identity data. Common migration flags: - `--apply` - perform the migration. Without this flag, migration is only a preview. - `--overwrite` - force the source file to win an opaque file conflict after backup. - `--remove-source` - remove redundant opaque source files after migration where safe. - `--online-uuid ` - provide the target online UUID for `/idb migrate`. - `--offline-uuid ` - provide the source offline UUID. - `--offline-name ` - derive the source offline UUID from an exact offline name spelling. ## Data Migration Safety Migration is built to avoid silent data loss. By default, IdentityBridge migrates these UUID-keyed files relative to the main world folder: ```text playerdata/{uuid}.dat playerdata/{uuid}.dat_old stats/{uuid}.json advancements/{uuid}.json ``` You can extend the list in `config.yml` for other UUID-keyed files written by datapacks or plugins. Safety behavior: - Migrations are dry-run by default. - Backups are enabled by default and are written under `plugins/IdentityBridge/backups/`. - Missing source files are reported, not treated as fatal. - Empty or unreadable sources are refused instead of being treated as valid empty data. - Stats are summed when both UUIDs have data. - Advancements are unioned when both UUIDs have data. - Inventory and other opaque file conflicts are resolved in favor of the side with more play time, with advancement count as a tie-breaker. - Nothing is discarded without a backup. - Merged stats and advancements are folded into one target file so rerunning the migration will not double-count. Basic manual migration: ```text /idb migrate Steve /idb migrate Steve --apply /idb migrate Steve --apply --remove-source ``` Use `migrate-uuid` when you need an explicit UUID-to-UUID move: ```text /idb migrate-uuid --apply ``` ## Configuration Highlights The generated `plugins/IdentityBridge/config.yml` is fully commented. The most important options are: - `login-continuity.enabled` - restore known players' real online UUIDs while the server is offline. - `login-continuity.block-unknown-during-outage` - block players IdentityBridge has never seen while offline. - `login-continuity.require-ip-match` - only restore a known player from their last known IP. - `login-continuity.require-ip-match-strict` - refuse known players whose IP cannot be verified when IP matching is enabled. - `login-continuity.proxy-mode` - use behind BungeeCord/Velocity UUID forwarding so IdentityBridge does not rewrite proxy-forwarded UUIDs. - `monitoring.enabled` - enable background auth health checks. - `monitoring.check-interval-minutes` - how often to check auth health. - `monitoring.request-timeout-seconds` - timeout for auth probes, Mojang lookups, startup backfill, and Floodgate link resolution. - `migration.backup` - back up changed files before migration. - `migration.auto-migrate-on-rejoin` - automatically migrate temporary offline data when the player rejoins after the server is back online. - `migration.auto-migrate-require-ip-match` - require outage IP and authenticated rejoin IP to match before auto-migration. - `migration.data-locations` - UUID-keyed file templates to migrate. - `identity-resolution.use-mojang-api` - allow Mojang name-to-UUID lookups. - `startup-backfill.enabled` - scan existing player data on startup and learn known online UUIDs. - `bedrock.enabled` - enable optional Floodgate/Bedrock identity tracking. - `privacy.store-player-ip` - persist last-known player IPs for optional hardening and admin visibility. - `logging.verbose` - log extra per-login and per-migration detail. The config upgrades itself across plugin versions. New keys are merged with defaults, your existing values are kept, and the old config is backed up first. If the config cannot be parsed, IdentityBridge preserves the broken file and refuses to continue with guessed settings. ## Bedrock and Floodgate IdentityBridge has no hard dependency on Floodgate. On Java-only servers, it works normally. If Floodgate is installed, IdentityBridge: - Detects Bedrock players through the Floodgate API when available. - Records Bedrock identities keyed by XUID, not by display name alone. - Stores Floodgate UUID, linked Java UUID, and linked/unlinked state for admin visibility. - Never rewrites Bedrock UUIDs. - Supports both Floodgate global linking and local linking through Floodgate's own link manager. - Can record a linked Java account as a known Java player so that account also gets Java-side continuity during an outage. Floodgate UUIDs are already derived from the Bedrock XUID and are stable across online/offline server mode changes, so Bedrock players generally do not need the Java UUID rewrite path. IdentityBridge keeps that behavior intact. ## Security Model and Limitations IdentityBridge is an outage and data-preservation tool, not an authentication replacement. - **Offline mode is unauthenticated.** While `online-mode=false`, anyone can connect as any username. If they connect as a known player, login continuity can place them onto that player's real UUID. This is the main risk of offline mode itself. - **Mitigations are best-effort.** Keep offline mode brief, restrict access with a whitelist or firewall, consider `require-ip-match`, and consider `block-unknown-during-outage`. - **IP matching is not perfect.** Dynamic IPs, missing historical IPs, proxy setups, and privacy settings can all affect it. - **Monitoring is advisory.** A reachable endpoint is not a guarantee that every login will work, and an unreachable endpoint might be a local networking problem. IdentityBridge reports what it sees; admins decide what to do. - **Mojang lookups can fail.** During outages or rate limits, name-to-UUID lookups may not work. You can provide an online UUID manually when needed. - **IdentityBridge cannot invent history.** If a player never joined while the server was online and no existing online UUID can be discovered, there is no trusted online UUID to restore until one is provided or learned. - **Names matter in offline mode.** Offline UUIDs are derived from the exact username spelling used at login. IdentityBridge handles capitalization carefully and lets you specify exact offline names or UUIDs for migrations. - **Proxies are different.** Behind BungeeCord or Velocity with UUID forwarding, the proxy owns authentication and UUID forwarding. Set `proxy-mode: true`. If the proxy itself is switched to offline mode, that is outside IdentityBridge's scope because the plugin runs on the backend server. When IdentityBridge cannot make a safe decision, it reports the problem and preserves data instead of guessing. ## Files Stored by the Plugin Everything lives under `plugins/IdentityBridge/`: - `config.yml` - plugin configuration. - `identities.yml` - cached Java, offline, and Bedrock identities, plus startup-backfill ignored UUIDs. - `backups/` - timestamped migration backups. - `config.yml.backup-*` - backups from config upgrades. - `config.yml.corrupt-*` - preserved unreadable config files. - `identities.yml.corrupt-*` - preserved unreadable identity cache files. Do not hand-edit `identities.yml` while the server is running. Runtime state is authoritative, and `/idb reload` saves in-memory state before reloading the file. ## Permissions - `identitybridge.admin` - access to all `/idb` commands. Default: `op`. - `identitybridge.notify` - receive in-game advisories about auth outages and mode mismatches. Default: `op`. ## Source, Issues, and License Source code and issue tracker: https://github.com/jamesmblakely/IdentityBridge License: [GNU Affero General Public License v3.0 or later](https://www.gnu.org/licenses/agpl-3.0.html) (AGPLv3+). For alternative licensing terms, contact [email protected].