Watch 1
Fork 0
You've already forked AuthTunnelClient

Latest commit message

DaTTV
Release version 1.2.1
All checks were successful
ci/woodpecker/push/check Pipeline was successful
ci/woodpecker/tag/release Pipeline was successful
dac7db6 2026-11-06 21:36:40 +01:00 26 commits
2026-06-23 01:15:26 +02:00
2026-11-06 21:36:40 +01:00
2026-06-23 01:15:26 +02:00
2026-06-23 01:15:26 +02:00
2026-06-23 01:15:26 +02:00
2026-08-21 09:31:52 +00:00
2026-06-23 01:15:26 +02:00
2026-06-23 01:15:26 +02:00
2026-06-23 01:15:26 +02:00

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

screenshot_1.png screenshot_2.png

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.

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.