Migrating from Other Auth Plugins

Relevant source files

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

• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/MigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/AuthMeSQLMigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/FastLoginSQLMigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/LoginSecuritySQLMigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.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/common/migrate/AegisSQLMigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/AuthySQLMigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/UniqueCodeAuthSQLMigrateReadProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/LogItSQLMigrateReadProvider.java

NexAuth includes a powerful and flexible migration system to import user data from a variety of other Minecraft authentication plugins. This feature simplifies the transition to NexAuth by preserving existing user accounts, passwords, and other relevant data. The entire process is configured within the config.yml file and is executed on server startup.

The system is designed to connect to the old plugin's database, read all user entries, convert password hashes to a compatible format, and insert the data into the NexAuth database. This ensures a seamless experience for players, who can log in with their old credentials after the migration is complete.

Configuration

To initiate a database migration, you must configure the migration section in config.yml. The migration will only run once, on the next startup after being enabled.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:162-170, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:71-72

Key Configuration Options

Key	Type	Default	Description
migration.on-next-startup	Boolean	false	Set to true to enable the migration process on the next server start.
migration.type	String	authme-sqlite	Specifies the source plugin and database type to migrate from. See the table below for all available types.
migration.old-database.mysql.table	String	user-data	The table name of the old MySQL database.
migration.old-database.postgresql.table	String	user-data	The table name of the old PostgreSQL database.
migration.old-database.*	Object	-	This section contains connection details (host, port, user, password, etc.) for the old database, mirroring the structure of the main database.properties section.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:172-232, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:93-95

Supported Migration Types

The migration.type option determines which data provider will be used. The following types are supported:

Migration Type	Description
jpremium-mysql	Converts from MySQL JPremium (SHA256, SHA512, BCrypt).
authme-mysql	Converts from MySQL AuthMe (BCrypt, SHA256).
authme-sqlite	Converts from SQLite AuthMe (BCrypt, SHA256).
authme-postgresql	Converts from PostgreSQL AuthMe (BCrypt, SHA256).
aegis-mysql	Converts from MySQL Aegis (BCrypt).
dba-mysql	Converts from MySQL DynamicBungeeAuth (SHA-512).
nlogin-sqlite	Converts from SQLite NLogin (SHA512).
nlogin-mysql	Converts from MySQL NLogin (SHA512).
loginsecurity-mysql	Converts from MySQL LoginSecurity (BCrypt).
loginsecurity-sqlite	Converts from SQLite LoginSecurity (BCrypt).
fastlogin-sqlite	Converts from SQLite FastLogin. Requires a prior conversion from AuthMe.
fastlogin-mysql	Converts from MySQL FastLogin. Requires a prior conversion from AuthMe.
limboauth-mysql	Converts from MySQL LimboAuth (BCrypt, SHA256).
authy-mysql	Converts from MySQL Authy (SHA256).
authy-sqlite	Converts from SQLite Authy (SHA256).
logit-mysql	Converts from MySQL LogIt (SHA256).
nexauth-mysql	Converts from another NexAuth MySQL database. Useful for database backend changes.
nexauth-sqlite	Converts from another NexAuth SQLite database. Useful for database backend changes.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:178-220

Migration Process Flow

The migration process is orchestrated by the checkAndMigrate method in GeneralUtil and executed within AuthenticNexAuth. It follows a clear, sequential flow to ensure data is transferred safely.

The diagram below illustrates the high-level migration workflow.

Architecture

The migration system is built upon a set of specialized provider classes. The core component is the MigrateReadProvider, an abstract class that all specific migration providers extend. This ensures a consistent interface for the main plugin to interact with, regardless of the source plugin.

This diagram shows the class hierarchy for migration providers. MigrateReadProvider implements ReadDatabaseProvider and is the base for all migration-specific logic.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/MigrateReadProvider.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/AuthMeSQLMigrateReadProvider.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/LoginSecuritySQLMigrateReadProvider.java

Supported Plugin Details

Each supported plugin has a dedicated MigrateReadProvider implementation that handles the specifics of its database schema and password hashing.

AuthMe

• Provider Class: AuthMeSQLMigrateReadProvider
• Data Migrated: realname, password, lastlogin, regdate.
• Password Handling:
  • Detects SHA-256 hashes (prefixed with $SHA$) and extracts the hash and salt.
  • Detects BCrypt hashes (prefixed with $2a$) and converts them to NexAuth's HashedPassword format.
  • Logs an error if an unknown hash format is encountered for a user.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/AuthMeSQLMigrateReadProvider.java:34-62

LoginSecurity

• Provider Class: LoginSecuritySQLMigrateReadProvider
• Data Migrated: unique_user_id, last_name, last_login, registration_date, password.
• Password Handling:
  • Only supports BCrypt hashes, identified by hashing_algorithm column value 7.
  • Logs a warning and skips users with any other hashing algorithm.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/LoginSecuritySQLMigrateReadProvider.java:34-51

FastLogin

• Provider Class: FastLoginSQLMigrateReadProvider
• Data Migrated: This provider does not migrate user accounts directly. Instead, it reads premium player UUIDs from the FastLogin database.
• Special Requirement: The configuration explicitly states that a migration from AuthMe must be performed first. This provider's purpose is to link existing cracked accounts (migrated from AuthMe) with their premium UUIDs if they are registered in FastLogin.
• Logic: It iterates through all users in the NexAuth database, checks if a premium entry exists for them in the FastLogin database, and if so, updates the premiumUUID field for that user in NexAuth.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/FastLoginSQLMigrateReadProvider.java:31-59, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:205-206

Aegis

• Provider Class: AegisSQLMigrateReadProvider
• Data Migrated: uuid, onlineId (as premium UUID), name, password.
• Password Handling:
  • Supports BCrypt hashes (prefixed with $2a$).
  • Handles cases where the password field is empty or null.
• Data Quirks: The provider cleans up UUIDs stored with extraneous dots (.).

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/AegisSQLMigrateReadProvider.java:31-58

UniqueCodeAuth

• Provider Class: UniqueCodeAuthSQLMigrateReadProvider
• Data Migrated: name, password, premium status.
• Password Handling:
  • This plugin stores passwords in plain text.
  • The provider reads the plain text password and hashes it using NexAuth's default crypto provider.
  • It handles a special case where the password "n" is treated as null.
• Premium Players: If a user is marked as premium, it attempts to fetch their premium UUID from Mojang's API.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/UniqueCodeAuthSQLMigrateReadProvider.java:34-79

Authy

• Provider Class: AuthySQLMigrateReadProvider
• Data Migrated: uuid, username, ip, password.
• Password Handling:
  • Assumes all passwords are a direct SHA-256 hash with no salt.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/AuthySQLMigrateReadProvider.java:31-52

LogIt

• Provider Class: LogItSQLMigrateReadProvider
• Data Migrated: uuid, username, password, salt, hashing_algorithm, ip, email.
• Password Handling:
  • Supports a custom salted SHA-256 implementation identified by the algorithm sha-256.
  • Uses a custom LOGIT-SHA-256 crypto provider within NexAuth to correctly validate these hashes post-migration.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/migrate/LogItSQLMigrateReadProvider.java:34-67, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:279