ServerAUTH

Minecraft 版本： 26.2

平台： paper purpur

标签： management utility

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

Permissions

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