This document describes how to run OWF 7 in JBoss. It is intended to serve as an example of hosting OWF in a Java Servlet container other than the default, Apache Tomcat. The steps that follow will configure OWF to use x509 certificate authentication only. Consult JBoss documentation for information on performance tuning and security lock-down.

1. You must have a properly built OWF 7 distribution. For the purpose of this document [owfBundle] refers to the staging directory in your OWF source tree.

2. Download the JBoss Application Server package (i.e. jboss-5.1.0.GA.zip, jboss-as-7.1.1.Final.zip, etc.). Unzip the contents to your desired installation location. The root directory of your unzipped JBoss package will be referred to as [jBossHome] below.

The following subsections describe how to configure and run OWF in certain versions of JBoss.

• Create a ozone/configuration/main directory under the [jBossHome]/modules directory.

• Copy the following files and directories from the [owfBundle]/apache-tomcat-7.0.21/lib directory to the [jBossHome]/modules/ozone/configuration/main directory:

    OwfConfig.groovy
    owf-override-log4j.xml
    OzoneConfig.properties
    users.properties
    js-plugins/
    ozone-security-beans/
  

• Copy the [owfBundle]/owf-security/OWFsecurityContext_cert_only.xml file to the [jBossHome]/modules/ozone/configuration/main directory. Said file configures OWF to use certificate only authentication.

  NOTE: You must delete the default OWFsecurityContext.xml file from the main directory if you copied it there in the previous step.

• In the [jBossHome]/modules/ozone/configuration/main directory create a module.xml file with the following content:

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.1" name="ozone.configuration">
        <resources>
            <resource-root path="."/>
        </resources>
        <dependencies>
        </dependencies>
    </module>
  

• Create a owf.war directory in the [jBossHome]/standalone/deployments directory.

• Unwar (unzip) the contents of the [owfBundle]/apache-tomcat-7.0.21/webapps/owf.war file into the [jBossHome]/standalone/deployments/owf.war directory.

• In the [jBossHome]/standalone/deployments/owf.war/WEB-INF directory create a jboss-deployment-structure.xml file with the following content:

    <?xml version="1.0" encoding="UTF-8"?>
    <jboss-deployment-structure>
        <deployment>
            <!-- Do not use the built-in log4j that ships with JBoss -->
            <exclusions>
                <module name="org.apache.log4j" />
            </exclusions>
            <!-- Include external configuration module for OWF -->
            <dependencies>
                <module name="ozone.configuration"/>
            </dependencies>
        </deployment>
        <!-- Use log4j that ships with OWF -->
        <module name="deployment.log4j">
            <resources>
                <resource-root path="log4j-1.2.16.jar" />
            </resources>
        </module>
    </jboss-deployment-structure>
  

• Remove invalid OSGI headers from the OWF application. Delete all lines except those beginning with Manifest-Version and Created-By from the [jBossHome]/standalone/deployments/owf.war/META-INF/MANIFEST.MF file.

• Create an empty owf.war.dodeploy file in the [jBossHome]/standalone/deployments directory.

• Copy the [owfBundle]/apache-tomcat-7.0.21/certs/keystore.jks file to the [jBossHome]/standalone/configuration directory and rename it as owf-keystore.jks (to avoid naming conflicts).

• In the [jBossHome]/standalone/configuration/standalone.xml file find the subsystem whose xmlns is urn:jboss:domain:web:1.1 and add the following connector element as a child:

    <connector name="https"
     protocol="HTTP/1.1"
     scheme="https"
     socket-binding="https"
     secure="true">
        <ssl name="ssl"
         password="changeit"
         certificate-key-file="${jboss.server.config.dir}/owf-keystore.jks"
         protocol="TLSv1"
         verify-client="want"
         ca-certificate-file="${jboss.server.config.dir}/owf-keystore.jks" />
    </connector>
  

The OWF distribution is configured to use a HSQL database by default. The following step should only be performed if using the HSQL database.

