How to install a custom password hashing plugin and ensure correct package naming?
-
I've developed a custom password hashing plugin for FusionAuth that implements several legacy password schemes. However, I've encountered an issue with plugin installation:
Initial Problem:
The plugin JAR (version 1.0.0) was not being loaded by FusionAuth. The Guice module was in the packageau.com.company.fusionauth.productbut FusionAuth didn't install it and provided no error message.Plugin Details:
- Custom password encryptor plugin
- Registers three custom password schemes
- Built against fusionauth-plugin-api 1.16.0
- Compiled for Java 17
- Running on FusionAuth 1.70.0 (which uses Java 25)
Questions:
- What are the package naming requirements for FusionAuth plugins?
- How can I confirm that a plugin has loaded successfully?
- What's the proper procedure for updating/replacing a plugin version?
- Will plugins persist through FusionAuth version upgrades?
-
Package Naming Requirement
FusionAuth has a specific package naming requirement for plugins: the
@PluginModuleclass must be in a package that has a parent package named "plugin" or "plugins".For example:
au.com.company.fusionauth.plugins.product.MyPluginModule
au.com.company.fusionauth.plugin.product.MyPluginModule
au.com.company.fusionauth.product.MyPluginModule(will be skipped silently)
If the package structure doesn't follow this convention, FusionAuth will skip the plugin JAR without displaying an error.
Installation Process
-
Create the plugins directory in your FusionAuth installation (peer to the
binandconfigdirectories):- Linux/macOS:
/usr/local/fusionauth/plugins - Windows:
\fusionauth\plugins
- Linux/macOS:
-
Place the plugin JAR file in the FusionAuth plugins directory
-
Restart FusionAuth (this will cause 1-2 minutes of downtime)
-
Check the startup logs for confirmation messages:
INFO io.fusionauth.api.plugin.guice.PluginModule - Installing plugin [au.com.company.fusionauth.plugins.product.MyPluginModule] INFO io.fusionauth.api.plugin.guice.PluginModule - Plugin successfully installed
Confirming Plugin Installation
You can verify that your custom password hashing plugin loaded successfully through the Admin UI:
- Navigate to Tenants → [Your Tenant] → Password
- Scroll to Cryptographic hash settings
- Look for your custom scheme(s) in the Scheme dropdown field
If your custom schemes appear in this dropdown, the plugin has been successfully installed.
Updating a Plugin
When replacing a plugin version:
- Remove the old JAR file from the plugins directory (don't leave multiple versions installed if they register the same scheme names)
- Install the new JAR file
- Restart FusionAuth
- Verify the new version loaded via the startup logs
Note: You should never delete an installed password hashing plugin unless you are certain that no users are using the hash provided by that plugin. If any users still have that
encryptionSchemeassociated with their account, FusionAuth will not be able to validate their password.Plugin Persistence Through Upgrades
Plugins should generally persist through FusionAuth version upgrades. However, since FusionAuth bundles its own Java runtime and that runtime version can change between major FusionAuth versions, you may need to rebuild your plugin for compatibility with newer Java versions. It's advisable to test plugin compatibility when planning FusionAuth upgrades.
Java Compatibility Note
FusionAuth ships with its own bundled Java runtime. The version depends on your FusionAuth version. For example, FusionAuth 1.70.0 uses Java 25. If your plugin is compiled for Java 17, it should be compatible with Java 25 (forward compatibility), but always test in your environment to confirm.
Related Documentation
- Writing a Plugin - Install the Plugin - Detailed installation instructions and directory structure
- Writing a Plugin - Create the Guice Binding - Package naming requirements for plugins
- Custom Password Hashing - Overview of custom password hashing plugins
- Troubleshooting Custom Password Hashing Plugins - Common issues and verification steps
- Custom Password Hashing - Deleting Plugins - Important considerations when removing plugins
- Password Hashing Plugins Overview - General information about FusionAuth's plugin mechanism
- Example Password Encryptor Plugin - Sample plugin project on GitHub
-
D dan has marked this topic as solved