Tomcat 5.5, the latest release of the Apache Java servlet container, supports the Servlet 2.4 and JSP 2.0 specifications. Tomcat is distributed as a deployable service in jbossweb-tomcat-55.sar in the deploy directory. It is shipped in exploded directory form, so it's easy to inspect and update the configuration of the embedded Tomcat instance.

The main service file is META-INF/jboss-service.xml. It configures the org.jboss.web.tomcat.tc5.Tomcat5 MBean which controls Tomcat. Its configurable attributes include:

While the jboss-service.xml file controls the Tomcat integration service, Tomcat itself has its own configuration file which guides its operation. This is the server.xml descriptor that you will find in the jbossweb-tomcat55.sar directory.

The server.xml file doesn't have a formal DTD or schema definition, so we'll just cover the major configurable elements available. The top-level element is the Server element. It should contain a Service element representing the entire web subsystem. The supported attributes are:

The context.xml file contains the default Context element used for all web applications in the system. The supported attributes include:

You can find additional information on the Context element in the Tomcat documentation at http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html.

There are a few ways you can configure HTTP over SSL for the embedded Tomcat servlet container depending on whether or not you use the JBoss specific connector socket factory, which allows you to obtain the JSSE server certificate information from a JBossSX SecurityDomain. This requires establishing a SecurityDomain using the org.jboss.security.plugins.JaasSecurityDomain MBean. These two steps are similar to the procedure we use in Chapter 8, Security on JBoss to enable RMI with SSL encryption. A server.xml configuration file that illustrates the setup of only an SSL connector via this approach is given below.

<Server>
    <Service name="jboss.web" className="org.jboss.web.tomcat.tc5.StandardService">

        <Connector port="8080" address="${jboss.bind.address}" maxThreads="150"
            minSpareThreads="25" maxSpareThreads="75" enableLookups="false"
            redirectPort="443" acceptCount="100" connectionTimeout="20000" 
            disableUploadTimeout="true"/>

        <Connector port="443" address="${jboss.bind.address}" maxThreads="100"
            minSpareThreads="5" maxSpareThreads="15" scheme="https"
            secure="true" clientAuth="false"
            keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"
            keystorePass="rmi+ssl" sslProtocol="TLS"/>

        <Engine name="jboss.web" defaultHost="localhost">
            <Realm
                className="org.jboss.web.tomcat.security.JBossSecurityMgrRealm" 
                certificatePrincipal="org.jboss.securia.Log4jLogger"
                verbosityLevel="WARNING" category="org.jboss.web.localhost.Engine"/>
            <Host name="localhost" autoDeploy="false" deployOnStartup="false" 
                  deployXML="false">
                <DefaultContext cookies="true" crossContext="true" override="true"/>
            </Host>
        </Engine>
    </Service>
            </Server>

This configuration includes the same JaasSecurityDomain setup as Chapter 8, Security on JBoss, but since the descriptor is not being deployed as part of a SAR that includes the chap8.keystore, you need to copy the chap8.keystore to the server/default/conf directory. You can test this configuration by accessing the JMX console web application over HTTPS using this URL: https://localhost/jmx-console.

Note: if you are running on a system that requires special permissions to open ports below 1024, it might be easier need to change the port number to one above 1024. Port 8443 is commonly used because of this.

The configurable attributes are as follows:

Note that if you try to test this configuration using the self-signed certificate from the Chapter 8, Security on JBoss chap8.keystore and attempt to access content over an HTTPS connection, your browser should display a warning dialog indicating that it does not trust the certificate authority that signed the certificate of the server you are connecting to. For example, when we tested the first configuration example, IE 5.5 showed the initial security alert dialog listed in Figure 9.1, “The Internet Explorer 5.5 security alert dialog.”. Figure 9.2, “The Internet Explorer 5.5 SSL certificate details dialog.” shows the server certificate details. This warning is important because anyone can generate a self-signed certificate with any information desired. Your only way to verify that the system on the other side really represents the party it claim to is by verifying that it is signed by a trusted third party.

Figure 9.1. The Internet Explorer 5.5 security alert dialog.

Figure 9.2. The Internet Explorer 5.5 SSL certificate details dialog.

