This page describers how to configure the Wildfly / JBoss Application Server for Magnolia. 

Securing Web and JMX consoles

JBoss AS ships with two consoles which are publicly accessible: Web Console and JMX Console. Make sure they are secured and cannot be accessed publicly. Also make sure the JNP command port is protected.

See Securing the JMX Console and Web Console (HTTP)

Configuring JAAS login

Magnolia uses the Java Authentication and Authorization Service (JAAS) to authenticate and authorize users. Configure the JAAS login modules for JBoss AS so that you can log into Magnolia.

If JAAS login is not configured correctly you may see the following error:

The security domain other has been disabled. All authentication will fail. 
Please check your configuration to make sure this is expected

Wildfly 10.1.0.Final

To configure JAAS login modules in Wildfly 10.1.0.Final:

  1. Open WILDFLY_HOME/standalone/configuration/standalone.xml.
  2. Add the following login modules in the <subsystem xmlns="urn:jboss:domain:security:1.2> section:

    standalone.xml
    <subsystem xmlns="urn:jboss:domain:security:1.2">
        <security-domains>
            <security-domain name="magnolia" cache-type="default">
               <authentication>
                  <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthenticationModule" flag = "requisite" />
                  <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthorizationModule" flag = "required" />
               </authentication>
            </security-domain>
            <security-domain name="Jackrabbit" cache-type="default">
               <authentication>
                  <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" flag = "required" />
               </authentication>
            </security-domain>
            <security-domain name="other" cache-type="default">
                <authentication>
                    <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" flag="required"/>
                </authentication>
            </security-domain>
    	</security-domains>
    </subsystem>

JBoss AS 7

Please be aware that JBoss AS releases to version JBoss AS 7.1.1.Final are unsupported. An upgrade to either WildFly or JBoss EAP is recommended (cf. also Where is JBoss 7.2.0.Final?).

To configure JAAS login modules in JBoss AS 7:

  1. Open JBOSS_HOME/standalone/configuration/standalone.xml.
  2. Add the following login modules in the <subsystem xmlns="urn:jboss:domain:security:1.1"> section:

    standalone.xml
    <subsystem xmlns="urn:jboss:domain:security:1.1">
        <security-domains>
            <security-domain name="magnolia" cache-type="default">
               <authentication>
                  <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthenticationModule" flag = "requisite" />
                  <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthorizationModule" flag = "required" />
               </authentication>
            </security-domain>
            <security-domain name="Jackrabbit" cache-type="default">
               <authentication>
                  <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" flag = "required" />
               </authentication>
            </security-domain>
            <security-domain name="other" cache-type="default">
                <authentication>
                    <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" flag="required"/>
                </authentication>
            </security-domain>
    	</security-domains>
    </subsystem>

JBoss AS 6

To configure JAAS login modules in JBoss AS 6:

  1. Open JBOSS_HOME/server/default/conf/login-config.xml.
  2. Add the following login modules in login-config.xml under <policy>. The sequence of the login modules configured in this file does not matter.

    login-config.xml
    <!-- Magnolia JAAS login modules -->
    <application-policy name="magnolia">
       <authentication>
          <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthenticationModule" flag="requisite" />
         <login-module code="info.magnolia.jaas.sp.jcr.JCRAuthorizationModule" flag="required" />
       </authentication>
    </application-policy>
    
    <!-- Jackrabbit JAAS login modules -->
    <application-policy name="Jackrabbit">
       <authentication>
          <login-module 
           code="org.apache.jackrabbit.core.security.SimpleLoginModule" 
           flag="required" />
       </authentication>
    </application-policy>

Deploying Bouncy Castle cryptography libraries

