Minecraft 1.20.1, 1.21.1용 VeloAuth 플러그인

VeloAuth

Complete Velocity authentication plugin with intelligent nickname protection, premium auto-login, secure offline player management, and optional self-contained embedded limbo.

What is VeloAuth?

VeloAuth is a comprehensive authentication system for Velocity proxy that handles all player authorization before they reach your backend servers. It includes a loopback-only embedded limbo while maintaining full compatibility with existing external limbo servers, all while protecting nickname ownership through intelligent conflict resolution.

Live test server

Want to see VeloAuth in action? 2b2t.pl runs the plugin in production — join the server to test premium auto-login, offline registration and nickname protection on a live network.

Key Features

• 🔒 Intelligent Nickname Protection - Premium nicknames are reserved unless already registered by cracked players.
• ⚡ Premium Auto-Login - Mojang account owners skip password entry after session verification; auth/limbo passthrough is an opt-in bypass.
• 🔄 Automatic Nickname Change Detection - Detects when a premium player renames their Mojang account and updates the database record automatically.
• 🛡️ Secure Offline Auth - BCrypt password hashing, brute-force protection, and atomic first-owner registration enforced by the database.
• 📱 Optional Floodgate Support - Bedrock and linked Floodgate accounts are detected before Mojang resolution; only UUIDs confirmed by Floodgate can bypass the auth server.
• 🧩 Optional Self-Contained Limbo - Use the built-in 1.8-base limbo with a reviewed, checksum-pinned ViaVersion runtime, or keep using an external limbo (NanoLimbo, etc.).
• 🗺️ Forced Hosts Support - Players connect via custom domains (e.g., pvp.server.com) and are properly routed to their intended server after authentication.
• 🚫 Smart Command Hiding - Authentication commands (/login, /register) are hidden while authorization is active; expired sessions expose them again.
• 🚀 High Performance - Bounded three-layer premium cache (in-memory → DB → Mojang/Ashcon API), virtual threads (Java 21), and zero blocking on Velocity event loops.
• 🔐 Optional 2FA (TOTP) - Opt-in RFC 6238 second factor compatible with Google Authenticator, Authy, Aegis. See 2FA.md for the operator handbook.
• 🔄 Conflict Resolution - Smart handling of premium/cracked nickname conflicts with /vauth conflicts.
• 📊 Admin & Diagnostic Tools - Health checks, statistics, and 1-click sanitized diagnostic reports via /vauth report (mclo.gs).
• 🗄️ Multi-Database - MySQL, PostgreSQL, H2, and SQLite with HikariCP connection pooling.
• 🌍 17 Languages & HEX Formatting - EN, PL, DE, FR, RU, TR, SI, FI, ZH_CN, ZH_HK, JA, HI, VI, KO, TH, ID, PT_BR with full RGB/HEX color support.
• 🔄 LimboAuth Compatible - 100% database schema compatibility with automatic, additive in-place migrations.
• 📢 Discord Alerts - Webhook notifications for security anomalies and resolver failure spikes with automated retry logic.

When to use VeloAuth

• You run a Velocity proxy with one or more backend servers and need authentication at the proxy layer (not per-backend).
• You accept both premium and cracked players and need automatic, fail-secure routing — premium players skip /login, cracked players go through BCrypt-hashed registration.
• You already use LimboAuth and want to migrate without losing data — VeloAuth reads and upgrades the same schema seamlessly.
• You want high performance — premium status is resolved through a three-layer cache without blocking proxy event loops.

If you only run a single backend server (Paper/Spigot/Folia) without a proxy, use a backend-side auth plugin instead.

Operating Profiles

Choose how strict nickname protection should be in plugins/veloauth/config.yml:

Profile 1 — Mixed strict (default, recommended)

premium: check-enabled: true allow-cracked-on-premium-nicks: false bypass-auth-server: false

• What you get: Premium players auto-login with real Mojang UUIDs; cracked players go through /register + BCrypt; premium nicknames are strictly reserved for Mojang owners.
• What you lose: Cracked clients trying to join with a registered Mojang username are rejected ("You are not logged into your Minecraft account").
• Best for: Public servers accepting both types of players where nickname theft prevention matters.

Profile 2 — Cracked-only

premium: check-enabled: false

• What you get: Zero HTTP traffic to Mojang/Ashcon, deterministic offline UUIDs for everyone.
• What you lose: Premium auto-login is disabled for all players; first player to register a nickname owns it.
• Best for: Private networks, dev environments, or pure offline-mode setups.

