mudauth

Sign in to your MUD with Discord, GitHub, Google, Microsoft, Apple, Twitch, Facebook, or Steam. mudauth is a small, stateless OAuth/OIDC broker for games that implement the GMCP Authentication standard — supported today by Mudlet 5 and LociTerm.

• No database. It verifies a provider identity and hands {provider, provider_id, username} to your game once. Your game stays the source of truth for accounts and characters.
• No dependencies. Python 3.11+ standard library only. One process, one env file.
• No inbound port on the game. The game polls mudauth over loopback; only mudauth sits behind your TLS proxy.
• Eight providers, each enabled by environment variables — a client id and secret for the seven OAuth/OIDC providers, a single Web API key for Steam.

Install

pipx install mudauth            # or: pip install mudauth
brew install stickmud/tap/mudauth

Run

mudauth serve --env-file .env   # listens on 127.0.0.1:7700
mudauth check --env-file .env   # validates config and reaches the running service

.env is yours to write: AUTH_PUBLIC_BASE and one provider's id and secret are enough to start. pip/pipx install only the Python code and the mudauth command, so the annotated template lives in the source rather than on your PATH — take it from a checkout, from the sdist, or straight from the repository:

curl -fsSLO https://raw.githubusercontent.com/StickMUD/mudauth/main/.env.example
cp .env.example .env

Put a TLS reverse proxy in front of AUTH_PUBLIC_BASE and forward /auth/ to the loopback listener. See docs/deploy.md for systemd, nginx, and Apache.

Integrate your game

Your game starts a login with GET /auth/login/<provider>/<nonce>, hands the player the returned URL over Char.Login.URL, and polls GET /auth/token-poll?nonce= until the identity arrives. Full contract: docs/protocol.md. Driver-specific notes (LDMud efun, Evennia, Node): docs/integrating.md.

LDMud games get a ready-made efun: pip install "mudauth[ldmud]" registers auth_service_request(method, path, body).

Endpoints

Configuration

All settings are environment variables; --env-file loads a KEY=VALUE file.

One more variable belongs to the game side, not the service: AUTH_SERVICE_URL (default http://127.0.0.1:7700) names the loopback listener the game talks to.

Provider registration walkthroughs: docs/providers.md.

Security model

Random per-flow state (CSRF); client-generated nonce with a 10-minute TTL; the identity is returned exactly once and forgotten; non-loopback pollers must come from the IP that started the flow; provider secrets never leave the service. Loopback callers are trusted — the listener must stay on loopback. X-Forwarded-For and X-Real-IP are believed only from a loopback peer (your reverse proxy), and only the rightmost X-Forwarded-For element — the hop your proxy appended — is read, so a caller cannot name its own origin. If two proxies append to the header, set AUTH_TRUSTED_PROXY_HOPS=2.

Count the appending proxies exactly. Reading too few hops back binds every login to one of your own proxies' addresses instead of the player's; reading too many reads an element the client wrote whenever a client pads the header. The value is validated at startup — a non-integer or anything below 1 stops the service with a message rather than being clamped — and the effective count is printed in the startup banner. When a request's forwarding header is not the shape that count promises, or carries something that is not an IP address, the service logs an [auth][security] line and refuses the request; it never falls back to the loopback peer, which would make every origin match.

That "loopback caller" test is itself worth strengthening: by default it rests on the absence of X-Forwarded-For/X-Real-IP, which a proxy that stops adding them (a misconfiguration, not an attack) can erase for every internet caller at once. Set AUTH_SERVICE_TOKEN to the same value in the service's environment and the game's, and the exemption instead requires a loopback peer, a matching X-Auth-Service-Token header, and that same header absence — the token tightens the legacy rule, it does not replace it, so a caller who learns the token still cannot claim the exemption through the proxy. Unset is a supported, backward-compatible default — the service warns at startup — but see docs/deploy.md for the order to turn it on without taking logins down.

Both shipped proxy configs turn access logging off for /auth/, because the request line carries the nonce and the authorization code. Report vulnerabilities per SECURITY.md.

Test

python -m unittest discover -s tests -v

Credits and license

Originally built as the auth service for StickMUD, following the pattern proven by MUDdown. MIT licensed — see LICENSE.