Watch 1
Fork 0
You've already forked AuthTunnelServer

Latest commit message

DaTTV
Report safe filesystem error codes for account persistence
All checks were successful
ci/woodpecker/push/check Pipeline was successful
25e2a48 2026-11-06 22:30:16 +01:00 24 commits
2026-07-22 12:47:24 +02:00
2026-11-06 21:53:27 +01:00
2026-11-06 21:53:27 +01:00

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
  1. 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.
  2. 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.
  3. Put an HTTPS reverse proxy in front of port 8080. The mod deliberately accepts only HTTPS/WSS endpoints.
  4. Open the HTTPS URL in a browser, enter the admin API key, and use Add account to complete Microsoft's device login.
  5. Create a non-admin user in the dashboard, generate its API key, and assign the linked account UUIDs that user may access.
  6. 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.

Bridge containers

Native installs retain the default 127.0.0.1:8080 binding. In a bridge container, create a dedicated state directory owned by UID 10000 and place this config.toml in it before starting the container:

host = "0.0.0.0"
port = 8080

Mount that directory as the container working directory and publish only on host loopback (replace IMAGE with your built image):

docker run --rm --workdir /state -v "$PWD/state:/state" -p 127.0.0.1:8080:8080 IMAGE

Copy the release static/ directory into state/static/ as well: dashboard assets are resolved relative to the working directory. Keep a TLS reverse proxy on the host in front of 127.0.0.1:8080. Binding container loopback prevents bridge port publishing from reaching the service; publishing on all host interfaces would expose the plaintext HTTP API. Windows hosts must provision private directory ACLs rather than relying on Unix owner/mode settings.

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. Sessions are bound to the credentials verified at login; key rotation (including reusing the same key) and deleting/recreating a user invalidate old sessions. Permissions are refreshed for every request. Session storage is capped at 4096 total and 16 per user; excess logins return HTTP 429 without evicting existing sessions. Expired sessions are reclaimed on login and periodically.

Upgrade the server and client together: the current client requires the explicit AUTH_TUNNEL/1 result frame; a legacy server that only closes the tunnel cannot confirm success. A build passing does not validate Microsoft login or a live Minecraft join.

Account refresh has one 30-second network/lock budget before WebSocket upgrade. The client allows 45 seconds for upgrade, 60 seconds idle, 120 seconds total, and 20 seconds for the final result after upstream EOF; the server reads response headers within 15 seconds and recognizes a complete 204 without waiting for TLS EOF. Slow disk persistence can still delay pre-upgrade completion.

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.

Refreshing idle accounts

While the server is running, a background task checks for expired Minecraft tokens at startup and every five minutes after the previous sweep finishes. Accounts are refreshed sequentially through the same per-account lock and 30-second network budget used by login, and renewed credentials are saved atomically. Failed accounts are retried on the next sweep; one failure does not stop other accounts. The task does not run while the server is stopped. Microsoft authorization that has been revoked still requires signing in again through Add account.