When using BASIC and FORM web authentications, the users password is sent in the clear as part of the HTTP requests. As we saw in the last section, it is possible to encrypt the entire session using HTTPS, keeping the password private over the wire. However, this still requires the password to exist on in plain text form on the server, at least temporarily in memory if not in password store.

Digest authentication employs a challenge-response mechanism, whereby the server sends a unique challenge to the client. The client responds with a hashed value that the server compares against it's own hashed value. At no point does the client ever send the the actual password text to the server.

Web applications request digest authentication by setting the auth-method to DIGEST in the web.xml deployment descriptor. The following example shows what this would look like, omitting the application-specific security-constraint and security-role declarations.

<login-config>
    <auth-method>DIGEST</auth-method>
    <realm-name>My Aplication</realm-name>
</login-config>

To complete the configuration, we'll create a special digest-friendly security domain and link it to the application. For this example, we'll create a security domain under the name java:/jaas/digest. The application would link to it in the jboss-web.xml file.

<jboss-web>
    <security-domain>java:/jaas/digest</security-domain>
</jboss-web>        

Now we need to create the security domain definition, as explained in Section 8.5, “Defining Security Domains”. We'll use the UsersRolesLoginModule in this example, though any login module that supports password hashing can be used. The following examples shows a complete configuration.

<application-policy name="digest">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
                      flag="required">
            <module-option name="usersProperties">digest-users.properties</module-option>
            <module-option name="rolesProperties">digest-roles.properties</module-option>
            <module-option name="hashAlgorithm">MD5</module-option>
            <module-option name="hashEncoding">rfc2617</module-option>
            <module-option name="hashUserPassword">false</module-option>
            <module-option name="hashStorePassword">true</module-option>
            <module-option name="passwordIsA1Hash">true</module-option>
            <module-option name="storeDigestCallback">
                org.jboss.security.auth.spi.RFC2617Digest
            </module-option>
        </login-module>
    </authentication>
</application-policy>

The first two module options configure the locations of the user and roles properties file. The remaining six complete the configuration for digest authentication. To enable digest authentication in your application, copy these last 6 options into your login module configuration.

At this point, all the is required is to create the password hashes to be stored in your user store, which is the digest-users.properties file in this example. Digest hashes hash the username, the password, and the realm name together. The realm name comes from the realm name in web.xml file. In this example it is My Application.

JBoss provides a helper class to create digest hashes. It can be invoked from the bin directory as shown here:

[bin]$ java -cp ../server/default/lib/jbosssx.jar \
org.jboss.security.auth.spi.RFC2617Digest username "My Application" password
RFC2617 A1 hash: 9b47ec6f03603dd49863e7d58c4c49ea

The three arguments are the username, the realm name and the password. The digested password should be stored in the user management store. In the example here, it would go in the digest-users.properties file.

user=9b47ec6f03603dd49863e7d58c4c49ea

You would still need to define the application roles and configure them in the login module to complete the security configuration. However, none of this differs with digest authentication.

The context root of a web application determines which URLs Tomcat will delegate to your web application. If your application's context root is myapp then any request for /myapp or /myapp/* will be handled by your application unless a more specific context root exists. If a second web application were assigned the context root myapp/help, a request for /myapp/help/help.jsp would be handled by the second web application, not the first.

This relationship also holds when the context root is set to /, which is known as the root context. When an application is assigned to the root context, it will respond to all requests no handled by a more specific context root.

The context root for an application is determined by how it is deployed. When a web application is deployed inside an EAR file, the context root is specified in the application.xml file of the EAR, using a context-root element inside of a web module. In the following example, the context root of the web-client.war application is set to bank.

<application xmlns="http://java.sun.com/xml/ns/j2ee" version="1.4"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com /xml/ns/j2ee 
                             http://java.sun.com/xml/ns/j2ee/application_1_4.xsd">
    <display-name>JBossDukesBank</display-name>

    <module>
        <ejb>bank-ejb.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>web-client.war</web-uri>
            <context-root>bank</context-root>
        </web>
    </module>

</application>

For web applications that are deployed outside an EAR file, the context root can be specified in two ways. First, the context root can be specified in the WEB-INF/jboss-web.xml file. The following example shows what the jboss-web.xml file would look like if it weren't bundled inside of an EAR file.

