Home
Relevant source files
The following files were used as context for generating this wiki page:- README.md
- CHANGELOG.md
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
- API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java
- Plugin/src/main/resources/plugin.yml
- Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java
- CHANGELOGS.md
- Plugin/src/main/resources/LICENSE.txt
NexAuth is an open-source, multi-platform, and highly customizable authentication plugin for Minecraft servers. It is an updated fork of LibreLogin, focusing on enhanced security, performance, and modern features. The plugin is designed to be robust and flexible, supporting various server platforms and databases.
The project requires Java 21 or newer to run. It is licensed under the Mozilla Public License 2.0, ensuring it remains free and open-source.
Sources: README.md, Plugin/src/main/resources/LICENSE.txt, CHANGELOG.md:14
Core Features
NexAuth provides a comprehensive set of features for server authentication and security.
| Feature | Description |
|---|---|
| Multi-platform Support | Natively supports Paper, Velocity, and BungeeCord. |
| AutoLogin | Automatically logs in premium players. |
| TOTP 2FA | Supports Time-based One-Time Passwords with apps like Authy and Google Authenticator. See 2FA for details. |
| Session System | Remembers logged-in players for a configurable duration to avoid repeated logins. |
| Geyser (Bedrock) Support | Integrates with Floodgate to support Bedrock players. See Floodgate for details. |
| Data Migration | Provides commands and automated tools to migrate user data from other authentication plugins. |
| Secure Hashing | Uses modern password hashing algorithms like BCrypt and Argon2-ID. |
| Limbo Integration | Uses a dedicated limbo server (NexLimbo) for a secure and seamless authentication experience. |
| Email Support | Allows users to reset their passwords via email. |
| Packet-level Inventory Hiding | Hides the inventory of unauthenticated players to prevent item access before login. |
Sources: README.md:18-26, CHANGELOG.md:83-91, 55-56, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:214-219, 313-318
Supported Platforms
NexAuth is designed to work across the modern Minecraft server ecosystem.
- Proxy Servers:
- Velocity (3.4.0-SNAPSHOT and newer)
- BungeeCord / Waterfall (Latest)
- Application Servers:
- Paper / Purpur (and other Paper forks)
- Minecraft Versions:
- Supports a wide range of versions from 1.13 to 1.21.10.
- Java Version:
- Requires Java 21+.
Sources: README.md:10, 56-59, CHANGELOG.md:14, 40-43, Plugin/src/main/resources/plugin.yml:4-5
Architecture Overview
The plugin is built around a core module with platform-specific implementations. The main class, AuthenticNexAuth, orchestrates all components, including database connections, cryptography, event handling, and platform interactions.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
Core Components
This diagram illustrates the main components of NexAuth and their relationships.
*AuthenticNexAuth**: The central class that initializes and manages all other components of the plugin during its lifecycle (enable/disable).
PlatformHandle: An abstraction layer that provides platform-specific functionalities like moving players, sending kicks, and getting server information. Implementations exist for Paper (PaperPlatformHandle).DatabaseProvider: Manages all interactions with the database, including user data storage and retrieval.CryptoProvider: Handles password hashing and verification. Multiple algorithms are supported.AuthorizationProvider: Manages the authentication state of players (e.g., checking if a player is logged in).ServerHandler: Manages lobby and limbo server logic, including selecting an available server for a player.EmailHandler: Handles sending emails for features like password reset.- Integrations: NexAuth integrates with external plugins like NexLimbo, Floodgate, and LuckPerms to provide extended functionality.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:90-120, 190-220, API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperPlatformHandle.java
Dependencies
Required Dependencies
NexLimbo
For proxy setups (Velocity/BungeeCord), NexLimbo is highly recommended. It is a lightweight limbo server specifically designed and optimized for NexAuth's authentication flow, providing enhanced security and performance.
Sources: README.md:28-46, CHANGELOG.md:23-28
Optional Integrations (Soft Dependencies)
NexAuth automatically detects and integrates with the following plugins if they are present:
Floodgate: Enables support for Bedrock players connecting via Geyser. The plugin checks forfloodgateand initializesFloodgateIntegration.LuckPerms: Provides a context provider for permission checks. The plugin checks forluckpermsand initializesLuckPermsIntegration.
Sources: Plugin/src/main/resources/plugin.yml:8-11, Plugin/src/main/resources/paper-plugin.yml:8-17, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:298-308
Plugin Initialization Flow
The following diagram shows the sequence of actions performed when the NexAuth plugin is enabled.
Configuration
NexAuth is configured via config.yml inside its data folder (plugins/NexAuth/). The configuration uses the HOCON format.
Key Configuration Options
Below are some of the most important configuration keys.
| Key | Default Value | Description |
|---|---|---|
database.type | nexauth-sqlite | The database type to use (e.g., nexauth-mysql, nexauth-postgresql). |
default-crypto-provider | BCrypt-2A | The default algorithm for hashing new passwords. (Options: SHA-256, SHA-512, BCrypt-2A, Argon-2ID). |
limbo | ["limbo0", "limbo1"] | A list of server names or worlds to use as authentication limbo servers. |
lobby | root: ["lobby0", "lobby1"] | A map of servers or worlds to send players to after successful authentication. |
totp.enabled | true | Enables or disables Time-based One-Time Password (2FA) functionality. |
mail.enabled | false | Enables or disables the email password recovery feature. |
auto-register | false | If true, automatically registers players who have a premium (paid) Minecraft account. |
session-timeout | 0 | Time in seconds after which a player's session expires. 0 or less disables sessions. |
hide-player-inventory | true | Hides a player's inventory on a packet level until they are authenticated. |
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
Database & Migration
NexAuth supports multiple database backends and includes a powerful migration system to import data from other popular authentication plugins.
Supported Databases
- MySQL
- PostgreSQL
- SQLite
These are registered in the setupDB() method.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:464-482
Data Migration
The plugin can migrate data from various sources. This process is configured in the migration section of config.yml and is triggered by setting migration.on-next-startup to true.
Supported migration sources include:
- AuthMe (MySQL, SQLite, PostgreSQL)
- JPremium (MySQL)
- NLogin (SQLite, MySQL)
- LoginSecurity (MySQL, SQLite)
- FastLogin (MySQL, SQLite)
- And several others.
The migration process involves connecting to the old database, reading all user data, and inserting it into the new NexAuth database.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:237-285, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:62-114, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:484-565
Security
Password Hashing
NexAuth supports multiple secure password hashing algorithms. The default is BCrypt-2A, but Argon-2ID is also available for higher security, though it may be more resource-intensive. Older algorithms like SHA-512 and SHA-256 are included for compatibility with migrated data.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:94-102, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:247-252
Forbidden Passwords
The plugin uses a forbidden-passwords.txt file to prevent players from using common and weak passwords. This file is downloaded from the official repository on first startup. Any password in this list will be rejected during registration or password change.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:181-189, 567-594
Update Checker
NexAuth features a reliable update checker that uses multiple fallback methods to ensure it can always retrieve the latest version information.
This diagram shows the fallback logic of the update checker.