Auth Tunnel (Minecraft Mod)

Latest release: Get the newest release here

If you are looking for the server software, please check out auth-tunnel-server

What is this?

Auth Tunnel is a Minecraft client mod that adds an account selector for remote accounts hosted on an AuthTunnel server. Instead of storing multiple accounts locally, this mod lets you pick from accounts provided by a running AuthTunnel server.

Warning

This project is in very early development and is expected to be unstable and full of bugs. Use at your own risk. Feel free to report bugs by opening an issue.

Screenshots

Requirements

• A compatible Minecraft client (Minecraft 26.3, 26.2, or 26.1.2, Fabric Loader 0.19.5 or newer)
• An AuthTunnel server running and reachable from the client. (I will link the AuthTunnel server repository and releases here later.)

Quick start

1. Install Fabric Loader 0.19.5 or newer and Fabric API for your exact Minecraft version.
2. Put only the matching jar in the instance's mods/ directory:
   • Minecraft 26.3: auth-tunnel-1.1.2+mc26.3.jar
   • Minecraft 26.2: auth-tunnel-1.1.2+mc26.2.jar
   • Minecraft 26.1.2: auth-tunnel-1.1.2+mc26.1.2.jar
3. Start Minecraft and open the Auth Tunnel account selector.
4. Enter only the server authority, such as auth.example.com or auth.example.com:8443. Do not enter https:// or a path.
5. Enter the non-admin API key assigned to you. Select Save API key permanently only if you want it stored for future game sessions, then press Connect.
6. Select one of the returned remote accounts. Select the local account to return to the launcher's original signed-in session.

If you need the server software, see the repository link above.

Configuration

The mod expects an AuthTunnel server URL and optional credentials (depending on server configuration). Typical settings you may need to provide:

• Server authority, for example auth.example.com
• AuthTunnel API key

Configuration can be entered in the mod UI or via the mod configuration file in the Minecraft config/ directory.

Changes are applied and sent only when Connect is pressed. The server address is saved automatically. The masked API key stays only in memory for the current game session unless Save API key permanently is selected; clearing that option removes a previously stored key on the next connection. Pressing Connect first returns to the original local account, so changing or rejecting an endpoint cannot leave a remote account active. Remote login succeeds only when the server explicitly confirms Mojang's HTTP 204 response.

When permanent saving is enabled, the configuration file contains the API key. The mod writes it atomically and restricts its permissions where the operating system supports that, but the file should still be treated as a secret. Do not upload the instance's config/ directory.

Building

Use JDK 25 to build any supported target from this source tree (26.3 is the default):

./gradlew clean build -Pminecraft_version=26.3
./gradlew clean build -Pminecraft_version=26.2
./gradlew clean build -Pminecraft_version=26.1.2

Troubleshooting

• If accounts don't show up: verify the server URL is correct and reachable from the client machine.
• If the server uses NetBird-Only access: verify NetBird is connected on the Minecraft machine and that its peer belongs to an allowed group.
• If a NetBird or other reverse proxy uses SSO, PIN, or password login: remove that browser challenge from the mod endpoint; the mod supports AuthTunnel bearer authentication, not interactive proxy login.
• If login fails: check server logs and ensure any required API keys or tokens are correct.
• If Minecraft rejects the mod: verify the jar's +mc... suffix exactly matches the game version and remove the other version's jar.
• Crashes on startup: remove the mod from mods/ and test; provide crash logs when reporting issues.

Contributing

Contributions, bug reports and feature requests are welcome. When opening issues or pull requests, please include:

• A clear description of the problem or feature
• Minecraft/mod loader version and mod version
• Steps to reproduce and any relevant logs

License

This project is licensed under the Apache License 2.0. See License.