Required Post-Installation Tasks for the JBoss Application Server 4.x/5.x Agent

• Setting the JBOSS_CLASSPATH Variable for the JBoss Application Server Instance

• Deploying the Agent Application

• Installing the Agent Filter for an Application Protected by the JBoss Application Server 4.x/5.x Agent

Setting the JBOSS_CLASSPATH Variable for the JBoss Application Server Instance

You must set the JBOSS_CLASSPATH variable for the JBoss Application Server 4.x/5.x configuration and locale directories.

To set the JBOSS_CLASSPATH variable, modify the JBoss startup script, depending on your platform:

• Solaris and Linux systems: JBOSS_HOME/bin/run.sh

• Windows: JBOSS_HOME\bin\run.bat

To Set the JBOSS_CLASSPATH Variable on Solaris and Linux Systems

1. In the JBOSS_HOME/bin/run.sh script, find the following lines:

   if [ "x$JBOSS_CLASSPATH" = "x" ]; then
     JBOSS_CLASSPATH="$JBOSS_BOOT_CLASSPATH:$JAVAC_JAR"
     else
     JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$JBOSS_BOOT_CLASSPATH:$JAVAC_JAR"
   fi

2. After the lines you found in Step 1, add the following new lines:

   CONFIG=$2
   if [ "x$1"="x" ] && [ "x$CONFIG" = "x" ]; then CONFIG=default; fi
   if [ -r "setAgentClasspath$CONFIG.sh" ]; then
             . /opt/jboss-4.2.3.GA/bin/setAgentClasspath$CONFIG.sh
   fi

   Note: The previous command is for JBoss Application Server 4.2.3.GA. If you are using a different version, specify the appropriate JBoss Application Server directory.

3. Save the change.

To Set the JBOSS_CLASSPATH Variable on Windows Systems

1. In the JBOSS_HOME\bin\run.bat script, find the following lines:

   if "%JBOSS_CLASSPATH%" == "" (
              set JBOSS_CLASSPATH=%JAVAC_JAR%;%RUNJAR% 
   ) ELSE (
              set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%JAVAC_JAR%;%RUNJAR% 
   )

2. After the lines you found in Step 1, add the following new lines:

   set CONFIG=%2%
   if "x%CONFIG%" == "x" (
         set CONFIG=default 
   )
   if exist setAgentClasspath%CONFIG%.bat (
         call c:\jboss-4.2.3.GA\bin\setAgentClasspath%CONFIG%.bat
   )

   Note: The previous command is for JBoss Application Server 4.2.3.GA. If you are using a different version, specify the appropriate JBoss Application Server directory.

3. Save the change.

Deploying the Agent Application

The agent application (agentapp.war) is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support.

To Deploy the Agent Application

1. The agent application (agentapp.war) is bundled with the jboss_v42_agent_3.zip distribution file and is available as follows after you unzip the file:

   PolicyAgent-base/etc/agentapp.war

2. Deploy agentapp.war on the JBoss Application Server instance using the JBoss administration console or deployment command.

   Important: You must use the same deployment URI that you specified for the “Agent URL” prompt during the agent installation. For example, if you accepted the default value (/agentapp) as the deployment URI for the agent application, use this same URI to deploy agentapp.war.

Installing the Agent Filter for an Application Protected by the JBoss Application Server 4.x/5.x Agent

You install the agent filter by modifying the deployment descriptor of each application that you want to protect with the JBoss Application Server 4.x/5.x agent.

To Install the Agent Filter for an Application Protected by the JBoss Application Server 4.x/5.x Agent

1. Ensure that the application you want to protect is not currently deployed on JBoss Application Server.

   If the application is deployed, undeploy it before continuing.

2. Backup the application's web.xml file before you modify the deployment descriptor.

   The backup copy can be useful if you need to uninstall the agent later.

3. Edit the deployment descriptors in the application's web.xml file as follows:

   1. Set the <DOCTYPE> element as shown in the following example:

      <!DOCTYPE web-app version="2.4"
      xmlns="http://java.sun.com/xml/ns/j2ee"
      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/web-app_2_4.xsd">

      Note: JBoss Application Server supports the Java Servlet specification version 2.4. Version 2.4 is fully backward compatible with version 2.3. Therefore, all existing servlets should work without modification or recompilation.

   2. Add the <filter> elements to the deployment descriptor.

      Specify the agent filter as the first <filter> element and the agent filter mapping as the first <filter-mapping> element. For example:

      <web-app>
      ...
          <filter>
              <filter-name>Agent</filter-name>
              <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
          </filter>
          <filter-mapping>
              <filter-name>Agent</filter-name>
              <url-pattern>/*</url-pattern>
              <dispatcher>REQUEST</dispatcher>
              <dispatcher>INCLUDE</dispatcher>
              <dispatcher>FORWARD</dispatcher>
              <dispatcher>ERROR</dispatcher>
          </filter-mapping>
      ...
      </web-app>

4. In the applications's jboss-web.xml and jboss.xml files, specify the value of the security-domain element as AMRealm. For example:

   <security-domain>java:/jaas/AMRealm</security-domain>

5. Restart the JBoss Application Server instance.

6. Deploy (or redeploy) the application on the JBoss Application Server web container.

   The agent filter is then added for the application.

Next Steps

You can also protect an application with Java EE declarative security. To learn more about protecting your application with Java EE declarative security, consider Deploying the Java EE Policy Agent Sample Application.