ServerAUTH

Password + TOTP two-factor authentication for Paper/Purpur 1.21.x

Version 1.0.0 · Minecraft 1.21.x · Java 21 · Server-side

ServerAUTH is a login/registration plugin built for offline-mode and proxy setups, where the vanilla client identity cannot be trusted. Players register with a password, log in on every join, and can protect their account with a TOTP second factor (Google Authenticator, Authy, etc.). Passwords and recovery answers are hashed with BCrypt; the 2FA setup page is served by a built-in local web server so players can scan a QR code in their browser.

Features

• Password authentication with BCrypt hashing (configurable cost 10-16) and confirm-match on registration.
• TOTP two-factor authentication (RFC 6238, Google Authenticator compatible) with hashed backup codes and per-account verify lockout.
• Built-in web server for 2FA setup: the QR code and secret are generated locally (never sent to a third party) and shown on a page you can put behind a reverse proxy.
• Login lockdown for unauthenticated players: movement, chat, commands, inventory and interactions are frozen, optional blindness, and teleport to a configurable login spawn that can hide real coordinates.
• Reconnect grace period: reconnect from the same IP within a window without re-entering the password (2FA is always re-challenged, never skipped).
• 4-layer auto-login (username / UUID / IP / client fingerprint) with clear documentation of what each layer is worth on offline-mode servers.
• Account recovery via a security question/answer or a valid 2FA code, both rate-limited with lockout.
• Bedrock crossplay: optional auto-login for Floodgate players (their Xbox Live identity is verified before they reach the server).
• Admin tooling: /authadmin (requires OP and the admin's own 2FA) to look up, reset or delete accounts.
• Security logging with sensitive-command redaction, optional OP alerts on failed logins and UUID mismatches.
• Storage: SQLite (default) or MySQL, via a connection pool with versioned schema migrations.
• Policies: require 2FA for OPs/admins, limit accounts per IP, session and inactivity timeouts.

Offline-mode / proxy note

On offline-mode servers a player's UUID is derived from their name, so UUID and client-fingerprint checks are defence-in-depth only and can be spoofed. On these servers the password is the real gate and 2FA is the strong second factor — encourage players to enable 2FA and keep login attempt limits low. The bundled config.yml documents these trade-offs in detail.

Commands

Command	Description	Permission
/register <password> <password>	Register an account	serverauth.use
/login <password>	Log in	serverauth.use
/changepassword <old> <new> <confirm> (alias /cpw)	Change your password	serverauth.use
/logout	Log out	serverauth.use
/autologin <on|off|status>	Trusted-IP auto-login toggle	serverauth.use
/recovery <setquestion|setanswer|status>	Configure account recovery	serverauth.use
/recover	Recover an account (question answer or 2FA code)	serverauth.use
/2fa <setup|confirm|code|verify|disable|status> (aliases /twofa, /totp)	Manage two-factor auth	serverauth.use
/authhelp	Authentication help	serverauth.use
/help	Alias for /authhelp (only when override-help-command is enabled)	serverauth.use
/authadmin <lookup|setpassword|delete|reset2fa|reload> <player> [args]	Admin account management	serverauth.admin

Permissions

Node	Description	Default
serverauth.use	Use the authentication commands	true
serverauth.admin	Use /authadmin (also requires OP + the admin's own 2FA)	op

Configuration

Key sections of config.yml:

password:
  min-length: 6
  require-confirm-match: true

security:
  max-login-attempts: 5
  login-lockout-seconds: 300
  bcrypt-cost: 12            # 10-16; higher = slower & stronger

two-factor:
  enabled: true
  backup-code-count: 8
  max-verify-attempts: 5
  verify-lockout-seconds: 300
  setup-token-expiry-minutes: 15

# Built-in web server for the 2FA setup page
web-server:
  enabled: true
  port: 8921
  host: "0.0.0.0"           # 127.0.0.1 = local only (safer)
  public-url: "http://localhost:8921"

storage:
  type: sqlite              # sqlite or mysql
  sqlite:
    file: "auth.db"
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: ""
    use-ssl: false

Web server (2FA setup page)

The plugin runs a small HTTP server (default port 8921) that renders the 2FA setup page. The QR code is produced locally, so the TOTP secret never leaves your machine — but the page itself is plain HTTP.

• port — the TCP port the setup page listens on.
• host — bind address. 0.0.0.0 exposes it on all interfaces; 127.0.0.1 restricts it to the local machine (recommended if players set up 2FA from the server host, or if a reverse proxy runs locally).
• public-url — the URL players see in chat. Set it to your domain/IP.

Recommended hardening: if players need remote access to the setup page, put the web server behind a reverse proxy (nginx/Caddy) that terminates HTTPS, bind the plugin to 127.0.0.1, and set public-url to the https:// address. Avoid exposing the raw HTTP port to the public internet.

Other important sections documented inline in config.yml: lockdown (freeze behaviour, login spawn, allowed commands), autologin and fingerprint (4-layer verification), floodgate (Bedrock auto-login), and policy (require-2fa-for-ops/admins, max-accounts-per-ip, inactivity timeout).

Installation

1. Requires Paper or Purpur 1.21.x and Java 21.
2. Drop the JAR into your plugins/ folder and start the server once to generate config.yml.
3. Review the web-server, security and storage sections, then run /authadmin reload (or restart).

Dependencies

• Floodgate (optional) — enables Bedrock crossplay auto-login. Without it, Bedrock players simply register/log in like Java players.
• PlayerSettings (optional) — per-player language selection, if installed.

No hard dependencies; SQLite/MySQL drivers and the crypto libraries are bundled.

Support / Source

Source code: https://github.com/henriquescrrrr/carrageis-serverauth