# TrueUUID<\/p>\n
English | \u7b80\u4f53\u4e2d\u6587<\/p>\n
A Forge 1.20.X mod that securely verifies premium accounts on an offline-mode server during the login phase, without sending the player’s access token to the server.<\/p>\n
TrueUUID lets an offline-mode server:
\n– Ask the client to perform Mojang “joinServer” locally.
\n– Verify with Mojang Session Server from the server using a nonce.
\n– If verification passes: replace the player’s UUID with the official premium UUID, fix username casing, and inject skin properties.
\n– If verification fails or times out: configurable behavior (kick on timeout by default; failover to offline mode for verification failures by default).
\n– Inform the player on join with a Title whether they are in “Online\/Premium Mode” or “Offline Mode” and send an explanatory chat message for offline fallback.<\/p>\n
Note: Client and server must both install this mod. The server must run in offline mode.<\/p>\n
## Why<\/p>\n
– Privacy-preserving: the player’s access token never leaves the client. The client calls `joinServer(profile, token, nonce)` locally.
\n– Better identity integrity: even in offline mode, verified players keep their official UUID and skins.
\n– Clear UX: show Title messages for premium vs offline mode, plus a chat hint when falling back to offline.<\/p>\n
## How it works<\/p>\n
1. Server is in offline mode. During login (HELLO), the server sends a custom login query with a nonce (transactionId + identifier `trueuuid:auth` + data).
\n2. The modded client intercepts this query, reads the nonce, and locally calls `MinecraftSessionService.joinServer(profile, token, nonce)` (token never sent to the server).
\n3. The client replies with a boolean ack (no sensitive data).
\n4. The server calls Mojang Session Server `\/hasJoined?username={name}&serverId={nonce}[&ip={ip}]`.
\n5. If success:
\n – Replace the pending login `GameProfile` with premium UUID and the name returned from Mojang (ensuring correct casing).
\n – Inject skin properties (textures) with signature into the `GameProfile` property map.
\n – After join, force-refresh player info so skins update.
\n – Show a green Title “Premium Mode”.
\n6. If failure:
\n – Behavior is configurable. By default:
\n – Timeout: kick with configurable message.
\n – Any verification failure (ack=false \/ hasJoined failed \/ server error): fall back to vanilla offline flow (no UUID replacement), then:
\n – Show a red Title “Offline Mode” with a short subtitle.
\n – Send a chat message explaining that the session failed and it might be due to network issues.<\/p>\n
## Requirements<\/p>\n
– Minecraft: 1.20.X
\n– Forge: 47.x (e.g., 47.4.8)
\n– Java: 17
\n– Client and server must both install this mod.
\n– Server property: `online-mode=false`<\/p>\n
## Installation<\/p>\n
– Server:
\n – Set `online-mode=false` in `server.properties`.
\n – Place the built JAR in `mods\/`.
\n– Client:
\n – Place the same JAR in `mods\/`.<\/p>\n
Tip: If the client does not have this mod, the server will not receive a valid response to the custom login query. Depending on configuration, the server may kick or fall back to offline mode.<\/p>\n
## Configuration<\/p>\n
After the first run, a config file is generated:
\n– `config\/trueuuid-common.toml`<\/p>\n
Keys and defaults (reflecting the recommended behavior):
\n– `auth.timeoutMs = 10000`
\n – Login-phase wait time (milliseconds) for the client’s reply.
\n– `auth.allowOfflineOnTimeout = false`
\n – false: kick on timeout (default)
\n – true: allow offline fallback if timeout occurs
\n– `auth.allowOfflineOnFailure = true`
\n – true: allow offline fallback on any verification failure (default)
\n – false: disconnect on failure
\n– `auth.timeoutKickMessage = “\u767b\u5f55\u8d85\u65f6\uff0c\u672a\u5b8c\u6210\u6b63\u7248\u6821\u9a8c”`
\n – Kick reason shown on timeout.
\n– `auth.offlineFallbackMessage = “\u6ce8\u610f\uff1a\u4f60\u5f53\u524d\u4ee5\u79bb\u7ebf\u6a21\u5f0f\u8fdb\u5165\u670d\u52a1\u5668\uff1b\u5982\u679c\u4f60\u662f\u6b63\u7248\u8d26\u53f7\uff0c\u53ef\u80fd\u662f\u7f51\u7edc\u539f\u56e0\u5bfc\u81f4\u65e0\u6cd5\u6210\u529f\u9274\u6743\u3002”`
\n – Chat message shown to the player if they were allowed in via offline fallback.
\n– `auth.offlineShortSubtitle = “\u9274\u6743\u5931\u8d25\uff1a\u79bb\u7ebf\u6a21\u5f0f”`
\n – Short subtitle for the Title when in offline mode.
\n– `auth.onlineShortSubtitle = “\u5df2\u901a\u8fc7\u6b63\u7248\u6821\u9a8c”`
\n – Short subtitle for the Title when in premium mode.<\/p>\n
Notes:
\n– The “Title” uses short subtitles to avoid overflowing the screen.
\n– The long explanatory message is sent via chat when offline fallback happens.<\/p>\n
## Compatibility and notes<\/p>\n
– Proxies (Bungee\/Velocity): The server optionally includes the client IP in the Mojang `\/hasJoined` call when available. If you’re behind a proxy that hides the real IP, verification still works because `ip` is optional for Mojang’s endpoint.
\n– Skins: Skin properties are injected during login. The server broadcasts a player info refresh after join to force client-side skin updates.
\n– If the client is unmodded: it will not respond with the expected payload. Depending on config, the server will either kick or allow offline fallback.<\/p>\n
## Privacy<\/p>\n
– The player’s access token is never sent to your server. The token is used locally on the client to call `joinServer`.
\n– The server only receives a boolean ack and then itself contacts Mojang’s session server to verify the nonce.<\/p>\n
## License<\/p>\n
– GNU LGPL 3.0 (see `gradle.properties` \/ project license)<\/p>\n
## Credits<\/p>\n
– Mojang authlib and session API.
\n– Sponge Mixin.
\n– ForgeGradle.<\/p>\n
—
\nMaintained by: @YuWan-030<\/p>\n","protected":false},"excerpt":{"rendered":"
A Forge 1.20.X mod that securely verifies premium accounts on an offline-mode server during the login phase, without sending the player’s access token to the server.<\/p>\n","protected":false},"featured_media":160286,"template":"","meta":{"_minecraft_slug":"trueuuid","_minecraft_project_id":"fMgRLYNA","_minecraft_author":"YuWan030","_minecraft_license":"LGPL-3.0-only","_minecraft_downloads":11818,"_minecraft_follows":10,"_minecraft_client_side":"required","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"trueuuid.zip","_minecraft_size_bytes":198700,"_minecraft_version_count":5,"_minecraft_updated_at":"2026-05-16T02:53:58.815392Z","_minecraft_date_created":"2025-09-08T00:32:51.213342Z","_minecraft_date_modified":"2025-11-28T08:10:38.785763Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/trueuuid","_minecraft_icon_attachment_id":160286,"_minecraft_imported_at":"2026-06-09T14:49:21+00:00","_minecraft_import_hash":"6e56106048c12b0466de08e9a710720a","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[104,158],"mod_loader":[106,160],"minecraft_version":[36,60,93,94,101,102,37],"class_list":["post-160285","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-forge","mod_category-neoforge","mod_loader-forge","mod_loader-neoforge","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21-1"],"yoast_head":"\n