Chapter 4 Post-Installation Tasks of Policy Agent 2.2 for Oracle Application Server 10g

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 Oracle Application Server 10g

• 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 Oracle Application Server 10g.

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 Oracle Application Server 10g.

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.

Deploying the Agent Application for J2EE Agents in Policy Agent 2.2

The task described in this section is required. Deploy the URI for the agent application using the deployment container. The agent application is a housekeeping application used by the agent for notifications and other internal functionality. This application is bundled with the agent binaries and can be found at the following location:

PolicyAgent-base/etc/agentapp.extension

where extension refers to the .war extension or the .ear extension. The extension varies depending on the deployment container.

For more information about the Policy Agent base directory (PolicyAgent-base), see J2EE Agent Directory Structure in Policy Agent 2.2.

Restart the Oracle Application Server 10g instance before you deploy the agent application. If you do not restart the server, the deployment of the agent application will fail.

The agentapp application has to be deployed as a post installation step. In order for the agent to function correctly, this application must be deployed on the agent-protected deployment container instance using the same URI that was supplied during the agent installation process (optionally, you can add a hyper link to and from the relevant prompt). For example during the installation process, if you entered /agentapp as the deployment URI for the agent application, then use that same context path to deploy the .war or .ear file in the deployment container.

Using the administration console or command-line utilities of your deployment container, deploy this application using Application Context Path as the URI specified during agent installation.

Post-Installation Steps Specific to Agent for Oracle Application Server 10g

Once you have installed Policy Agent 2.2 for Oracle Application Server 10g 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.

• Installing the Agent Filter for the Deployed Application on Agent for Oracle Application Server 10g

• Protecting an Application With the Filter Mode Set to J2EE_POLICY or ALL For the Oracle Application Server 10g Agent

Installing the Agent Filter for the Deployed Application on Agent for Oracle Application Server 10g

The agent filter can be installed by modifying the deployment descriptor of each application to be protected.

To Install the Agent Filter for the Deployed Application on Agent for Oracle Application Server 10g

The following steps explain how to install the agent filter for an application you want the agent to protect.

1. Ensure that the application is not currently deployed on Oracle Application Server 10g.

   If it is currently deployed, remove it before proceeding any further.

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-INF/web.xml descriptor as required:

   You must change the <DOCTYPE> element and you must add filter elements to the web.xml descriptor.

   The <DOCTYPE> element of the web.xml descriptor must be changed to reflect that the deployment is, at minimum, a servlet 2.3 compliant deployment descriptor.

   The filters were introduced in Servlet Specification 2.3. For more information about this specification visit the following web page: http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html

   1. Edit the <DOCTYPE> element of the web.xml descriptor as required.

      The following is an example of how the <DOCTYPE> element should appear after editing:

      <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

   2. Add the required filter elements to the web.xml descriptor at the first filter definition.

      The following example demonstrates the <filter> elements to be added:

      <web-app> ... <filter> <filter-name>Agent</filter-name> <display-name>Agent</display-name> <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class> </filter> <filter-mapping> <filter-name>Agent</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> ... <web-app>

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. Change directories to 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 Oracle Application Server 10g.

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.

Protecting an Application With the Filter Mode Set to J2EE_POLICY or ALL For the Oracle Application Server 10g Agent

The steps in this section are required if the filter mode (com.sun.identity.agents.config.filter.mode property) is set to J2EE_POLICY or ALL (which is the default value set during the agent installation).

Perform these steps for each application to be protected by the version 2.2–02 Oracle Application Server 10g agent, including the sample application.

To Protect an Application With the Filter Mode Set to J2EE_POLICY or ALL For the Oracle Application Server 10g Agent

1. If the application is already deployed, undeploy it.

   Then, find the application's EAR file with its internal source files, including files within the WAR and JAR files.

2. Edit the WAR file's WEB-INF/web.xml file as follows:

   1. Add the following filter descriptors as the first filter definition:

      <filter id="Filter_PolicyAgent"> 
      <filter-name>Agent</filter-name> 
      <display-name>Agent</display-name> 
      <description>J2EE Policy Agent Filter</description> 
      <filter-class> 
      com.sun.identity.agents.filter.AmAgentFilter 
      </filter-class> 
      </filter> 
      <filter-mapping id="FilterMapping_PolicyAgent"> 
      <filter-name>Agent</filter-name> 
      <url-pattern>/*</url-pattern> 
      </filter-mapping> 

   2. Since filters were introduced in Servlet specification 2.3, the web.xml file's <DOCTYPE> element must indicate that the deployment descriptor is a Servlet 2.3 compliant deployment descriptor, as follows:

      <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application2.3//EN" 
      "http://java.sun.com/dtd/web-app_2_3.dtd"> 

3. If the application has specified declarative security in the web.xml or ejb-jar.xml file, perform these steps:

   1. Add the following entry in WEB-INF/web.xml:

      <login-config> 
      <auth-method>FORM</auth-method> 
      <form-login-config> 
      <form-login-page>/jsp/oracle10g_login.jsp</form-login-page> 
      <form-error-page>/authentication/accessdenied.html</form-error-page> 
      </form-login-config> 
      </login-config>

   2. Copy the sampleapp/docroot/jsp/oracle10g_login.jsp file to the application's WAR file jsp directory.

   3. Copy the sampleapp/docroot/authentication/accessdenied.html file to the application's WAR file authentication directory.

      Note: If you wish, you can customize these two files and put them into different directories for the application. Refer to the various application files under sampleapp/etc for the sample application.

4. Add the following entry to the application's META-INF/orion-application.xml file:

   <jazn provider="XML"> 
   <property name="role.mapping.dynamic" value="true"/> 
   <property name="custom.loginmodule.provider" value="true" /> 
   </jazn>

   Or, if the application has an existing jazn-data.xml file in its META-INF directory, add this entry:

   <jazn provider="XML" "location="./jazn-data.xml"> 
   <property name="role.mapping.dynamic" value="true"/> 
   <property name="custom.loginmodule.provider" value="true" /> 
   </jazn>

5. Repackage the application with the changes you have made.

6. Redeploy the application through the Oracle 10g Enterprise Manager. Note the application name, which is required in a later step.

   • On the “Deploy Application: User Manager” screen, select “Use JAZN XML User Manager”.

   • Leave the “Default Realm” empty and “XML Data” as /jazn-data.xml, which are the defaults.

7. Add the following entry to oracle_home/j2ee/home/config/jazn-data.xml or oracle_home/j2ee/instance/config/jazn-data.xml:

   <application> 
   <name>application-name</name>
   <login-modules> 
   <login-module> 
   <class>com.sun.identity.agents.oracle.v1012.AmOracleLoginModule</class> 
   <control-flag>required</control-flag> 
   <options> 
   <option> 
   <name>debug</name> 
   <value>true</value> 
   </option> 
   </options> 
   </login-module> 
   </login-modules> 
   </application> 

   Note: For <name>application-name</name>, specify the application name within the Oracle 10g instance from Step 6.

8. Add the URL policies from Access Manager. You also must grant permissions to those users for this application's URLs.

   For information about specifying URL policies in Access Manager, see Chapter 8, Managing Policies, in Sun Java System Access Manager 7 2005Q4 Administration Guide.

9. In AMAgent.properties, set the com.sun.identity.agents.config.filter.mode property to the proper mode, such as J2EE_POLICY or ALL.

10. Restart both the Access Manager server and the Oracle 10g instance.

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 Oracle Application Server 10g 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 Oracle Application Server 10g resources. See Sun Java System Access Manager 7 2005Q4 Administration Guide to learn how to create these policies using the Access Manager Console or command-line utilities.