Installation Guide

Relevant source files

The following files were used as context for generating this wiki page:

• Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityBootstrap.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordBootstrap.java
• 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/PaperNexAuth.java
• README.md
• CHANGELOG.md
• Plugin/src/main/resources/plugin.yml
• Plugin/src/main/resources/bungee.yml
• Plugin/src/main/resources/paper-plugin.yml
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java

NexAuth is a multi-platform, open-source authentication plugin for Minecraft designed for security and performance. It supports proxy servers like Velocity and BungeeCord, as well as standalone Paper servers. This guide provides comprehensive instructions for installing and setting up NexAuth on your server environment.

The plugin provides features such as secure password hashing, TOTP 2FA, session management, and automatic data migration from other authentication plugins. For proxy setups, it is highly recommended to use NexAuth in conjunction with NexLimbo, a purpose-built limbo server that isolates unauthenticated players.

Sources: README.md, CHANGELOG.md

1. Prerequisites

Before installing NexAuth, ensure your server environment meets the following requirements.

System Requirements

Requirement	Details	Source
Java Version	Java 21 or higher is required to run the plugin.	README.md, CHANGELOG.md
Minecraft Version	Supports versions from 1.13 to 1.21.10.	CHANGELOG.md:16

Supported Platforms

NexAuth can be installed on the following server platforms:

• Paper/Purpur: For standalone servers. Versions 1.13 - 1.21.10 are supported.
• Velocity: Proxy server, 3.4.0-SNAPSHOT and later are supported.
• BungeeCord/Waterfall: Proxy server, latest versions are supported.

Sources: README.md:43-45, CHANGELOG.md:27-30

Platform-Specific Requirements

Paper Server Setup

When running NexAuth on a Paper server (or its forks), the following conditions must be met:

1. Offline Mode: The server must be running in offline-mode. The plugin will detect if online-mode is enabled and will refuse to start.
2. No Proxy: The server must not be configured to run under a proxy (i.e., bungeecord setting in spigot.yml and velocity-support in paper.yml must be false). If you intend to use a proxy, NexAuth must be installed on the proxy itself, not the backend server.
3. Adventure-Compatible: The server must be an Adventure-compatible distribution (e.g., Paper). The plugin explicitly checks for this and will shut down the server if it detects an unsupported type like Spigot.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperNexAuth.java:101-112, Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java:40-46

Dependencies

While NexAuth can run standalone, certain features require additional plugins. These are defined as soft dependencies.

Dependency	Feature	Platforms	Required?
NexLimbo	Secure authentication limbo for unauthenticated players.	Velocity, BungeeCord	Recommended
Protocolize	Enables TOTP 2FA functionality (QR code maps).	Velocity, BungeeCord	Optional
Floodgate	Enables Geyser (Bedrock) support.	All	Optional
LuckPerms	Provides a permission context for authentication status.	All	Optional
RedisBungee	Enables multi-proxy support.	BungeeCord, Velocity	Optional

Sources: README.md:29, Plugin/src/main/resources/bungee.yml:6-11, Plugin/src/main/resources/paper-plugin.yml:7-18, Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityBootstrap.java:31-36

2. Installation Process

The installation process involves downloading the plugin, placing it in the correct directory, and performing an initial startup to generate configuration files.

General Steps

1. Download the NexAuth.jar file from the official GitHub Releases.
2. Place the downloaded JAR file into the /plugins directory of your Paper, Velocity, or BungeeCord server.
3. If using a proxy, download and install NexLimbo in the proxy's /plugins directory.
4. Start the server. NexAuth will generate its data folder (/plugins/NexAuth/) containing config.yml and messages.yml.
5. Stop the server to perform the initial configuration as described in the next section.

Sources: CHANGELOGS.md:46-51, README.md:36-41

Platform-Specific Bootstrap Flow

NexAuth uses a different bootstrap class for each platform, which handles loading dependencies and initializing the plugin.

The diagram below illustrates the initial loading sequence for the Paper platform.

This diagram shows the startup process for NexAuth on a Paper server, including compatibility checks that prevent it from running on unsupported platforms.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java:34-71

3. Initial Configuration

After the first run, you must configure NexAuth before it can be used.

Database Configuration

NexAuth requires a database to store user data. It supports SQLite, MySQL, and PostgreSQL.

1. Open plugins/NexAuth/config.yml.
2. Locate the database section.
3. Set the type to your desired database.

Here are the available built-in database types:

database.type	Description
nexauth-sqlite	Default. Uses a local SQLite file.
nexauth-mysql	Uses an external MySQL/MariaDB server.
nexauth-postgresql	Uses an external PostgreSQL server.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:169-176

If you choose MySQL or PostgreSQL, you must fill in the connection details in the corresponding section within config.yml.

Server Configuration (Limbo & Lobby)

You must define at least one "limbo" server/world for unauthenticated players and one "lobby" server/world for authenticated players.

• limbo: A list of server names (on proxy) or world names (on Paper) where players are sent before they log in.
• lobby: A map of servers/worlds where players are sent after successful authentication. The root key is used for players who did not connect via a forced host.

Example config.yml snippet:

# On a Proxy (Velocity/BungeeCord)
limbo:
  - "auth-server-1"
lobby:
  root:
    - "lobby-1"
    - "lobby-2"

# On Paper
limbo:
  - "limbo_world"
lobby:
  root:
    - "world"

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:45-70, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:271-280

4. Database Migration (Optional)

If you are switching from another authentication plugin, NexAuth provides a utility to migrate your existing user data.

The migration process is controlled via the migration section in config.yml.

Migration Flow

The following diagram shows the steps NexAuth takes when migration is enabled.

This flow is triggered on startup if migration.on-next-startup is set to true.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:70-125

How to Migrate

1. Stop your server.
2. In config.yml, set migration.on-next-startup: true.
3. Set migration.type to the correct value for your old plugin (e.g., authme-mysql, nlogin-sqlite).
4. Configure the connection details for your old database under the migration.old-database section.
5. Ensure your new NexAuth database is correctly configured under the database section.
6. Start the server. NexAuth will perform the migration.
7. After a successful migration, the plugin will continue its startup. It is recommended to set migration.on-next-startup back to false to prevent it from running again.

A list of available migration types can be found in the configuration file's comments.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:185-231

5. Verifying the Installation

After starting the server with your configuration:

1. Check the Console: Look for the message NexAuth version <version> enabled!. This indicates a successful startup.
2. Review for Errors: Scan the console for any [NexAuth] error messages, particularly related to:
   • Database connection failures.
   • Corrupted configuration files.
   • Unsupported server environments (e.g., running on Spigot, or in online-mode on Paper).
3. Join the Server: Attempt to connect to your server as a new player. You should be placed in one of the configured limbo locations and prompted to register.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java:146, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:300-329