TrueUUID
Running a modded Minecraft server in offline mode often invites security risks, particularly regarding identity spoofing and skin theft. Server administrators frequently struggle to balance accessibility for players without premium accounts while ensuring that verified users retain their unique identities and skins. This is where TrueUUID steps in as a vital solution. It adds a robust layer of account verification to modded servers running in offline mode, allowing premium players to prove their ownership without ever sending their sensitive access tokens to the server.
The core philosophy behind this add-on is privacy and security. When a player joins, their access token remains strictly on their own computer. The server only receives the necessary login proof required to verify their UUID and skin properties. This mechanism ensures that even if the server is compromised, user credentials remain safe. To function correctly, the same TrueUUID JAR file must be installed on both the client side and the server side, creating a secure handshake between the two.
How Login Verification Works
Understanding the technical flow helps administrators trust the system. When an offline-mode server initiates a connection, it sends a one-time login challenge to the client. The client then uses its local session to answer this challenge through Mojang's standard joinServer call. Crucially, the access token never leaves the client's environment. The server subsequently checks the result using Mojang's hasJoined endpoint.
If the check is successful, the server grants the player their verified UUID and signed skin properties. If the check fails or times out, the server handles the situation based on the configured offline-fallback policy. This flexibility allows server owners to decide whether unknown players can join in offline mode while preventing previously verified names from being reused by impostors. For those managing custom authentication providers like Yggdrasil or authlib-injector, the same secure flow applies via HTTPS session endpoints, provided the host is explicitly allowlisted.
For users who prefer a streamlined setup process, modern tools can simplify the installation significantly. If you are using the foxygame.net launcher, you can leverage its integrated add-on catalog to find TrueUUID instantly, ensuring you grab the correct version for your specific loader without manual file hunting. This one-click install feature reduces configuration errors and keeps your modpack consistent across different machines.
Supported Versions and Loaders
Compatibility is paramount when dealing with modded environments. TrueUUID supports a wide matrix of Minecraft versions and loaders, including Fabric, Forge, and NeoForge. However, precision is key; you must always choose the JAR built for your exact Minecraft version and loader. Version 1.2.0, for instance, publishes only 36 exact targets approved in the target matrix. Omitted Minecraft patches are not implicitly supported, so assuming a JAR for version 1.20.4 will work on 1.20.6 could lead to crashes or failed verifications.
When searching to download TrueUUID, ensure you select the file matching your server's architecture. For Fabric users, it is critical to use the remapped JAR found in the build/libs directory, never the development JAR located in build/devlibs. Similarly, do not attempt to load a Forge JAR into a NeoForge environment, as the underlying APIs differ significantly despite their shared heritage.
Installation Guide
Installing TrueUUID for Minecraft involves a few straightforward steps for both server and client setups:
- Server Setup: Install the loader and Minecraft version matching the TrueUUID filename. Copy the JAR into the server's
modsdirectory. Openserver.propertiesand setonline-mode=false. It is highly recommended to keep the server behind a firewall during initial configuration. - Client Setup (Prism Launcher): Open the instance matching the JAR's Minecraft version. Navigate to Edit → Mods → Add file and select the built TrueUUID JAR. Ensure this matches the server version exactly.
- Verification: Start the server once to generate the configuration file, then join with a matching modded client. The HUD will display a green badge for verified premium logins and a red indicator if the server accepts an offline fallback.
Knowing how to install the configuration correctly is just as important as placing the files. Forge and NeoForge generate a config/trueuuid-common.toml file, while Fabric generates config/trueuuid.json. Within these files, administrators can fine-tune policies such as auth.allowOfflineOnFailure or auth.knownPremiumDenyOffline. The recommended defaults are designed to allow unknown offline names initially but prevent those names from falling back to offline mode after they have successfully completed a verified login once.
Migration and Admin Commands
One of the most powerful features of TrueUUID is its ability to handle data migration. It can back up and move same-name offline player data to a verified UUID, preserving world progress when a player finally verifies their account. This process requires confirmation and safely preserves both old offline data and any existing destination data before modifying files.
Administrators with permission level 4 can utilize specific commands to manage these transitions:
/trueuuid cleanupuuid <name>: Cleans up residual data for a specific name./trueuuid migrateuuid <name>: Initiates the migration process for a player.
Additionally, the server-side API exposes methods for other mods to query a player's status. Developers can check if a player joined as premium or through offline fallback, allowing for customized gameplay rules based on verification status. Whether you are running a small community server or a large network, TrueUUID provides the necessary tools to maintain integrity without sacrificing the flexibility of offline mode.
In conclusion, securing your Minecraft server does not require compromising on player accessibility. By implementing TrueUUID, you ensure that premium players are recognized correctly while maintaining strict control over who can impersonate them. With support for major loaders like Fabric, Forge, and NeoForge across numerous versions, it stands as an essential utility for any serious server administrator looking to protect their community's identity and data.