Creating custom login modules in JBoss EAP

Solution Verified - Updated -

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 6
    • 7
  • Custom PicketBox / Legacy Security login module

Issue

  • Developing a custom login module
  • Getting classpath or ClassNotFoundException issues
  • Defining dependencies

Resolution

Disclaimer: Links contained herein to external website(s) are provided for convenience only. Red Hat has not reviewed the links and is not responsible for the content or its availability. The inclusion of any link to an external website does not imply endorsement by Red Hat of the website or their entities, products or services. You agree that Red Hat is not responsible or liable for any loss or expenses that may result due to your use of (or reliance on) the external site or content.

  1. Developing a custom login module is fully covered in the Development Guide of Red Hat JBoss Enterprise Application Platform 6.4: #18.3.2. Custom Modules for EAP 6.4 and Login Module Reference for EAP 7.

    Once this is done, the rest of the steps will assume the login module has the class org.jboss.example.CustomLoginModule and is packaged in jar named example-custom-principal.jar.

  2. Add the custom login module as a JBoss EAP module.

    module add --name=org.jboss.example --resources=/path/to/example-custom-principal.jar --dependencies=javax.api,javax.persistence.api,javax.resource.api,javax.security.auth.message.api,javax.security.jacc.api,javax.servlet.api,javax.transaction.api,javax.xml.bind.api,javax.xml.stream.api,org.jboss.logging,org.infinispan,org.picketbox

    This will create a module in $JBOSS_HOME/modules/org/jboss/example/main with a module.xml file like this:

    <?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.jboss.example">
    <resources>
    <resource-root path="example-custom-principal.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.persistence.api"/>
        <module name="javax.resource.api"/>
        <module name="javax.security.auth.message.api"/>
        <module name="javax.security.jacc.api"/>
        <module name="javax.servlet.api"/>
        <module name="javax.transaction.api"/>
        <module name="javax.xml.bind.api"/>
        <module name="javax.xml.stream.api"/>
        <module name="org.jboss.logging"/>
        <module name="org.infinispan"/>
        <module name="org.picketbox"/>
    </dependencies>
</module>

    And copy in the example-custom-principal.jar.

    The dependencies are defined as other JBoss EAP modules that the code requires. These must be defined or the module class loader will be able to find the dependencies.

  3. Configure the security domain to use the custom login module. Using bin/jboss.cli.sh run:

    /subsystem=security/security-domain=custom-security-realm:add
/subsystem=security/security-domain=custom-security-realm/authentication=classic:add(login-modules=[{"code" => "org.jboss.example.CustomLoginModule", "flag" => "required"}])

    Which makes the following change:

    <subsystem xmlns="urn:jboss:domain:security:1.1">
    <security-domains>
    <security-domain name="custom-security-realm" cache-type="default">
        <authentication>
        <!-- FIXME: notice the 'module' attribute -->
        <login-module module="org.jboss.example" code="org.jboss.example.CustomLoginModule" flag="required"/>
        </authentication>
    </security-domain>
    </security-domains>
</subsystem>

Root Cause

PicketBox login modules will still work with any release JBoss EAP 7, but they are considered Legacy Security and are being phased-out in favor of Elytron Security.

For any new development, Red Hat recommends Creating a Custom Elytron Realm.

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.

Comments