FusionAuth has a specific package naming requirement for plugins: the @PluginModule class 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 ProcessCreate the plugins directory in your FusionAuth installation (peer to the bin and config directories):
Linux/macOS: /usr/local/fusionauth/plugins Windows: \fusionauth\pluginsPlace 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 InstallationYou 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 fieldIf your custom schemes appear in this dropdown, the plugin has been successfully installed.
Updating a PluginWhen 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 logsNote: 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 encryptionScheme associated with their account, FusionAuth will not be able to validate their password.
Plugin Persistence Through UpgradesPlugins 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 NoteFusionAuth 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