Magnolia uses the Bouncy Castle cryptography package to decode the license key and to secure the activation processIn JBoss AS7, the Bouncy Castle libraries must be deployed as a server module.

  1. Create a JBoss AS module folder in $JBOSS_HOME/modules/org/bouncycastle/main.
    (warning) JBoss WildFly $JBOSS_HOME/modules/system/layers/base/org/bouncycastle/main

  2. Place the required Bouncy Castle JAR files in the folder:
    • Provider bcprov
    • Provider extensions bcprov-ext
    • OpenPGP/BCPG bcpg
    • SMIME bcmail
  3. Create a module.xml file in the same folder and add the following code in the file.

    module.xml
    <module xmlns="urn:jboss:module:1.1" name="org.bouncycastle">
      <resources>
        <resource-root path="bcprov-jdk16-1.46.jar"/><!-- put proper filename here, depending on the BC version you're using -->
      </resources>
      <dependencies>
        <module name="javax.api" slot="main" export="true"/>
      </dependencies>
    </module>

    For Wildfly 10.1.0.Final the code should go as follows:

    module.xml
    <module xmlns="urn:jboss:module:1.1" name="org.bouncycastle">
      <resources>
          <resource-root path="bcprov-jdk15on-1.46.jar"/>
          <resource-root path="bcpg-jdk15on-1.46.jar"/>
          <resource-root path="bcmail-jdk15on-1.46.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api" slot="main" export="true"/>
      </dependencies>
    </module>
  4. Create a jboss-deployment-structure.xml file in Magnolia's WEB-INF folder and configure the above module for use by adding the following code.

    jboss-deployment-structure.xml
    <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
      <deployment>
        <dependencies>
          <module name="org.bouncycastle" slot="main" export="true" />
        </dependencies>
      </deployment>
    </jboss-deployment-structure>
  5. Remove the Bouncy Castle JAR files from Magnolia's WEB-INF/lib folder.

Using Magnolia's REST API

Magnolia's REST modules use RESTEasy 3.0.4.Final but JBoss already comes with RESTEasy modules (JBoss AEP 6.1 for example comes with RESTEasy 2.3.5). To be able to use the REST modules, you'll have to

  1. Update RESTEasy module on your JBoss instance (https://docs.jboss.org/resteasy/docs/3.0.6.Final/userguide/html/Installation_Configuration.html#upgrading-eap61)
    1. Download resteasy-jaxrs-3.0.4.Final-all.zip
    2. This comes with resteasy-jboss-modules-3.0.4.Final.zip
    3. Unzip & copy the content to $EAP_HOME/modules/system/layers/base/ (Make sure to keep newer libs)
  2. Create or edit jboss-deployment-structure.xml file in Magnolia's WEB-INF folder by adding the following code. This will disable the container's JAX-RS and JAX-WS in [the] war which is required as Magnolia uses its own way to register endpoints and resources in info.magnolia.rest.RestDispatcherServlet.

    jboss-deployment-structure.xml
    <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
      <deployment>
        <exclude-subsystems>
          <subsystem name="jaxrs"/>
          <subsystem name="webservices"/>
        </exclude-subsystems>
      </deployment>
    </jboss-deployment-structure>

Magnolia Workflow (prior 5.4)

When using Magnolia's worklow modules prior to 5.4 you might experience class loading issue related to packages of org.jboss.weld.*. In this case create or edit jboss-deployment-structure.xml file in Magnolia's WEB-INF folder by adding the following code.

jboss-deployment-structure.xml
<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <exclude-subsystems>
            <subsystem name="weld" />
        </exclude-subsystems>
    </deployment>
</jboss-deployment-structure>

See also below a known issue: JBoss AS7 class loading issue with Weld.

Assigning heap memory

JBoss AS 7

Set the JAVA_OPTS environment variable in JBOSS_HOME/bin/standalone.conf (or standalone.conf.bat in Windows) under the section "Specify options to pass to the Java VM." For example: 

standalone.conf
JAVA_OPTS="-server -Xms1024m -Xmx1024m -XX:MaxPermSize=384M"

JBoss AS 6

Set the JAVA_OPTS environment variable in JBOSS_HOME/bin/run.conf under section "Specify options to pass to the Java VM." For example:

JAVA_OPTS="-server -Xms1024m -Xmx1024m -XX:MaxPermSize=384M"

Configuring Log4j

JBoss 7 Application Server adds its own log4j logging configuration. If you want to use your own log4j logging configuration in your deployment, exclude the JBoss configuration first.

Create a new file jboss-deployment-structure.xml under the WEB-INF folder with this content:

<jboss-deployment-structure>
  <deployment>
  <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
    <exclusions>
      <module name="org.apache.log4j" />
      <module name="org.slf4j" />
    </exclusions>
  </deployment>
</jboss-deployment-structure>

See How do I use log4j.properties or log4j.xml instead of using the logging subsystem configuration?

A symptom of this issue is that you only see the Root class in Tools > Logging.

Enabling remote debugging

To enable remote debugging, go to JBOSS_HOME/bin and uncomment following line in standalone.conf:

standalone.conf
# Sample JPDA settings for remote socket debugging
JAVA_OPTS="$JAVA_OPTS -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"

Known issues

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))