Proxy-Specific Features (Velocity/BungeeCord)
Relevant source files
The following files were used as context for generating this wiki page:
- Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordListener.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityListeners.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/server/AuthenticServerHandler.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordNexAuth.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordPlatformHandle.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityPlatformHandle.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
NexAuth provides robust authentication services for Minecraft networks by integrating directly with proxy servers like Velocity and BungeeCord. This integration allows NexAuth to intercept player connections before they reach a game server, enforce authentication, and manage player transitions between a secure "limbo" state and the main lobby servers. The system is designed to be platform-agnostic where possible, using a common core logic, but relies on specific implementations for each proxy to handle events, player interactions, and server management.
The proxy implementations are responsible for bootstrapping the plugin, listening to platform-specific connection events, and translating abstract actions (like moving a player) into concrete API calls for that proxy. This architecture ensures that unauthenticated players are isolated in a controlled environment, typically provided by the recommended NexLimbo plugin, until they successfully log in or register.
Core Architecture
NexAuth's proxy support is built around a central AuthenticNexAuth class, which is extended by platform-specific classes: BungeeCordNexAuth and VelocityNexAuth. These classes handle the plugin lifecycle (enable/disable), dependency detection, and providing platform-specific implementations for core services.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordNexAuth.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java
Platform Handle Abstraction
A key component of this design is the PlatformHandle interface, which abstracts all direct interactions with the proxy's API. BungeeCordPlatformHandle and VelocityPlatformHandle implement this interface, providing concrete logic for actions like kicking a player, moving a player to a server, and retrieving server information.
The diagram below shows the class relationships between the core AuthenticNexAuth class and its proxy-specific implementations.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordPlatformHandle.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityPlatformHandle.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordNexAuth.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java
Dependency Integration
NexAuth detects and integrates with several optional plugins to enhance its functionality on proxies.
| Plugin | Feature | Detection Method |
|---|---|---|
| NexLimbo | Provides the secure authentication environment. | pluginPresent("NexLimboBungee") or pluginPresent("nexlimbovelocity") |
| RedisBungee | Enables multi-proxy support for player presence checks. | pluginPresent("RedisBungee") or pluginPresent("redisbungee") |
| Protocolize | Enables QR code map display for 2FA. | pluginPresent("Protocolize") or pluginPresent("protocolize") |
| Floodgate | Enables support for Bedrock players. | pluginPresent("floodgate") |
The getLimboIntegration() method in both BungeeCordNexAuth and VelocityNexAuth is responsible for initializing the integration with NexLimbo if it's detected.
// VelocityNexAuth.java
@Nullable
@Override
public LimboIntegration<RegisteredServer> getLimboIntegration() {
if (pluginPresent("nexlimbovelocity") && limboIntegration == null) {
limboIntegration = new VelocityNanoLimboIntegration(server,
getConfiguration().get(ConfigurationKeys.LIMBO_PORT_RANGE));
}
return limboIntegration;
}
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java:230-237, Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordNexAuth.java:199-205
Player Connection Flow
NexAuth intercepts the player connection process at multiple stages to perform checks, modify connection properties, and direct the player to the appropriate server (limbo or lobby).
BungeeCord Connection Flow
The following sequence diagram illustrates the key events and actions during a player's connection on a BungeeCord proxy.
This flow shows how BungeeCordListener uses PreLoginEvent to determine the online mode, LoginEvent to inject the correct player UUID from the database, and ServerConnectEvent to route the player to a limbo server.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordListener.java:51-97
Velocity Connection Flow
The process on Velocity is similar, but uses Velocity-specific events.
On Velocity, VelocityListeners uses PreLoginEvent to set the online mode, LoginEvent to modify the player's GameProfile with the correct UUID, and ServerPreConnectEvent to perform the initial redirection to a limbo server.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityListeners.java
Server Management
Server management is handled by AuthenticServerHandler, which is responsible for selecting appropriate limbo and lobby servers based on the plugin's configuration.
Configuration
The following configuration keys in config.yml are crucial for server management on proxies.
| Key | Type | Default | Description |
|---|---|---|---|
limbo | List<String> | ["limbo0", "limbo1"] | A list of server names to be used as authentication servers. |
lobby | Map<String, List<String>> | root: ["lobby0", "lobby1"] | A map of forced hosts to lobby server lists. The root key is for default connections. |
ping-servers | Boolean | false | If true, NexAuth will ping servers to check their online status and player count before selection. |
ignore-max-players-from-backend-ping | Boolean | false | If true, ignores the max player count from a server ping, useful for misconfigured servers. |
fallback | Boolean | false | If a player is kicked from a server, setting this to true will attempt to move them to a lobby instead of disconnecting them. |
Server Selection Logic
When a player needs to be sent to a limbo or lobby, AuthenticServerHandler uses a round-robin approach to select an available server from the configured list. If ping-servers is enabled, it will only select from servers that are online and not full.
This flowchart illustrates the server selection process.
Fallback Mechanism
On BungeeCord, if a player is kicked from a server and the fallback option is enabled, BungeeCordListener intercepts the ServerKickEvent. It then attempts to find an available lobby server via chooseLobbyServer and redirects the player there, preventing a full disconnect from the proxy.
// BungeeCordListener.java
@EventHandler(priority = LOW)
public void onKick(ServerKickEvent event) {
// ...
if (event.getState() == ServerKickEvent.State.CONNECTED) {
if (!plugin.getConfiguration().get(ConfigurationKeys.FALLBACK)) {
// ... disconnect player
} else {
try {
var server = plugin.getServerHandler().chooseLobbyServer(...);
// ...
event.setCancelled(true);
event.setCancelServer(server);
} catch (NoSuchElementException | EventCancelledException e) {
// ... disconnect player if no lobby is found
}
}
}
// ...
}
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordListener.java:101-124
Summary
NexAuth's proxy-specific features are essential for its function as an authentication plugin. By leveraging the event systems of BungeeCord and Velocity, it creates a secure boundary between unauthenticated players and the main network. The use of a platform abstraction layer (PlatformHandle) and a common server handling logic (AuthenticServerHandler) allows for maintainable and consistent behavior across different proxy software, while integrations with plugins like NexLimbo and RedisBungee provide a complete and scalable authentication solution.