Profile 3 — Permissive mixed

premium: check-enabled: true allow-cracked-on-premium-nicks: true

• What you get: Existing premium accounts retain premium UUIDs; cracked players can register unclaimed premium-looking usernames.
• What you lose: New premium players connecting for the first time receive offline UUIDs permanently if not pre-registered as premium.
• Best for: Cracked-first communities that prioritize admitting all players without kick screens.

Goal - Recommended Profile

Maximum security, premium UUIDs preserved - 1 — Mixed strict No Mojang calls, pure offline network - 2 — Cracked-only Accept all connections, unreserved nicknames - 3 — Permissive mixed

Requirements

• Java 21 or newer (tested on Temurin 21)
• Velocity Proxy (3.4.0+ / 3.5.x line)
• Database: MySQL, PostgreSQL, H2 (default), or SQLite
• Auth Server Topology:
• External (default): NanoLimbo, LOOHP/Limbo, LimboService, PicoLimbo, or similar.
• Embedded (optional): Built-in 1.8 loopback limbo (requires outbound HTTPS to ViaVersion maven repo for runtime staging).

Quick Setup

1. Installation

• Download the latest veloauth-X.X.X.jar from Modrinth.
• Drop it into your Velocity plugins/ folder.
• Start and stop Velocity to generate configuration files in plugins/veloauth/.
• Configure database details and auth settings in plugins/veloauth/config.yml.
• Start Velocity.

2. Velocity Configuration (velocity.toml)

[servers] limbo = "127.0.0.1:25566" # External limbo server (keep out of try list!) lobby = "127.0.0.1:25565" # Primary backend lobby survival = "127.0.0.1:25567" # Secondary backend server

try = ["lobby", "survival"] # Fallback backend order for authenticated players

[forced-hosts]

Players joining via survival.example.com authenticate in limbo,

then get routed directly to 'survival' instead of 'lobby'.

"survival.example.com" = ["survival"]

3. VeloAuth Configuration (plugins/veloauth/config.yml)

language: en

auth-server:

'external' (default) uses registered limbo server; 'embedded' starts loopback limbo.

mode: external server-name: limbo timeout-seconds: 300 embedded: port: 0 # 0 = auto-select loopback port max-connections: 512 handshake-timeout-seconds: 10 login-timeout-seconds: 15

premium: check-enabled: true allow-cracked-on-premium-nicks: false

Set to true only if verified premium players should skip the auth-server completely

bypass-auth-server: false

Optional Floodgate integration

floodgate: enabled: false username-prefix: "." bypass-auth-server: true

Password Complexity Policy (Optional)

security: min-password-length: 8 max-password-length: 72 password-policy: min-digits: 0 # e.g., 1 = require at least one digit min-uppercase: 0 # e.g., 1 = require at least one uppercase letter min-lowercase: 0 # e.g., 1 = require at least one lowercase letter min-special: 0 # e.g., 1 = require at least one symbol

Commands & Permissions

Player Commands

Command - Description - Notes

/register - Register a new account - Hidden once logged in /login - Log into your account - Available in auth/limbo /logout - Invalidate session & disconnect - Clean disconnect; requires /login upon return /changepassword - Update your account password - Requires active session /2fa setup - Begin TOTP authenticator setup - Requires active session /2fa verify - Confirm TOTP setup or submit 2FA code - Standard RFC 6238 TOTP /2fa disable - Remove 2FA from account - Requires valid TOTP code /2fa qr / /2fa status - Show 2FA enrollment status - Re-enrollment instructions

Admin Commands (veloauth.admin)

Command - Description

/vauth reload - Reload configuration & language files /vauth report - Upload sanitized diagnostic bundle to mclo.gs /vauth stats - Show runtime cache, thread, and connection stats /vauth conflicts - List active nickname ownership conflicts /vauth cache-reset [player] - Clear premium resolver/auth caches /vauth 2fa-remove - Administrative 2FA reset for recovery /unregister - Delete account record from database

LimboAuth Migration

VeloAuth features 100% automatic LimboAuth schema migration:

• Stop LimboAuth on your backend servers.
• Install VeloAuth on your Velocity proxy.
• Configure plugins/veloauth/config.yml with the same database credentials.
• Start Velocity. Existing accounts and /premium flags will be converted seamlessly on startup without manual UUID rewrites.

Links & Support

• Source Code & Releases: GitHub Repository
• Issue Tracker: GitHub Issues
• Community & Support: Discord Server
• Documentation: 2FA Guide | Changelog
• License: MIT