Getting Started
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/config/ConfigurationKeys.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java
- CHANGELOGS.md
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java
- plugin.yml
NexAuth is an open-source, multi-platform, and highly customizable authentication plugin for Minecraft servers. It is an updated fork of LibreLogin, designed for enhanced security and performance. This plugin provides a robust set of features to manage player authentication, including support for premium (online-mode) and offline-mode players, two-factor authentication (2FA), and data migration from other popular authentication plugins.
This guide will walk you through the initial setup, core features, and basic configuration of NexAuth to get your server protected quickly. For more detailed information on specific features, you can refer to other wiki pages like 2FA and Floodgate.
Sources: README.md, CHANGELOG.md:83-85
Core Features
NexAuth offers a comprehensive suite of features for server administrators.
| 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. |
| Session System | Remembers logged-in players for a configurable duration to avoid repeated logins. |
| Database Support | Works with MySQL, PostgreSQL, and SQLite for storing player data. |
| Data Migration | Provides tools to import player data from various other authentication plugins. |
| Limbo Integration | Uses a dedicated limbo server (NexLimbo) to securely isolate unauthenticated players. |
| Geyser (Bedrock) Support | Integrates with Floodgate to support Bedrock players. |
| Email Password Reset | Allows users to reset their password via email. |
| Secure Hashing | Implements modern password hashing algorithms like BCrypt and Argon2ID. |
Sources: README.md:19-26, CHANGELOG.md:90-99, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:302-305, 182-189
Requirements and Supported Platforms
Before installing, ensure your server environment meets the following requirements.
- Java Version: Java 21 or newer.
- Supported Platforms:
- Paper/Purpur (1.13 - 1.21.10)
- Velocity (3.4.0-SNAPSHOT)
- BungeeCord/Waterfall (Latest)
Sources: README.md:6, CHANGELOGS.md:36-40
Installation
Follow these steps to install NexAuth on your server or proxy.
- Download the latest
NexAuth.jarfrom the project's releases page. - Place the JAR file into the
pluginsdirectory of your Paper server or Velocity/BungeeCord proxy. - (Recommended for Proxies) Download and install NexLimbo, the dedicated limbo server for NexAuth, on your proxy. This provides the most secure and seamless authentication experience.
- Restart your server/proxy to generate the default configuration files.
- Open
plugins/NexAuth/config.ymlto configure the plugin, particularly the database connection and server settings.
Sources: CHANGELOGS.md:42-48, README.md:31-43
Dependencies
NexAuth integrates with several other plugins to enhance its functionality.
This diagram shows the relationship between NexAuth and its key dependencies.
- NexLimbo (Recommended): A lightweight limbo server specifically designed for NexAuth's authentication flow on proxies.
- Floodgate (Optional): Enables support for Bedrock players connecting via Geyser.
- LuckPerms (Optional): Enables a context provider for more granular permission control based on authentication status.
Sources: README.md:28-30, 26, plugin.yml:7-10, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:310-319
Plugin Startup Flow
When the server starts, NexAuth follows a specific sequence to initialize its components. This process ensures that all configurations are loaded, the database is connected, and all necessary handlers are ready before players can join.
This flowchart illustrates the main steps during the plugin's enablement phase.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java:30-50, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:237-323
Configuration Overview
NexAuth's behavior is controlled through configuration files located in the plugins/NexAuth/ directory. The main configuration file is config.yml.
Below are some of the most important keys to configure for a basic setup.
| Configuration Key | Default Value | Description |
|---|---|---|
database.type | nexauth-sqlite | The type of database to use. Can be nexauth-mysql, nexauth-postgresql, or nexauth-sqlite. |
limbo | ["limbo0", "limbo1"] | A list of server names (on proxy) or world names (on Paper) where unauthenticated players are sent. |
lobby | root: ["lobby0", "lobby1"] | A map of servers/worlds where authenticated players are sent. |
default-crypto-provider | BCrypt-2A | The default password hashing algorithm. BCrypt-2A and Argon-2ID are recommended. |
auto-register | false | If true, automatically registers players with a premium (paid Minecraft) username. |
totp.enabled | true | Enables or disables Two-Factor Authentication (2FA). |
session-timeout | 0 | Time in seconds a player's session is valid, allowing them to rejoin without logging in. 0 or less disables it. |
mail.enabled | false | Enables the email password recovery feature. Requires SMTP server configuration. |
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
Database and Migration
NexAuth requires a database to store user data. You can choose between SQLite for simple setups or MySQL/PostgreSQL for larger networks.
Database Migration
If you are switching from another authentication plugin, NexAuth provides a powerful migration tool.
The migration process is triggered by setting migration.on-next-startup to true in config.yml.
This diagram shows the automated database migration flow.
You must configure the migration.type and the old database connection details. Supported migration sources include:
authme-sqlite/authme-mysql/authme-postgresqljpremium-mysqlnlogin-sqlite/nlogin-mysqlloginsecurity-mysql/loginsecurity-sqlite- And many others.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:62-114, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:197-234
After following this guide, your server will have a basic but secure authentication system. For advanced features and further customization, explore the config.yml file and other pages in this wiki.