The ejb-security-jaas quickstart demonstrates how legacy JAAS security domains can be used in conjunction with Elytron

What is it?

The ejb-security-jaas quickstart demonstrates how legacy JAAS-based security domains can be used in conjunction with WildFly Elytron to secure JEE applications. The secured EJB component can be accessed indirectly using a web application and it can also be directly invoked by a remote client. This quickstart shows how WildFly Application Server must be configured to support both scenarios using the legacy JAAS integration.

The following steps required to use the JAAS integration.

  1. Specify a JAAS security domain in the legacy security subsystem.

  2. Export an Elytron-compatible security realm that delegates to the legacy JAAS security domain.

  3. Create a security-domain in the elytron subsystem that uses the exported realm.

  4. Setup an http-authentication-factory in the elytron subsystem to handle the web requests.

  5. Setup a sasl-authentication-factory in the elytron subsystem to handle the requests made by remote clients.

  6. Add the application-security-domain mappings to both ejb3 and undertow subsystems to enable Elytron security for the EJB3 and web components.

System Requirements

The application this project produces is designed to be run on WildFly Application Server 12 or later.

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.

To run these quickstarts with the provided build scripts, you need the WildFly distribution ZIP. For information on how to install and run the WildFly server, see the Getting Started Guide for JBoss Enterprise Application Platform Continuous Delivery located on the Red Hat Customer Portal.

Use of WILDFLY_HOME

In the following instructions, replace WILDFLY_HOME with the actual path to your WildFly installation. The installation path is described in detail here: Use of WILDFLY_HOME and JBOSS_HOME Variables.

Create the Properties Files for the JAAS Security Domain

  1. Open a terminal and navigate to the WildFly server configuration directory:

    $ cd WILDFLY_HOME/standalone/configuration/
  2. Create a file named users.properties and add the following username/password pair.

    quickstartUser=quickstartPwd1!
  3. Create a file named roles.properties and add the following username/roles pair.

    quickstartUser=guest

This concludes the configuration required by the legacy JAAS login module used in this quickstart.

Back Up the WildFly Standalone Server Configuration

Before you begin, back up your server configuration file.

  1. If it is running, stop the WildFly server.

  2. Back up the WILDFLY_HOME/standalone/configuration/standalone.xml file.

After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.

Start the WildFly Standalone Server

  1. Open a terminal and navigate to the root of the WildFly directory.

  2. Start the WildFly server with the default profile by typing the following command.

    $ WILDFLY_HOME/bin/standalone.sh 
    Note
    For Windows, use the WILDFLY_HOME\bin\standalone.bat script.

Configure the Server

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-elytron-jaas.cli script provided in the root directory of this quickstart.

  1. Before you begin, make sure you do the following:

  2. Review the configure-elytron-jaas.cli file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands.

  3. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing WILDFLY_HOME with the path to your server.

    $ WILDFLY_HOME/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli
    Note
    For Windows, use the WILDFLY_HOME\bin\jboss-cli.bat script.

    You should see the following result when you run the script.

    The batch executed successfully
    process-state: reload-required
  4. Stop the WildFly server.

Review the Modified Server Configuration

