API: Custom Providers

Relevant source files

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

• API/src/main/java/xyz/xreatlabs/nexauth/api/crypto/CryptoProvider.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/authorization/AuthorizationProvider.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/database/ReadDatabaseProviderRegistration.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java

NexAuth features a flexible API that allows developers to extend and customize core functionalities by implementing and registering their own providers. This system is primarily designed for adding new password hashing algorithms and integrating different database systems, including tools for data migration from other authentication plugins. The main plugin interface, NexAuthPlugin, exposes methods to register these custom implementations, which are then managed by the core plugin logic.

This modular architecture enables developers to tailor NexAuth to specific needs, such as supporting a legacy password format or migrating user data from an unsupported plugin. The core plugin, AuthenticNexAuth, handles the lifecycle of these providers, from registration during startup to their utilization in the authentication and data management flows.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java

Crypto Providers

Crypto providers are responsible for hashing and verifying user passwords. By implementing the CryptoProvider interface, you can add support for any hashing algorithm. NexAuth includes several built-in providers like BCrypt-2A, Argon-2ID, SHA-256, and SHA-512.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:240-244, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:70-76

The CryptoProvider Interface

Any custom crypto provider must implement the CryptoProvider interface.

Method	Description
getIdentifier()	Returns a unique string ID for the provider (e.g., "BCrypt-2A"). This ID is used in the configuration file.
hash(String password)	Hashes a plain-text password and returns a HashedPassword object.
compare(String password, HashedPassword hash)	Compares a plain-text password against a HashedPassword object to verify correctness.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/crypto/CryptoProvider.java:16-39

Registration

Custom crypto providers are registered with the main plugin instance using the registerCryptoProvider method. This is typically done in your plugin's onEnable method.

// Method from NexAuthPlugin.java
void registerCryptoProvider(CryptoProvider provider);

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java:112-117

The following diagram illustrates the registration process.

The default provider is determined by the default-crypto-provider key in config.conf.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:70-76, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:1007-1009

Database Providers

NexAuth uses a provider model for all database interactions, making it possible to support different SQL and NoSQL databases, or to create migration tools from other authentication plugins. The system is composed of two main components: DatabaseConnector and ReadDatabaseProvider.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:400-403

Database Connectors

A DatabaseConnector is a low-level component responsible for establishing and managing the connection to a specific database type (e.g., MySQL, SQLite).

You can register a custom connector using registerDatabaseConnector. This method takes a factory function that creates an instance of your connector.

// Method from NexAuthPlugin.java
<E extends Exception, C extends DatabaseConnector<E, ?>> void registerDatabaseConnector(
    Class<?> clazz,
    ThrowableFunction<String, C, E> factory,
    String id
);

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java:119-127

The registration is stored in a DatabaseConnectorRegistration object internally.

Read/Write Database Providers

A ReadDatabaseProvider implements the logic to read user data. This is particularly useful for creating migration tools. If a provider also implements WriteDatabaseProvider, it can be used as the main database for NexAuth.

To register a provider, you create an instance of ReadDatabaseProviderRegistration and pass it to the registerReadProvider method.

// Method from NexAuthPlugin.java
void registerReadProvider(ReadDatabaseProviderRegistration<?, ?, ?> registration);

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java:105-110

The ReadDatabaseProviderRegistration record encapsulates the necessary information to create and use the provider.

Field	Type	Description
create	Function<C, T>	A factory function that takes a DatabaseConnector and returns an instance of the ReadDatabaseProvider.
id	String	A unique ID for the provider, used in config.conf (e.g., nexauth-mysql, authme-sqlite).
databaseConnector	Class<C>	The class of the DatabaseConnector required by this provider.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/database/ReadDatabaseProviderRegistration.java:15-26

Example: Registering a Migration Provider

The AuthenticNexAuth class registers numerous providers for migrating from other plugins like AuthMe, NLogin, and more. The registration for the authme-sqlite migration provider looks like this:

registerReadProvider(new ReadDatabaseProviderRegistration<>(
        connector -> new AuthMeSQLMigrateReadProvider("authme", logger, connector),
        "authme-sqlite",
        SQLiteDatabaseConnector.class
));

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:515-519

This registration tells NexAuth:

1. It is identified by the string authme-sqlite.
2. It requires a SQLiteDatabaseConnector.
3. When needed, it can be instantiated by creating a new AuthMeSQLMigrateReadProvider.

Built-in Database and Migration Providers

NexAuth comes with several built-in providers for its own use and for migration.

Provider ID	Database Type	Purpose
nexauth-mysql	MySQL	Default NexAuth provider
nexauth-postgresql	PostgreSQL	Default NexAuth provider
nexauth-sqlite	SQLite	Default NexAuth provider
aegis-mysql	MySQL	Migration from Aegis
authme-mysql	MySQL	Migration from AuthMe
authme-postgresql	PostgreSQL	Migration from AuthMe
authme-sqlite	SQLite	Migration from AuthMe
nlogin-sqlite	SQLite	Migration from NLogin
nlogin-mysql	MySQL	Migration from NLogin
fastlogin-mysql	MySQL	Migration from FastLogin
loginsecurity-mysql	MySQL	Migration from LoginSecurity
limboauth-mysql	MySQL	Migration from LimboAuth
authy-mysql	MySQL	Migration from Authy
logit-mysql	MySQL	Migration from LogIt

Sources: Plugin/src/main/java/xyzx/reatlabs/nexauth/common/AuthenticNexAuth.java:490-581

Conclusion

The provider-based API is a cornerstone of NexAuth's extensibility. It grants developers significant power to customize and integrate the plugin with other systems. By implementing CryptoProvider, developers can support virtually any password hashing scheme. Similarly, the ReadDatabaseProvider and DatabaseConnector system provides a robust framework for adding support for new data storage backends and, crucially, for building migration paths from a wide array of other authentication plugins. This design ensures that NexAuth can adapt to diverse server environments and legacy data formats.