Chapter 4 Post-Installation Tasks of Policy Agent 2.2 for JBoss Application Server 4.0

This chapter describes configuration and other post-installation considerations and tasks, including:

• Common Post-Installation Steps for All J2EE Agents in Policy Agent 2.2

• Post-Installation Steps Specific to Agent for JBoss Application Server 4.0

• Conditional Post-Installation Steps for J2EE Agents in Policy Agent 2.2

After completing the applicable tasks described in this chapter, perform the tasks to configure the agent to your site's specific needs as explained in Chapter 5, Managing Policy Agent 2.2 for JBoss Application Server 4.0.

Common Post-Installation Steps for All J2EE Agents in Policy Agent 2.2

The tasks described in this section apply to all J2EE agent installations.

Updating the Agent Profile for J2EE Agents in Policy Agent 2.2

This procedure is not required. The agent profile is created and updated in Access Manager Console. The agent profile should originally be created prior to installing an agent. However, after you install a J2EE agent, you can update the agent profile at anytime. If you do update the agent profile in Access Manager Console, you must then configure the J2EE agent accordingly as described in this section.

To Update the Agent Profile for J2EE Agents in Policy Agent 2.2

Before You Begin

Change the agent profile in Access Manager using Access Manager Console. For more information about the agent profile, see Creating a J2EE Agent Profile.

1. Change the password in the password file to match the new password you just created in Access Manager Console as a part of the agent profile.

   The password file should originally have been created as a J2EE agent pre-installation task. For more information about pre-installation, see Preparing to Install Agent for JBoss Application Server 4.0.

2. In the command line, issue the agentadmin --encrypt command to encrypt the new password.

   For more information on this command, see agentadmin --encrypt.

3. Access the J2EE agent AMAgent.properties configuration file at the following location:

   PolicyAgent-base/AgentInstance-Dir/config

4. In this configuration file, edit the property for the agent ID to match the new ID in the agent profile as follows:

   com.sun.identity.agents.app.username = agentID
   

   where agentID represents the new agent ID that you created for the agent profile in Access Manager Console.

5. Edit the property for the agent password as follows:

   com.iplanet.am.service.secret = encryptedPassword
   

   where encryptedPassword represents the new encrypted password you created when you issued the agentadmin --encrypt command.

6. Restart the J2EE agent container.

   The container needs to be restarted because neither property that you edited in this task is hot-swap enabled.

Post-Installation Steps Specific to Agent for JBoss Application Server 4.0

Once you have installed Policy Agent 2.2 for JBoss Application Server 4.0 and you have performed the post-installation steps that apply to all J2EE agents in the Policy Agent 2.2 release, complete the following agent-specific steps.

Setting the Classpath for the JBoss Application Server 4.0 Instance

The JBOSS_CLASSPATH variable must be set to the agent's configuration and locale directories. To set the JBOSS_CLASSPATH variable, modify the appropriate JBoss startup script, depending on your platform:

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

• Windows platforms: JBOSS_HOME\bin\run.bat

The changes to the startup script call the setAgentClassPath script, which sets the JBOSS_CLASSPATH variable when you run the script.

These changes are based on running the scripts as follows:

• Solaris and Linux platforms: run.sh -c server-instance-name

• Windows platforms: run.bat -c server-instance-name

If you specify other script arguments or specify the arguments in a different order, you must change the CONFIG=$2 or set CONFIG=%2% lines accordingly.

To set the JBOSS_CLASSPATH Variable on Solaris and Linux Platforms:

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.0.2/bin/setAgentClasspath$CONFIG.sh 
   fi

   Note: The previous command is for JBoss server 4.0.2. If you are using a different version, specify the appropriate JBoss server directory.

3. Save your changes.

To set the JBOSS_CLASSPATH Variable on Windows Platforms:

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.0.2\bin\setAgentClasspath%CONFIG%.bat
   )

3. Save your changes.

Installing the Agent Filter for the Deployed Application on Agent for JBoss Application Server 4.0

You install the agent filter by modifying the deployment descriptor of each application to be protected.

To Install the Agent Filter for the Deployed Application on Agent for JBoss Application Server 4.0

1. Ensure that the application is not currently deployed on JBoss Application Server 4.0.

   If the application is currently deployed, remove it before continuing.

2. Create the necessary backups before proceeding to modify these descriptors.

   Since you will modify the deployment descriptor in the next step, creating backup files at this point is important.

3. Edit 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">

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

   2. Add the following filter element in the web.xml file:

      <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>

   3. Modify the jboss-web.xml and jboss.xml files for the deployed application.

      Specify the value of the security-domain element as AMRealm. For example:

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

   If you want to specify a different value for the realm, set the security-domain element to that value in the jboss-web.xml and jboss.xml files.

Next Steps

You have the option of protecting your application with J2EE declarative security. For more information, seeEnabling Web-Tier Declarative Security in J2EE Agents.

Furthermore, you can learn more about protecting your application with J2EE declarative security by deploying the sample application. Visit the PolicyAgentBase/sampleapp directory to learn how to build and deploy an application. The sampleapp application is by no means a full fledged J2EE application. Rather it is a simple application that provides you with a quick reference to application specific deployment descriptors and various deployment modes of a J2EE agent. Once you successfully deploy sampleapp and test all of its features, you can use it as a reference to other applications that will be protected by the J2EE agent.

Once the web.xml deployment descriptor is modified to reflect the new <DOCTYPE> and <filter> elements, the agent filter is added to the application. You can now redeploy your application on JBoss Application Server 4.0.

Ensure that role-to-principal mappings in container specific deployment descriptors are replaced with Access Manager roles or principals. You can retrieve Access Manager roles or principals for Access Manager 7 by issuing the agentadmin --getUuid command. For more information on the agentadmin --getUuid command, see agentadmin --getUuid.

You can also retrieve the universal ID for the user (UUID) using Access Manager 7 Console to browse the user profile.

Conditional Post-Installation Steps for J2EE Agents in Policy Agent 2.2

Steps described in this section might be required, depending on your site's specific deployment.

Creating the Necessary URL Policies

If the agent is installed and configured to operate in the URL_POLICY mode or ALL mode, the appropriate URL policies must be created. For instance, if JBoss Application Server 4.0 is available on port 8080 using HTTP protocol, at least a policy must be created to allow access to the following resource:

http://myhost.mydomain.com:8080/sampleApp/

where sampleApp is the context URI for the sample application.

If no policies are defined and the agent is configured to operate in the URL_POLICY mode or ALL mode, then no user is allowed access to JBoss Application Server 4.0 resources. See Sun Java System Access Manager 7.1 Administration Guide to learn how to create these policies using the Access Manager Console or command-line utilities.