After stopping the server, open the WILDFLY_HOME/standalone/configuration/standalone.xml file and review the changes.

  1. The following security-domain was added to the legacy security subsystem.

    <security-domain name="quickstart-domain" cache-type="default">
        <authentication>
            <login-module code="Remoting" flag="optional">
                <module-option name="password-stacking" value="useFirstPass"/>
            </login-module>
            <login-module code="UsersRoles" flag="required">
                <module-option name="usersProperties" value="${jboss.server.config.dir}/users.properties"/>
                <module-option name="rolesProperties" value="${jboss.server.config.dir}/roles.properties"/>
                <module-option name="password-stacking" value="useFirstPass"/>
            </login-module>
        </authentication>
        <mapping>
            <mapping-module code="SimpleRoles" type="role">
                <module-option name="quickstartUser" value="admin"/>
            </mapping-module>
        </mapping>
    </security-domain>

    The quickstart-domain is used to authenticate and authorize users. The Remoting login module is added to properly authenticate requests made from remote clients. A mapping-module is added that can be used to provide an extra role (admin). It is used later on to show how the legacy role mappers can be enabled and disabled.

  2. The following elytron-realm was added to the legacy security subsystem.

    <elytron-integration>
        <security-realms>
            <elytron-realm name="LegacyRealm" legacy-jaas-config="quickstart-domain" apply-role-mappers="false"/>
        </security-realms>
    </elytron-integration>

    This block tells the security subsystem to export an Elytron-compatible realm called LegacyRealm that will delegate authentication and authorization decisions to the legacy quickstart-domain. Setting the apply-role-mappers attribute to false indicates to the exported realm that it should not use any role mappers defined in the legacy security domain.

  3. The following security-domain was added to the elytron subsystem.

    <security-domain name="LegacyDomain" default-realm="LegacyRealm" permission-mapper="default-permission-mapper" security-event-listener="local-audit">
        <realm name="LegacyRealm"/>
    </security-domain>
  4. The following http-authentication-factory was added to the elytron subsystem.

    <http-authentication-factory name="quickstart-http-authentication" http-server-mechanism-factory="global" security-domain="LegacyDomain">
        <mechanism-configuration>
            <mechanism mechanism-name="BASIC">
                <mechanism-realm realm-name="Legacy Realm"/>
            </mechanism>
        </mechanism-configuration>
    </http-authentication-factory>

    It creates the HTTP authentication factory that will handle BASIC requests by delegating the security domain, which was created in the previous step.

  5. The following application-security-domain mapping was added to the undertow subsystem.

    <application-security-domains>
        <application-security-domain name="legacy-domain" http-authentication-factory="quickstart-http-authentication"/>
    </application-security-domains>

    It tells the undertow subsystem to use the HTTP authentication factory, which was created in the previous step, for web applications that specify the security domain legacy-domain in their metadata. The quickstart application specifies this domain both for the web layer, in the jboss-web.xml file, and the EJB component, using annotation in the code.

  6. The following sasl-authentication-factory was added to the elytron subsystem.

    <sasl-authentication-factory name="quickstart-sasl-authentication" sasl-server-factory="configured" security-domain="LegacyDomain">
        <mechanism-configuration>
            <mechanism mechanism-name="PLAIN"/>
        </mechanism-configuration>
    </sasl-authentication-factory>
  7. The http-remoting-connector in the remoting subsystem was updated to use the sasl-authentication-factory, which was created in the previous step.

    <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm" sasl-authentication-factory="quickstart-sasl-authentication"/>

    Authentication performed by the quickstart remote client is handled by this SASL authentication factory.

  8. Finally, the following application-security-domain mapping was added to the ejb3 subsystem.

    <application-security-domains>
        <application-security-domain name="legacy-domain" security-domain="LegacyDomain"/>
    </application-security-domains>

    This mapping basically enables Elytron security for EJB3 applications that specify the security domain legacy-domain in their metadata (either via jboss-ejb3.xml or annotations). The quickstart application uses the @SecurityDomain annotation in the bean class to specify this security domain.

Build and Deploy the Quickstart

  1. Make sure you start the WildFly server as described above.

  2. Open a terminal and navigate to the root directory of this quickstart.

  3. Type the following command to build the artifacts.

    $ mvn clean package wildfly:deploy

This deploys the ejb-security-jaas/target/ejb-security-jaas.war to the running instance of the server.

You should see a message in the server log indicating that the archive deployed successfully.

Access the Application

The application will be running at the following URL http://localhost:8080/ejb-security-jaas/.