• Copy the [owfBundle]/apache-tomcat-7.0.21/prodDb.script file to the [jBossHome]/bin directory.

  NOTE: The HSQL database that ships with OWF is intended for development purposes. It should not be used in production. You can change the database in the [jBossHome]/modules/ozone/configuration/main/OwfConfig.groovy file.

• Navigate to the [jBossHome]/bin directory (via a command prompt or file explorer).

• Execute the standalone.sh script (or standalone.bat).

  NOTE: When starting the JBoss server the prodDb.script file must be in the current working directory if using the HSQL database.

• Copy the contents of the [jBossHome]/server/default directory to a new directory. It can have any name, but we will call it owf7 for the purpose of this guide.

  NOTE: JBoss configurations other than default should work fine as a template for OWF, although not every one has been tested. Please report any issues encountered on the Google group.

• Copy the following files and directories from the [owfBundle]/apache-tomcat-7.0.21/lib directory to the [jBossHome]/server/owf7/conf directory:

    OwfConfig.groovy
    OzoneConfig.properties
    users.properties
    js-plugins/
    ozone-security-beans/
  

• Copy the [owfBundle]/owf-security/OWFsecurityContext_cert_only.xml file to the [jBossHome]/server/owf7/conf directory. Said file configures OWF to use certificate only authentication.

  NOTE: You must delete the default OWFsecurityContext.xml file from the conf directory if you copied it there in the previous step.

• Create a owf.war directory in the [jBossHome]/server/owf7/deploy directory.

• Unwar (unzip) the contents of the [owfBundle]/apache-tomcat-7.0.21/webapps/owf.war file into the [jBossHome]/server/owf7/deploy/owf.war directory.

• Remove JTA library that conflicts with JBoss. Delete the [jBossHome]/server/owf7/deploy/owf.war/WEB-INF/lib/jta-1.1.jar file.

• Copy the [owfBundle]/apache-tomcat-7.0.21/certs/keystore.jks file to the [jBossHome]/server/owf7/conf directory.

• Add the following connector entry to your [jBossHome]/server/owf7/deploy/jbossweb.sar/server.xml file:

    <Connector
     protocol="HTTP/1.1"
     SSLEnabled="true"
     port="8443"
     address="${jboss.bind.address}"
     scheme="https"
     secure="true"
     clientAuth="want"
     keystoreFile="${jboss.server.home.dir}/conf/keystore.jks"
     keystorePass="changeit"
     truststoreFile="${jboss.server.home.dir}/conf/keystore.jks"
     truststorePass="changeit"
     sslProtocol = "TLS" />
  

The OWF distribution is configured to use a HSQL database by default. The following step should only be performed if using the HSQL database.

• Copy the [owfBundle]/apache-tomcat-7.0.21/prodDb.script file to the [jBossHome]/bin directory.

  NOTE: The HSQL database that ships with OWF is intended for development purposes. It should not be used in production. You can change the database in the [jBossHome]/server/owf7/config/OwfConfig.groovy file.

• Open a command prompt and navigate to the [jBossHome]/bin directory.

• Start JBoss using the owf7 configuration defined in the previous sections. Enter one the following in your command prompt (depending on your platform):

    ./run.sh -c owf7
  

  or

    run.bat -c owf7
  

  NOTE: When starting the JBoss server the prodDb.script file must be in the current working directory if using the HSQL database.

Since we have configured OWF to use certificate only authentication above we must import the appropriate certificates into each web browser that will access OWF.

1. Open your web browser's certificate manager.

   In Firefox:

   • Open the Preferences menu and go the Advanced settings.
   • Click the View Certificates button in the Encryption tab.

2. Import either the testUser1.p12 or testAdmin1.p12 certificate file. Said files must be unlocked using "password" (no quotes) as the password. The noted example certificates are located under the [owfBundle]/apache-tomcat-7.0.21/certs directory.

   NOTE: The certificate file you import into your browser must correspond to one that exists in the keystore.jks (or owf-keystore.jks) file that JBoss is using for HTTPS.

3. When you access the OWF web application, via https://localhost:8443/owf for example, you will be prompted to select the certificate from a list of those you have imported.