Main Configuration (config.conf)
Relevant source files
The following files were used as context for generating this wiki page:- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateHelper.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/staff/NexAuthCommand.java
The config.conf file is the primary configuration file for the NexAuth plugin. It uses the HOCON (Human-Optimized Config Object Notation) format, which is a superset of JSON. This file controls all major aspects of the plugin's behavior, including security settings, database connections, server management, authentication flow, and integrations with other systems like 2FA and email.
The configuration is loaded and managed by the HoconPluginConfiguration class, which utilizes the Configurate library to parse the file, apply default values, and handle version migrations. All available configuration options are defined as static final fields in the ConfigurationKeys class, providing a centralized and type-safe way to access settings throughout the plugin. For more information on specific features, you may refer to other wiki pages like 2FA or Database Migration.
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java:18-24, 40-62](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java#L18-L24), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java)
Configuration Loading Process
The loading of config.conf is a multi-step process designed to be robust, handle defaults, and automatically migrate older configurations to the latest version. The process is initiated by the HoconPluginConfiguration.reload() method.
The diagram below illustrates the flow of loading the configuration file.
This diagram shows the configuration loading and migration flow.
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java:40-62](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java#L40-L62), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java:29-81](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java#L29-L81)
The main classes involved in this process and their relationships are shown below.
This diagram shows the class relationships for the configuration system.
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateHelper.java](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateHelper.java), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java)
Configuration Keys
All configuration keys are defined in ConfigurationKeys.java. They are grouped below by functionality.
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java)
General & Security
These settings control core security policies and general plugin behavior.
| Key | Type | Default | Description |
|---|---|---|---|
default-crypto-provider | String | BCrypt-2A | The default password hashing algorithm. Options: SHA-256, SHA-512, BCrypt-2A, Argon-2ID. |
profile-conflict-resolution-strategy | String | BLOCK | How to handle when a premium and cracked player have the same name. Options: BLOCK, USE_OFFLINE, OVERWRITE. |
new-uuid-creator | String | CRACKED | Method for generating UUIDs for new offline players. Options: RANDOM, CRACKED, MOJANG. |
minimum-password-length | Integer | -1 | Minimum password length. Negative values disable the check. |
minimum-username-length | Integer | -1 | Minimum username length for new players. Zero or lower disables the check. |
max-login-attempts | Integer | -1 | Number of incorrect password attempts before kicking. -1 disables it. |
milliseconds-to-refresh-login-attempts | Integer | 10000 | Time in ms after which login attempts are reset. |
ip-limit | Integer | -1 | Max accounts per IP address. Not recommended. Zero or less disables it. |
hide-player-inventory | Boolean | true | Hides player inventory at the packet level until authenticated. |
allow-proxy-connections | Boolean | true | (Paper only) Verifies player's IP against Mojang's authentication IP. |
debug | Boolean | false | Enables detailed debug messages in the console. |
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:80-168, 228-249, 303-310, 362-369](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L80-L168)
Server & Connection Management
These keys define how players are moved between servers (on a proxy) or worlds (on Paper).
| Key | Type | Default | Description |
|---|---|---|---|
limbo | List | ["limbo0", "limbo1"] | List of authentication servers/worlds. Must be registered in proxy config or exist as worlds on Paper. |
lobby | Map<String, List> | {"root": ["lobby0", "lobby1"]} | Servers/worlds to send authenticated players to. Supports forced hosts. |
ignore-max-players-from-backend-ping | Boolean | false | If true, ignores the max player count when selecting a lobby/limbo, preventing issues with incorrect ping data. |
ping-servers | Boolean | false | (Proxy only) Pings servers to check online status and player count. |
remember-last-server | Boolean | false | Remembers the last server a player was on and sends them back after login. |
fallback | Boolean | false | (Proxy only) If true, players are sent to a lobby if their current server shuts down. If false, they are kicked. |
limbo-port-range | String | 30000-40000 | (Proxy only, with NexLimbo) Port range for limbo servers to bind to. |
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:31-77, 312-330, 371-376](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L31-L77)
Authentication Flow
Settings that control the user experience during the login and registration process.
| Key | Type | Default | Description |
|---|---|---|---|
allowed-commands-while-unauthorized | List | ["login", "register", ...] | Commands a player can use before being authenticated. |
use-titles | Boolean | true | Shows titles (e.g., "Register", "Login") to unauthenticated players. |
use-action-bar | Boolean | false | Shows action bar messages to unauthenticated players. |
auto-register | Boolean | false | Automatically register players with a premium (paid) Minecraft account. Cracked players cannot register premium names if this is true. |
milliseconds-to-refresh-notification | Integer | 10000 | How often to resend login/register prompts (chat, titles) to an unauthenticated player. Negative values disable it. |
seconds-to-authorize | Integer | -1 | Time limit in seconds for a player to log in or register. Negative values disable it. |
session-timeout | Long | 0 | Time in seconds for a player's session to be valid, allowing auto-login. Zero or less disables sessions. |
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:19-30, 137-148, 170-198, 251-256, 303-310](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L19-L30)
Database
Configures the primary database connection for storing user data.
| Key | Type | Default | Description |
|---|---|---|---|
database.type | String | nexauth-sqlite | The type of database to use. Built-in options: nexauth-mysql, nexauth-postgresql, nexauth-sqlite. |
Note: Specific connection properties (host, port, user, password, etc.) are configured under database.properties.mysql, database.properties.postgresql, or database.properties.sqlite depending on the selected type. These properties are loaded dynamically based on the registered DatabaseConnector.
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:200-213](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L200-L213), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:400-404](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java#L400-L404)
Database Migration
These settings are used to import data from other authentication plugins.
| Key | Type | Default | Description |
|---|---|---|---|
migration.on-next-startup | Boolean | false | If set to true, the plugin will attempt to migrate data from another database on the next server start. |
migration.type | String | authme-sqlite | The source of the migration. Many types are supported, such as authme-mysql, jpremium-mysql, nlogin-sqlite, etc. |
migration.old-database.mysql.table | String | user-data | The table name for the old database if the migration source is MySQL. |
migration.old-database.postgresql.table | String | user-data | The table name for the old database if the migration source is PostgreSQL. |
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:215-281](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L215-L281), [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:61-63](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java#L61-L63)
Two-Factor Authentication (TOTP)
Configures Time-based One-Time Password (TOTP) functionality, compatible with apps like Google Authenticator.
| Key | Type | Default | Description |
|---|---|---|---|
totp.enabled | Boolean | true | Enables or disables the 2FA feature. |
totp.label | String | NexAuth Network | The label displayed in the authenticator app. Should be set to your server/network name. |
totp.delay | Integer | 1000 | Delay in milliseconds before the QR code map is given to the player. |
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:283-301, 332-337](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L283-L301)
Email (Password Recovery)
Configures an SMTP server to allow players to recover their passwords via email.
| Key | Type | Default | Description |
|---|---|---|---|
mail.enabled | Boolean | false | Enables or disables the email password recovery feature. |
mail.host | String | smtp.gmail.com | The SMTP server host. |
mail.port | Integer | 587 | The SMTP server port. |
mail.username | String | username | The username for the SMTP account. |
mail.password | String | password | The password for the SMTP account. |
mail.sender | String | NexAuth Network | The sender name displayed in the email. |
mail.email | String | email@something.com | The "From" email address. |
Sources: [Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:339-360](https://github.com/XreatLabs/NexAuth/blob/HEAD/Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java#L339-L360)
Conclusion
The config.conf file is a powerful tool for tailoring NexAuth to the specific needs of any server or network. Its comprehensive set of options allows for fine-grained control over security, player experience, and data management. Proper configuration is essential for ensuring a secure and seamless authentication system. The use of HOCON, combined with a robust loading and migration system, makes it both flexible for administrators and maintainable for developers.