When you access the application, you are presented with a browser login challenge.

  1. If you attempt to login with a user name and password combination that has not been added to the server, the login challenge will be redisplayed.

  2. When you login successfully using quickstartUser/quickstartPwd1!, the browser displays the following security info:

    Successfully called Secured EJB
    
    Principal : quickstartUser
    Remote User : quickstartUser
    Has admin permission : false
    Authentication Type : BASIC
    Note
    See Server Log: Expected Warnings and Errors for the expected exception you will see in the server log.
  3. The application can also be accessed directly by a remote client. Type the following command in the root directory of the quickstart:

    $ mvn exec:exec

    The remote client application runs and displays the results of calling the secured bean.

    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    Called secured bean, caller principal quickstartUser
    
    Principal has admin permission: false
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    Note
    See Server Log: Expected Warnings and Errors for the expected exception you will see in the server log.
  4. Next, change the exported realm so that it now uses the legacy role mappers as defined in the legacy JAAS security domain.

    Make sure you are still in the root directory of this quickstart, and run the following command, replacing WILDFLY_HOME with the path to your server.

    WILDFLY_HOME/bin/jboss-cli.sh --connect --file=enable-role-mappers.cli
    Note
    For Windows, use the WILDFLY_HOME\bin\jboss-cli.bat script.

    You should see the following result when you run the script.

    {
        "outcome" => "success",
        "response-headers" => {
            "operation-requires-reload" => true,
            "process-state" => "reload-required"
        }
    }
  5. If you didn’t close your web browser, re-load the quickstart application page. Otherwise open a new browser, point it to the URL http://localhost:8080/ejb-security-jaas/ and login with quickstartUser/quickstartPwd1!. It should now display a page confirming the user now has the admin role that was provided by the legacy role mapper:

    Successfully called Secured EJB
    
    Principal : quickstartUser
    Remote User : quickstartUser
    Has admin permission : true
    Authentication Type : BASIC
    Note
    This time you will not see the exception in the server log because quickstartUser is authorized for the admin role.
  6. The same result can be observed when re-running the remote client application:

    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    Called secured bean, caller principal quickstartUser
    Principal has admin permission: true
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    Note
    This time you will not see the exception in the server log because quickstartUser is authorized for the admin role.

Server Log: Expected Warnings and Errors

When you initially test this quickstart, you will see the following exception in the server log when you log in using the application URL and when you run the mvn exec:exec command. This is because the quickstartUser does not yet have the admin role required by the administrativeMethod() method. You can ignore this exception.

ERROR [org.jboss.as.ejb3.invocation] (default task-1) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_jaas.SecuredEJBRemote.administrativeMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_jaas.SecuredEJBRemote.administrativeMethod() of bean: SecuredEJB is not allowed
	at org.jboss.as.ejb3.security.RolesAllowedInterceptor.processInvocation(RolesAllowedInterceptor.java:67)
	at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
	...

After you enable the legacy security domain role mappers in the exported realm, the quickstartUser will have admin role access and you will no longer see the exception in the server log.

Undeploy the Quickstart

When you are finished testing the quickstart, follow these steps to undeploy the archive.

  1. Make sure you start the WildFly server as described above.

  2. Open a terminal and navigate to the root directory of this quickstart.

  3. Type this command to undeploy the archive:

    $ mvn wildfly:undeploy

Restore the WildFly Standalone Server Configuration

You can restore the original server configuration using either of the following methods.

Restore the WildFly Standalone Server Configuration by Running the JBoss CLI Script

  1. Start the WildFly server as described above.

  2. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing WILDFLY_HOME with the path to your server:

    $ WILDFLY_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
    Note
    For Windows, use the WILDFLY_HOME\bin\jboss-cli.bat script.

This script reverts the changes made to the ejb3, elytron, security and undertow subsystems. You should see the following result when you run the script.

The batch executed successfully
process-state: reload-required

Restore the WildFly Standalone Server Configuration Manually

When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file.

  1. If it is running, stop the WildFly server.

  2. Replace the WILDFLY_HOME/standalone/configuration/standalone.xml file with the backup copy of the file.

Remove the Properties Files from the Server

After you are done with this quickstart, remember to remove the users.properties and roles.properties files from the server configuration directory (WILDFLY_HOME/standalone/configuration/).

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

You can also start the server and deploy the quickstarts or run the Arquillian tests in Red Hat JBoss Developer Studio or from Eclipse using JBoss tools. For general information about how to import a quickstart, add a WildFly server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

  • Make sure you Create the Properties Files for the JAAS Security Domain as described above.

  • Make sure you configure the server by running the JBoss CLI script as described above under Configure the Server. Stop the server at the end of that step.

  • To deploy the application to the WildFly server, right-click on the ejb-security-jaas project and choose Run AsRun on Server.

  • You are presented with a browser login challenge. Enter the credentials as described above under Access the Application to see the running application. Note that Has admin permission is false.

  • Leave the application running in JBoss Developer Studio. To configure the server to use the legacy role mappers, open a terminal, and run the enable-role-mappers.cli script as described above under Access the Application.

  • Go back to JBoss Developer Studio and click Refresh the current page. Note that Has admin permission is now true.

  • To undeploy the project, right-click on the ejb-security-jaas project and choose Run AsMaven build. Enter wildfly:undeploy for the Goals and click Run.

  • Make sure you restore the server configuration when you have completed testing this quickstart.

Debug the Application

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

$ mvn dependency:sources