FusionAuth
    • Home
    • Categories
    • Recent
    • Popular
    • Pricing
    • Contact us
    • Docs
    • Login

    How to install a custom password hashing plugin and ensure correct package naming?

    Scheduled Pinned Locked Moved Solved
    Frequently Asked Questions (FAQ)
    plugin password hashing installation configuration
    1
    2
    5
    Loading More Posts
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes
    Reply
    • Reply as topic
    Log in to reply
    This topic has been deleted. Only users with topic management privileges can see it.
    • F
      FASupportBot
      last edited by

      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 package au.com.company.fusionauth.product but 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:

      1. What are the package naming requirements for FusionAuth plugins?
      2. How can I confirm that a plugin has loaded successfully?
      3. What's the proper procedure for updating/replacing a plugin version?
      4. Will plugins persist through FusionAuth version upgrades?

      If you are looking for professional support and not just bot-provided support, please check out https://fusionauth.io/pricing and pick a plan that fits your needs.

      1 Reply Last reply Reply Quote 0
      • F
        FASupportBot
        last edited by

        Package Naming Requirement

        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 Process

        1. Create the plugins directory in your FusionAuth installation (peer to the bin and config directories):

          • Linux/macOS: /usr/local/fusionauth/plugins
          • Windows: \fusionauth\plugins
        2. Place the plugin JAR file in the FusionAuth plugins directory

        3. Restart FusionAuth (this will cause 1-2 minutes of downtime)

        4. 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:

        1. Navigate to Tenants → [Your Tenant] → Password
        2. Scroll to Cryptographic hash settings
        3. 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:

        1. Remove the old JAR file from the plugins directory (don't leave multiple versions installed if they register the same scheme names)
        2. Install the new JAR file
        3. Restart FusionAuth
        4. 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 encryptionScheme associated 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

        If you are looking for professional support and not just bot-provided support, please check out https://fusionauth.io/pricing and pick a plan that fits your needs.

        1 Reply Last reply Reply Quote 0
        • danD dan has marked this topic as solved
        • First post
          Last post