Skip to content

README.adoc

Latest commit

 

History

History
358 lines (296 loc) · 16.5 KB

README.adoc

File metadata and controls

358 lines (296 loc) · 16.5 KB

ejb-security-jaas: Using the legacy JAAS security domains to secure JEE applications

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 {productNameFull} 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.

Create the Properties Files for the JAAS Security Domain

  1. Open a terminal and navigate to the {productName} server configuration directory:

    $ cd {jbossHomeName}/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.

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 {jbossHomeName} with the path to your server.

    $ {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli
    Note
    		 For Windows, use the {jbossHomeName}\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 {productName} server.

Review the Modified Server Configuration

After stopping the server, open the {jbossHomeName}/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.

Access the Application

The application will be running at the following URL http://localhost:8080/{artifactId}/.

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 {jbossHomeName} with the path to your server.

    $ {jbossHomeName}/bin/jboss-cli.sh --connect --file=enable-role-mappers.cli
    Note
    		 For Windows, use the {jbossHomeName}\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/{artifactId}/ 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.

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

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 ({jbossHomeName}/standalone/configuration/).

  • 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 {productName} server, right-click on the {artifactId} project and choose Run As → Run 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 {JBDSProductName}. 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 {JBDSProductName} and click Refresh the current page. Note that Has admin permission is now true.

  • To undeploy the project, right-click on the {artifactId} project and choose Run As → Maven build. Enter wildfly:undeploy for the Goals and click Run.

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