Examining the J2EE Policy Agent and Installing It on Oracle Application Server 10g

Print-friendly Version

To protect hosted Java 2 Platform, Enterprise Edition (J2EE) applications that may require various security policies, you can install a J2EE Policy Agent (called the Policy Agent for short in the rest of this article). The J2EE security infrastructure provides both declarative and programmatic security, independent of platforms, and is supported by all J2EE platform-compliant application servers.

For details on how to use declarative and programmatic security on the J2EE platform, see the chapter, "Security," in The J2EE Tutorial.

A key function of the Policy Agent is to enable role-to-principal`mapping for protected applications with the principals of Sun Java System Access Manager (formerly Sun Java System Identity Server, called Access Manager for short). Thus, at runtime, evaluation of J2EE policies occurs in accordance with the information available in Access Manager. Subsequently, you can configure applications to be protected by the Policy Agent, which offers security services and other capabilities, such as Single Sign-On (SSO).

In addition, the Policy Agent supports Access Manager-based URL policies for enforcing access control over resources that are hosted in the application server's Web container.

This paper showcases the components of the Policy Agent, its capabilities, and its installation and configuration procedures on Oracle Application Server 10g. This version of the Policy Agent is compatible with Oracle Application Server 9i Release 2.

The Policy Agent contains two main components:

• Agent realm -- A platform component specific to an application server, the agent realm enables the application server to interact with the principals stored in Access Manager. You must correctly configure this component before the Policy Agent can enforce security policies for applications.
  
  
• Agent filter -- The agent filter resides within the protected application and enforces the security policies that govern the access to the application's resources. To use this filter, you must configure the deployment descriptors within the application. The Policy Agent does not protect applications that contain an incorrect setting; in fact, those applications may malfunction or become unusable if deployed to an application server on which the agent realm resides.

To recap, these components work in tandem with Access Manager and enforce authentication and authorization for users who attempt to access protected applications.

To take advantage of some of the Policy Agent's capabilities, you must modify the configurations of your applications. Be sure to become familiar with the installation and configuration procedures described in these two chapters in the J2EE Policy Agents Guide:

• Chapter 2, "Installing the Agent"
  
  
• Chapter 3, "Agent Configuration"

The current release of Policy Agents supports Access Manager-based URL policies that protect Web-tier resources, such as URLs that point to Java Servlets, JavaServer Pages (JSP) content, HTML files, images, and others.

You can install the J2EE Policy Agent to protect hosted J2EE applications. Recall that the J2EE platform infrastructure offers platform-independent declarative and programmatic security for compliant J2EE application servers.

The Policy Agent helps enable role-to-principal mapping for protected J2EE applications with Access Manager principals. Thus, when the application runs, the J2EE policies are evaluated according to the information in Access Manager. You can protect hosted applications by configuring them for the Policy Agent's security services, including SSO and other key features.

The Policy Agent can more tightly secure deployed applications. You can also customize its environment to suit the deployment. Here is a summary of the Policy Agent's capabilities:

• A bus architecture based on the software module
  
  
• Ability to set Lightweight Directory Access Protocol (LDAP) attributes as request headers, attributes, or cookies
  
  
• Ability to reset application cookies on unauthorized access to system resources
  
  
• Remote logging
  
  
• Support for the following:
  • The agent filter's operation modes (for details, see the next section)
  • Failover of the Login and Naming Service
  • Inversion of the Not-Enforced List
  • Protection of single-point redirection loops

Depending on your security requirements, you specify the agent filter's operation mode in the com.sun.am.policy.amFilter.mode property in the agent configuration file. Altogether, there are five modes:

1. NONE
2. SSO_ONLY
3. J2EE_POLICY
4. URL_POLICY
5. ALL

Regardless of the mode, once you have configured the agent realm, it continues to function. If you have configured J2EE security with the agent realm in place, a negative evaluation of J2EE security policies may result in some cases. However, some filter operation modes do not require agent realms.

Note - To learn how to disable the agent realm, see the section on that subject in the J2EE Policy Agents Guide.

The following subsections describe the agent filter modes.

The NONE operation mode effectively disables the agent filter, which then allows all requests to pass through. However, if logging is enabled, the agent filter still logs all the requests that it intercepts.

This mode does not require the agent realm.

The SSO_only mode is the least restrictive mode. In this mode, the agent filter authenticates all the users who try to access protected Web resources with Access Manager's authentication service.

You can safely disable the agent realm; it's not in use in this mode.

In the J2EE_POLICY mode, the agent filter and agent realm work together with Access Manager to ensure the correct evaluation of J2EE policies. You can set these policies either in the application's deployment descriptors or, in cases where the application uses the J2EE programmatic security APIs, in the application code. URL policies that are defined in Access Manager do not take effect in this mode.

If the application uses declarative security in the Web tier, you must configure the agent to enable that feature. For details, see "Enabling Web-Tier Declarative Security" in the J2EE Policy Agents Guide.

While running in the J2EE_POLICY mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.

This mode requires that you configure the agent realm in the application server.

In the URL_POLICY mode, the agent filter enforces the URL policies that are defined in Access Manager. This mode does not require the agent realm to be functional; you can safely disable the realm.

The ALL mode is the most restrictive mode: The filter enforces both the J2EE policies and URL policies that are defined in Access Manager. This mode requires that you configure the agent realm in the application server. When running in this mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.

We strongly recommend that you use the ALL mode for deployed production systems. This mode requires that you configure the agent realm in the application server.

With the Policy Agent tools, you can configure the Policy Agent for new application server instances, where supported. You can also encrypt plain text strings--sometimes a necessary step for changing passwords.

For details, see "Agent Tools" in the J2EE Policy Agents Guide.

The Policy Agent runtime provides access to all the Access Manager APIs that can further enhance the security of applications. On top of these APIs are APIs that enable applications to locate the SSO token string that is associated with the user who is logged on. You can use the APIs from either within the Web container or the Enterprise JavaBeans (EJB) container of the application server.

For details, see "Agent APIs" in the J2EE Policy Agents Guide.

Nowadays, most vendors that integrate with Oracle's application server perform simple SSO integrations. By providing five different operation modes, the Policy Agent by far surpasses its competitors in robustness. The J2EE_POLICY mode provides a framework to protect applications with support for fine-grained declarative and programmatic security. URL policies constitute a framework for enforcing those policies for resources hosted on the application server. The ALL mode offers a combination of three modes (SSO, URL_POLICY, and J2EE_POLICY) that work simultaneously to safeguard applications.

The Policy Agent is built on a software bus architecture that enables Internet service providers (ISPs) to plug in software modules on a common bus. The architecture's hierarchical data design supports hot-swapping configuration data at runtime. In addition, the framework contains built-in features that shield against misconfigurations that may lead to infinite loops or denial-of-service attacks.

Above all, the Policy Agent for Oracle Application Server 10g is a unique mechanism that protects two virtual machines (the OC4J instance and the Enterprise Manager instance), which run on two separate ports, with the same instance of the Policy Agent.

This section describes the procedures before and after installing the Policy Agent on Oracle Application Server 10g.

Before installing the Policy Agent for Oracle Application Server 10g, do the following:

1. Stop all the related processes.
   
   Not stopping all the Oracle-related processes, such as emctl, opmnctl, and dcmctl, can cause the Policy Agent to malfunction and portions or all of the application to become inaccessible.
   
   
2. Ensure that you have configured the front-end Apache Web server to have a fully qualified host name.
   
   Otherwise, the host name in the httpd.conf file in the Apache Web server would be in error.
   
   To perform that configuration, start the Oracle Universal installation program with the following command line:
   
   % ./runInstaller OUI_HOSTNAME=fully_qualified_hostname
   
   
3. Optional. If you installed Oracle Application Server 10g without specifying a value for the variable OUI_HOSTNAME, change the value for the variable ServerName in the $ORACLE_HOME/Apache/Apache/conf/httpd.conf file to be the fully qualified host name.
   
   An incorrect value in the ServerName variable in the httpd.conf file causes the Policy Agent to malfunction and portions or all of the application to become inaccessible.

Once installation is complete, do the following:

• Create the Oracle Application Server 10g administrative users and roles in Access Manager.
  
  
• Install the agent filter for the deployed application.
  
  
• Install the application from the Enterprise Manager Console.

The following subsections contain more details.

Creating Oracle Application Server 10g Administrative Users and Roles

By default, the installation program configures a second agent to protect Enterprise Manager. Without that agent, Enterprise Manager supports basic authentication with the default realm from Oracle Application Server 10g. The Policy Agent, however, modifies Enterprise Manager's web.xml file to support FORM-based authentication. Therefore, when you authenticate with Enterprise Manager for the first time, it redirects you to the Access Manager Console to authenticate as the administrator.

To enable users to authenticate with Enterprise Manager and perform tasks from its console, you must create two users and two related roles in Access Manager:

The document "Identity Management" details how to create users and roles and add users to roles in Access Manager.

Reminder - After creating the two users, add the ias_admin user to the role ias_admin and the admin user to the role administrators.

Installing the Agent Filter for Deployed Applications

You can install the agent filter by editing the deployment descriptor of the application you'd like to protect.

Note the following:

• When installing the agent filter, ensure that the application is not currently deployed on the application server. If the application is deployed, delete it before proceeding.
  
  
• Before editing the deployment descriptor, create a backup copy--always a prudent practice to adopt.

Follow this procedure:

1. Edit the application's web.xml descriptor, as follows:
   
   Because the filters were introduced in Servlet Specification 2.3, you must revise the web.xml file's DOCTYPE element to reflect that the deployment descriptor complies with Servlet 2.3. Do so by setting the DOCTYPE element this way:
   
   

   <!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 filter elements to the deployment descriptor.

   Do so by specifying the filter and the filter-mapping elements that immediately follow the description element of the web-app element in the descriptor web.xml. Here is a sample descriptor that includes those two elements.

   CODE EXAMPLE 1 Sample web.xml Descriptor

   <web-app> <display-name>...</display-name> <description>...</description> <filter> <filter-name>Agent</filter-name> <display-name>Agent</display-name> <description>Sun Java System Access Manager Policy Agent Filer</description> <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>

   
   

3. Add the agent filter to the web.xml file.

You can then redeploy your application on the application server.

For details on sample deployment descriptors specific to Oracle Application Server 10g, see "Assembly Descriptors" in the J2EE Policy Agents Guide.

Installing Applications from Enterprise Manager Console

You can now deploy the application from the Enterprise Manager Console or the dcmctl tool. Here is the procedure. (Access requires a preregistered, free account on otn.oracle.com.)

As you progress through the installation, you'll notice that Enterprise Manager has installed a custom User Manager (com.sun.identity.agents.oracle.AmOracleUserManager) and has selected it as a default option. Do not change that option. This User Manager is the Access Manager-specific realm that is installed by the Policy Agent.

While installing the Policy Agent for Oracle Application Server 10g, the installation program configures a second agent in the J2EE_POLICY mode to protect Enterprise Manager, which is in essence a Web application for the Oracle Application Server 10g Console. The section "Agent Filter Modes" in the J2EE Policy Agents Guide contains details on the modes.

For Enterprise Manager

The installation program does not inquire about the protocol or the port of Enterprise Manager. Instead, it assumes a default protocol (http) and a default port number (1810). To change those two properties, do the following:

1. Edit the Policy Agent's configuration file AMAgent.properties.
   
   On the Solaris platform, depending on the instance of the application server to which this file applies, the file resides in a directory under /etc/opt/SUNWam/j2ee_agents. On other platforms, this file resides in a directory under Agent_install_dir/j2ee_agents/config.
   
   For example, if Enterprise Manager is running on https instead of http, make this line in the file read:
   
   com.sun.am.policy.amFilter.port.check.map[1810]=https
   
   Since this property is hot-swappable, you need not restart Enterprise Manager for the changes to take effect.
   
   
2. Edit the file ORACLE_HOME/bin/emctl.
   
   For example, to add session notifications for the modified port or protocol, change the -D java option in the file to read as follows (all on one line):
   
   -Dcom.iplanet.am.notification.url=
http://hostname.domainname:1810/emd/notification
   
   Another example: If Enterprise Manager is running on https instead of http, set the -D java option as follows (all on one line):
   
   -Dcom.iplanet.am.notification.url=
https://hostname.domainname:1810/emd/notification
   
   Restart emctl for the changes to take effect.

Once you have installed the Policy Agent, you can configure it to accomplish the following:

• Customize deployment to enhance the deployed and protected applications and the performance of the entire system.
  
  
• Fine-tune the security policies according to your needs.

In fact, to enable some of the Policy Agent's capabilities, such as Web-tier declarative security support, you must perform several additional configurations for Oracle Application Server 10g applications, as described in "Enabling Web-Tier Declarative Security" in the J2EE Policy Agents Guide.

The Policy Agent's configuration is largely controlled by the properties in the AMAgent.properties file. See step 1 in the preceding section for the location of the file.

For more details on configuring Policy Agents, see Chapter 3, "Agent Configuration," in the J2EE Policy Agents Guide.

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Collection of documentation
    
• J2EE Policy Agent for Sun Java System Access Manager
  • J2EE Policy Agents Guide
  • Release Notes
    
• Oracle Application Server 10g
  • Main page
  • Documentation

Krishnendu Chakraborty, a member of the Sun Java System Access Manager development team, joined Sun four years ago after a stint at Oracle. He has programmed extensively with Java, HTTP, XML, and database technologies.

Arvind Prabhakar has been working with the J2EE platform since 1997. He's the architect of J2EE Policy Agents for Access Manager.

Marina Sum is a staff writer for Sun Developer Network. She has been writing for Sun for 15 years, mostly in the technical arena.