Auth Tunnel (Server)

Latest release: Get the newest release here

If you are looking for the client mod, please check out AuthTunnelClient.

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.

Quick Setup

1. Extract the release archive into a dedicated directory. Keep the included static/ directory next to the binary.
2. Start the server from that directory:

chmod +x auth-tunnel-server
./auth-tunnel-server

3. On first start the server creates config.toml, users.toml, and accounts_cache.json. Back up users.toml and accounts_cache.json; both contain security-sensitive state.
4. Copy the initial admin API key printed once in the server console. API keys are stored only as salted SHA-256 hashes and cannot be recovered later.
5. Put an HTTPS reverse proxy in front of port 8080. The mod deliberately accepts only HTTPS/WSS endpoints.
6. Open the HTTPS URL in a browser, enter the admin API key, and use Add account to complete Microsoft's device login.
7. Create a non-admin user in the dashboard, generate its API key, and assign the linked account UUIDs that user may access.
8. Give each player only their own non-admin API key. Do not share the admin key.

Run the server under a service manager for normal use. The process must use the extracted directory as its working directory because state and dashboard paths are relative to it.

NetBird Reverse Proxy

NetBird Reverse Proxy supports the HTTP and WebSocket traffic used by AuthTunnel and terminates public TLS. NetBird currently documents this feature as beta.

For a quick or private deployment on the same NetBird peer, leave config.toml on its safe loopback default and run:

netbird up
netbird expose 8080 --with-name-prefix auth-tunnel

Use the hostname from the displayed HTTPS URL in the mod, without https:// or a trailing path. netbird expose is ephemeral and must remain running; NetBird removes it when the command exits or its lease expires.

For a permanent dashboard-managed NetBird service:

1. Create an HTTP reverse-proxy service, not TCP or TLS passthrough.
2. Select the server's NetBird peer as the target, protocol HTTP, port 8080.
3. Bind AuthTunnel to that peer's NetBird IP in config.toml. If your NetBird installation requires 0.0.0.0, add host firewall and NetBird policy rules that allow port 8080 only through the NetBird interface.
4. Enable TLS on the NetBird public domain and verify the service reports active.
5. Do not enable browser-interactive SSO, PIN, or password authentication on this service; the Minecraft mod cannot complete a browser challenge. Use NetBird-Only access when every client is a permitted NetBird peer, or rely on AuthTunnel's per-user API keys plus NetBird access restrictions.

Never expose port 8080 directly to the internet. Also configure proxy access logs not to retain query strings for /api/authenticate.

Other Proxies

For Caddy on the same host, keep host = "127.0.0.1" and proxy only from the TLS listener:

auth.example.com {
    reverse_proxy 127.0.0.1:8080
}

The server serves dashboard files from the static/ directory next to the binary. Caddy automatically supports the WebSocket upgrade used by /api/authenticate.

State Files

• config.toml: bind host and port.
• users.toml: users, salted API-key hashes, per-user salts, admin flags, and allowed account UUIDs. Existing plaintext keys are migrated on startup.
• accounts_cache.json: Microsoft and Minecraft account tokens. Treat this as a secret.
• static/: dashboard assets required by the release binary.

State writes are atomic and owner-only on Unix. Restrict the service account and directory ACLs as well, especially on Windows. Stop the server before manually editing state files.

The dashboard exchanges an API key for an opaque, in-memory session token stored in a Secure, HttpOnly, SameSite=Strict cookie for 24 hours. The API key itself is never stored in the browser. The Minecraft mod continues to authenticate directly with its bearer API key.

Authentication tunnels end with a fixed AUTH_TUNNEL/1 OK result only after Mojang returns HTTP 204. Any handshake, I/O, status, or timeout failure returns a payload-free error result and closes the tunnel.

Updating

Stop the process, back up the three state files, replace the binary and static/ directory from the new release archive, then restart it from the same working directory. Never replace users.toml or accounts_cache.json with files from the archive.

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
• Steps to reproduce and any relevant logs

License

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