Code
Search code…
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
- Install Fabric Loader
0.19.5or newer and Fabric API for your exact Minecraft version. - 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
- Minecraft
- Start Minecraft and open the Auth Tunnel account selector.
- Enter only the server authority, such as
auth.example.comorauth.example.com:8443. Do not enterhttps://or a path. - 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.
- 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.
Server compatibility and proxies
Upgrade the server and client together. This client requires the server's explicit
AUTH_TUNNEL/1 OK result after a successful Minecraft join; legacy servers that
only close the tunnel cannot confirm success. A deployment with an older server
and a newer client may fail for this reason; local tests do not prove the cause
of a particular live failure.
Supported proxy modes are DIRECT and unauthenticated HTTP CONNECT. The same
Minecraft proxy setting is used for account/certificate HTTPS, WebSocket HTTPS,
and CONNECT to sessionserver.mojang.com:443. SOCKS is rejected explicitly because
the JDK WebSocket client cannot apply that mode consistently. Authenticated HTTP
proxies are unsupported. Proxy failures never fall back to a direct socket.
TLS certificate/hostname validation remains on the server end of the relayed
Mojang TLS connection, and on the client for HTTPS/WSS to AuthTunnel.
The WebSocket upgrade budget is 45 seconds to allow the server's bounded 30-second account refresh. Tunnel idle and total budgets are 60 and 120 seconds; after upstream TCP EOF the result budget is 20 seconds (server response-header budget: 15 seconds). Account requests retain their shorter timeouts and may need a retry during a slow account refresh.