<jboss-web>
    <context-root>bank</context-root>
</jboss-web>

Finally, if no context root specification exists, the context root will be the base name of the WAR file. For web-client.war, the context root would default to web-client. The only special case to this naming special name ROOT. To deploy an application under the root context, you simply name it ROOT.war. JBoss already contains a ROOT.war web application in the jbossweb-tomcat55.sar directory. You will need to remove or rename that one to create your own root application.

Naming your WAR file after the context root they are intended to handle is a very good practice. Not only does it reduce the number of configuration settings to manage, but it improves the maintainability of the application by making the intended function of the web application clear.

Virtual hosts allow you to group web applications according to the various DNS names by which the machine running JBoss is known. As an example, consider the server.xml configuration file given in Example 9.1, “A virtual host configuration.”. This configuration defines a default host named vhost1.mydot.com and a second host named vhost2.mydot.com, which also has the alias www.mydot.com associated with it.

<Server>
   <Service name="jboss.web"
      className="org.jboss.web.tomcat.tc5.StandardService">
       
      <!-- A HTTP/1.1 Connector on port 8080 -->
      <Connector port="8080" address="${jboss.bind.address}"
                 maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                 enableLookups="false" redirectPort="8443" acceptCount="100"
                 connectionTimeout="20000" disableUploadTimeout="true"/>

      <Engine name="jboss.web" defaultHost="vhost1">
         <Realm className="org.jboss.web.tomcat.security.JBossSecurityMgrRealm"
                certificatePrincipal="org.jboss.security.auth.certs.SubjectDNMapping"
            />
         <Logger className="org.jboss.web.tomcat.Log4jLogger"
                 verbosityLevel="WARNING"
                 category="org.jboss.web.localhost.Engine"/>

            <Host name="vhost1" autoDeploy="false"
                  deployOnStartup="false" deployXML="false">
                <Alias>vhost1.mydot.com</Alias>
                <Valve className="org.apache.catalina.valves.AccessLogValve"
                       prefix="vhost1" suffix=".log" pattern="common"
                       directory="${jboss.server.home.dir}/log"/>
            
  
                <DefaultContext cookies="true" crossContext="true" override="true"/>
            </Host>   
            <Host name="vhost2" autoDeploy="false" 
                  deployOnStartup="false" deployXML="false">
                <Alias>vhost2.mydot.com</Alias>
                <Alias>www.mydot.com</Alias>  

                <Valve className="org.apache.catalina.valves.AccessLogValve"
                       prefix="vhost2" suffix=".log" pattern="common" 
                       directory="${jboss.server.home.dir}/log"/>

                <DefaultContext cookies="true" crossContext="true" override="true"/>
            </Host>
      </Engine>
   </Service>
</Server>

When a WAR file is deployed, it is associated by default with the virtual host whose name matches the defaultHost attribute of the containing Engine. To deploy a WAR to a specific virtual host you need to specify an appropriate virtual-host definition in your jboss-web.xml descriptor. The following jboss-web.xml descriptor demonstrates how to deploy a WAR to the virtual host www.mydot.com. Note that you can use either the virtual host name in the config file or the actual host name.

<jboss-web>
    <context-root>/</context-root>
    <virtual-host>www.mydot.com</virtual-host>
</jboss-web>

JBoss provides a default application that serves content for the root application context. This default context is the ROOT.war application in the jbossweb-tomcat55.sar directory. You can serve static files not associated with any other application by adding that content to the ROOT.war directory. For example, if you want to have a shared image directory you could create an image subdirectory in ROOT.war and place the images there. You could then access an image named myimage.jpg at http://localhost:8080/images/myimage.jpg.

In some architectures, it is useful to put an Apache web server in front of the JBoss server. External web clients talk to an Apache instance, which in turn speaks to the Tomcat instance on behalf of the clients. Apache needs to be configured to use the mod_jk module which speaks the AJP protocol to an AJP connector running in Tomcat. The provided server.xml file comes with this AJP connector enabled.

<Connector port="8009" address="${jboss.bind.address}"
           enableLookups="false" redirectPort="8443" debug="0"
           protocol="AJP/1.3" />

