TrueUUID

TrueUUID is a login-phase authentication mod for offline-mode Minecraft servers.

It lets an offline-mode server verify premium Mojang accounts and supported Yggdrasil/authlib-injector skin-site accounts, without ever receiving the player's access token.

Client and server must both install this mod. The server must run with:

online-mode=false

What's New in 1.1.0

• Added Minecraft language-file based UI localization.
  • Chinese clients see Simplified Chinese text.
  • English clients see English text.
  • The server sends translatable components instead of hardcoded bilingual messages.
• Added localized text for:
  • Join Title feedback
  • Offline fallback chat messages
  • Offline data inheritance confirmation screens
  • Disconnect reasons
  • Admin command feedback
• Added auth.showJoinFeedback to disable join feedback Title/chat messages without changing authentication or skin refresh behavior.
• Changed default configurable messages to trueuuid.* translation keys while keeping custom plain-text messages compatible.
• Removed the obsolete auth.nomojang.enabled bypass option and related NoMojang logic.
• Version updated to 1.1.0 for Forge 1.20.1 and NeoForge 1.21.1 builds.

Features

• Privacy-preserving authentication: the player's access token is only used locally on the client.
• Premium/Yggdrasil UUID support on offline-mode servers.
• Correct username casing after successful verification.
• Signed skin texture injection during login.
• Player info refresh after joining, helping skins update correctly.
• Localized join feedback for premium, skin-site, offline fallback, and single-player states.
• Offline-to-verified player data inheritance with confirmation and backups.
• Admin commands for inheriting or cleaning duplicate offline UUID data.
• Protection against known verified players rejoining with the same name in offline mode.

Why

Offline-mode servers normally cannot trust player UUIDs. TrueUUID improves identity integrity while keeping the server in offline mode.

Verified players can keep their official Mojang or Yggdrasil UUID and skin data, while the server never sees their access token.

This is useful for modpacks, LAN-style servers, private offline-mode communities, and servers that want better identity consistency without enabling Mojang online-mode directly.

How It Works

1. The server runs in offline mode.
2. During login, the server sends a custom login query with a nonce.
3. The modded client receives the query and locally calls joinServer with the player's profile, token, and nonce. The token never leaves the client.
4. The client replies with the authentication result and the selected authentication source.
5. The server verifies the nonce through Mojang Session Server or a supported Yggdrasil hasJoined endpoint.
6. If verification succeeds:
   • The pending login profile is replaced with the verified UUID.
   • Username casing is corrected.
   • Signed skin texture properties are injected.
   • The authentication source is recorded.
   • Player info is refreshed after joining.
7. If verification fails or times out:
   • Behavior is controlled by the config.
   • Known verified names can be prevented from falling back to offline mode.
   • Unknown names may still be allowed to use offline fallback if configured.

Offline Data Inheritance

TrueUUID includes a safer inheritance flow for players who used to play offline and later switch to a premium or skin-site account with the same name.

When a verified login detects matching offline UUID data, the player will see a confirmation screen. Inheritance only happens after confirmation.

Before inheriting, TrueUUID backs up both the old offline data and any existing target verified UUID data.

After inheritance, that player name is bound to the verified Mojang/Yggdrasil UUID and can no longer be used by an offline identity.

Admins can also handle duplicate UUID data manually:

/trueuuid migrateuuid <name> Inherit same-name offline UUID data into the verified Mojang/Yggdrasil UUID, with backups.

/trueuuid cleanupuuid <name> Back up and remove duplicate offline UUID data without touching the verified UUID data.

Supported data targets include:

• Vanilla playerdata
• Vanilla playerdata_old
• Advancements
• Stats
• Cosmetic Armor .cosarmor data
• Open Parties and Claims
• FTB Chunks
• FTB Essentials
• FTB Teams
• FTB Quests
• FTB Ranks
• CustomNPCs playerdata

Requirements

Forge build:

• Minecraft: 1.20.1
• Forge: 47.x
• Java: 17

NeoForge build:

• Minecraft: 1.21.1
• NeoForge: 21.1.x
• Java: 21

Client and server must both install TrueUUID.

Server must use:

online-mode=false

Installation

Server:

1. Set online-mode=false in server.properties.
2. Place the matching TrueUUID jar in the server's mods folder.

Client:

1. Place the matching TrueUUID jar in the client's mods folder.

If the client does not have this mod installed, the server will not receive the expected login query response. Depending on configuration, the player may be kicked or allowed to fall back to offline mode.

Configuration

After the first run, the config file is generated at:

config/trueuuid-common.toml

Important options:

auth.timeoutMs = 30000 Login-phase wait time in milliseconds.

auth.allowOfflineOnTimeout = false false: kick on timeout. true: allow offline fallback on timeout.

auth.allowOfflineOnFailure = true true: allow offline fallback for normal verification failures. false: disconnect on verification failure.

auth.knownPremiumDenyOffline = true If a name has already been verified as premium or Yggdrasil, deny later offline fallback for that name.

auth.allowOfflineForUnknownOnly = true Only allow offline fallback for names that have never been verified before.

auth.recentIpGrace.enabled = true Allows a short same-IP reconnect grace period after a verified player disconnects. This grace is not used when the client explicitly rejects authentication or logs in as offline.

auth.recentIpGrace.ttlSeconds = 10 Same-IP grace time window in seconds.

auth.showJoinFeedback = true Show join feedback Title/chat messages for premium, skin-site, offline fallback, and single-player states. Set to false to silence those messages without changing authentication, data inheritance, or skin refresh behavior.

auth.timeoutKickMessage = "trueuuid.disconnect.timeout" Timeout kick message. Keep the default trueuuid.* key for client-side localization, or replace it with plain text for a custom server-defined message.

auth.offlineFallbackMessage = "trueuuid.chat.offline_fallback" Chat message shown when a player is allowed in via offline fallback.

auth.offlineShortSubtitle = "trueuuid.subtitle.offline" Short subtitle used for the Offline Mode Title.

auth.onlineShortSubtitle = "trueuuid.subtitle.online" Short subtitle used for the Premium Mode Title.

auth.yggdrasil.apiRootWhitelist = [] Whitelist for Yggdrasil/authlib-injector hasJoined URLs. An empty list trusts the endpoint reported by the client. Add entries such as "littleskin.cn" to restrict accepted skin-site sources.

NeoForge 1.21.1 also provides:

auth.mojangReverseProxy = "https://sessionserver.mojang.com" Mojang Session Server endpoint. This can be changed to a reverse proxy if needed.

Note: auth.nomojang.enabled was removed in 1.1.0 because it bypassed the core session verification flow and conflicted with TrueUUID's authentication model.

Localization Notes

Default feedback and disconnect messages are sent as Minecraft translation keys and rendered by the player's client language files.

Currently included:

• en_us
• zh_cn

If you previously generated a config with custom bilingual strings, those old strings will still be used as custom plain-text messages. Change the values back to trueuuid.* keys or regenerate the config to use client-side localization.

Compatibility Notes

Proxies: Mojang's hasJoined ip parameter is optional. Verification can still work when the real client IP is hidden by a proxy.

Skins: TrueUUID injects signed skin properties during login and refreshes player info after joining. If a client still shows stale skins, rejoining or clearing the skin cache may help.

Offline fallback: Offline fallback is configurable. In the recommended setup, previously verified names cannot be reused by offline clients.

Registry: TrueUUID stores known verified names in trueuuid-registry.json. If this file is cleared, the server forgets previous premium/Yggdrasil bindings.

Privacy

The player's access token is never sent to the server.

The client uses the token locally for joinServer. The server only receives the authentication result and verifies the nonce through Mojang Session Server or a supported Yggdrasil endpoint.

License

GNU LGPL 3.0