MAuth - Professional Authentication System for Hytale
A comprehensive and secure authentication plugin for Hytale servers developed by Machina Studios. MAuth provides robust account management, advanced security features, and an intuitive user experience for protecting your server and managing player identities.
Overview
MAuth is a complete authentication solution designed specifically for Hytale servers. It integrates directly with the game's native UI system, providing a polished in-game experience while offering server administrators extensive control over authentication flows, registration rules and security policies.
MAuth handles password-based authentication, persistent sessions, automatic token validation for premium players, two-factor authentication and an OAuth 2.0 REST API for external integrations - making it suitable for both casual servers and large production environments.
Why is the mod file so big?
Short version: CurseForge doesn't let me download database stuff at runtime, so everything ships inside the jar. Yes, everything.
Long version: MAuth needs database drivers for SQLite, MySQL and PostgreSQL. Normally you'd download only the one you actually use, but CurseForge forbids runtime downloads, so all three are bundled together so things just work 💼.
On top of that, Jakarta Persistence and Hibernate are included so the mod can store data without manual SQL - and since the API cannot fetch dependencies dynamically, everything must be packed into the mod archive.
None of this is unsafe, none of it connects to the internet, it's just chunky. I'm in contact with CurseForge to explore a cleaner solution.
Key Features
MAuth offers a wide range of features that make account management seamless, secure and configurable:
- Secure password-based login using BCrypt hashing 🔐
- Premium/online account auto-authentication via identity tokens 🎫
- Optional two-factor authentication for enhanced security 🔑
- Configurable registration requirements to match server policies ⚙️
- Multi-database support (SQLite, MySQL, PostgreSQL) 🗄️
- Native UI pages for login, registration and settings 📱
- Persistent sessions to avoid constant re-authentication 🔁
- Brute-force protection with lockout rules 🚧
- Chat and movement protection until authentication completes 🚫
- Offline mode compatibility with hybrid workflows 🌐
- OAuth 2.0 REST API for external integrations 🧩
Advanced Security
Security is a core pillar of MAuth. Passwords are hashed with BCrypt, tokens are validated, sessions are isolated, and optional two-factor authentication with TOTP enables enterprise-grade login protection.
Brute force defenses apply to in-game authentication through IP-based and account-based lockouts, while session expiration and cleanup prevent unauthorized persistence.
User Experience
MAuth integrates with Hytale's UI system to present modern UI pages:
- Login page that dynamically switches to 2FA when required
- Registration page with optional fields
- Settings page with separate account and security tabs
Players are temporarily restricted from moving or chatting until authentication completes, preventing grief or abuse during the login window.
MAuth supports both online and offline servers, and can automatically authenticate legitimate premium users even if the server itself runs in offline mode - striking a balance between usability and control.
Internationalization
MAuth is localized for multiple languages out of the box, including:
- English (en-US)
- Portuguese (pt-BR)
- Russian (ru-RU)
- Polish (pl-PL)
Additional languages can be added and translators are welcome.
Configuration
Configuration for MAuth lives in:
config/com.machina/mauth (preferred and used when writable)- fallback:
mods/com.machina/mauth (used when the primary path cannot be written)
Configuration files use JSON5, which allows comments, trailing commas and more flexibility than strict JSON.
MAuth's configuration is organized into the following domains:
Database Settings
database.type: backend to use (sqlite, mysql, postgres)database.host / database.port: network connection for SQLdatabase.name: DB name or SQLite filedatabase.username / database.password: credentials for SQLdatabase.schema: optional schema for SQL environments
Registration Settings
registration.required: controls when registration is required (REQUIRED_FOR_ALL, SKIPPED_FOR_ONLINE_MODE, OPTIONAL)registration.fields.*: toggles registration form fieldsregistration.validation.*: applies password policies
Login Settings
login.timeoutSeconds: disconnects players who fail to authenticate in time
Persistent Session Settings
session.persistent.enabled: enables reconnect without passwordsession.persistent.durationMinutes: expiration window
Security Settings
security.twoFactor.enabled: enables TOTP 2FAsecurity.lockout.*: IP and account brute-force protections
OAuth 2.0 API
api.enabled: enables REST OAuth APIapi.port: port to bindapi.jwt.*: token signing and expirations
OAuth 2.0 API
MAuth provides an optional OAuth 2.0 REST API that external systems can use to authenticate accounts, validate credentials, fetch profile data or implement web panels and companion apps 📡.
The API supports the Resource Owner Password Credentials flow and issues both access and refresh tokens. It is disabled by default, and should be placed behind a proxy or load balancer for rate limiting and security.
Technical Details
MAuth uses industry-standard components and practices:
- BCrypt for password hashing
- JPA/Hibernate for database abstraction
- Ed25519 identity token verification for premium players
- Native UI integration for seamless UX
- Event-driven architecture for extensibility
- Automatic schema creation and migration
Persistent sessions use secure token interception and validation, and expire automatically after configurable time windows.
Installation
- Place the MAuth jar into the server's
mods directory
- Configure
config.json5 for your desired workflow
- Restart or reload plugins
- The plugin initializes storage and begins managing authentication
Support Development
You can support development here 💖 to help fuel future updates and features:
https://machinastudios.net/support-us
Community
💬 Join our Discord community!
Get help, share ideas, and connect with other developers 🧑💻:
- 🆘 Support and troubleshooting
- 💡 Suggestions and feedback
- 🤝 Community and collaboration
👉 Join our Discord Server: https://discord.gg/QAFrzj48EN