You'll need to consult the Apache and mod_jk documentation for complete installation instructions. Assuming you have a properly configured Apache instance, the following configuration fragment shows an example of how to connect with a WAR deployed with a context root of /jbosstest.

...
LoadModule jk_module libexec/mod_jk.so
AddModule mod_jk.c
           
<IfModule mod_jk.c>
    JkWorkersFile /tmp/workers.properties
    JkLogFile /tmp/mod_jk.log
    JkLogLevel debug
    JkMount /jbosstest/* ajp13
</IfModule>

The workers.properties file contains the details of how to contact the JBoss instance. For more details on how to front Apache for JBoss, especially for a cluster of JBoss servers, please refer to Section 16.5.2, “Configure Apache to load mod_jk” and Section 16.5.3, “Configure worker nodes in mod_jk”.

Starting with version 4.0.3, the JBoss Application Server features built-in JavaServer Faces support. The implementation used is Apache MyFaces; however, the MyFaces extensions are not included with the JBoss distribution at this time. JBoss allows you to install your JSF application without putting lots of extra JSF implementation JAR files in your WEB-INF/lib directory.

To make use of JSF, you need to declare the Faces Servlet and the servlet mapping in the web.xml file:

<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.jsf</url-pattern>
</servlet-mapping>

In order to initialize the JSF environment, you also need to add the MyFaces listener to web.xml file:

<listener>
    <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>
</listener>

There are several additional context parameters that can be set to control the configuration of JavaServer Faces for a particular application:

<context-param>
    <param-name>javax.faces.CONFIG_FILES</param-name>
    <param-value>
        /WEB-INF/examples-config.xml
    </param-value>
    <description>
        Comma separated list of URIs of (additional) faces config files.
        (e.g. /WEB-INF/my-config.xml)
        See JSF 1.0 PRD2, 10.3.2
    </description>
</context-param>

<context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>server</param-value>
    <description>
        State saving method: "client" or "server" (= default)
        See JSF Specification 2.5.2
    </description>
</context-param>

<context-param>
    <param-name>org.apache.myfaces.ALLOW_JAVASCRIPT</param-name>
    <param-value>true</param-value>
    <description>
        This parameter tells MyFaces if javascript code should be allowed in the
        rendered HTML output.
        If javascript is allowed, command_link anchors will have javascript code
        that submits the corresponding form.
        If javascript is not allowed, the state saving info and nested parameters
        will be added as url parameters.
        Default: "true"
    </description>
</context-param>

<context-param>
    <param-name>org.apache.myfaces.DETECT_JAVASCRIPT</param-name>
    <param-value>false</param-value>
    <description>
        This parameter tells MyFaces if javascript code should be allowed in the
        rendered HTML output.
        If javascript is allowed, command_link anchors will have javascript code
        that submits the corresponding form.
        If javascript is not allowed, the state saving info and nested parameters
        will be added as url parameters.
        Default: "false"
        
        Setting this param to true should be combined with STATE_SAVING_METHOD "server" for
        best results.
        
        This is an EXPERIMENTAL feature. You also have to enable the detector 
        filter/filter mapping below to get JavaScript detection working.
    </description>
</context-param>

<context-param>
    <param-name>org.apache.myfaces.PRETTY_HTML</param-name>
    <param-value>true</param-value>
    <description>
        If true, rendered HTML code will be formatted, so that it is "human readable".
        i.e. additional line separators and whitespace will be written, that do not
        influence the HTML code.
        Default: "true"
    </description>
</context-param>

<context-param>
    <param-name>org.apache.myfaces.AUTO_SCROLL</param-name>
    <param-value>true</param-value>
    <description>
        If true, a javascript function will be rendered that is able to restore the
        former vertical scroll on every request. Convenient feature if you have pages
        with long lists and you do not want the browser page to always jump to the top
        if you trigger a link or button action that stays on the same page.
        Default: "false"
    </description>
</context-param>

To use another JSF implementation, such as the reference implementation, instead of the bundled MyFaces implementation, simply delete the

jbossweb-tomcat55.sar/jsf-lib

directory. You will need to include the the implementation JAR files in your own

WEB-INF/lib

directory for each web application making use of JSF.