test

Sun Java System Access Manager Policy Agent 2.2 Guide for Apache Tomcat 5.5 Servlet/JSP Container

What’s New About J2EE Agents

J2EE agents offer greater functionality in the 2.2 release. Several important new features have been added as follows:

Removal of J2EE Agent Dependency on LDAP and on Administrative Accounts

In the 2.2 release, certain restrictions have been removed as follows:

Removal of J2EE Agent Dependency on LDAP

Unlike previous releases, J2EE agents in the Policy Agent 2.2 release do not use a direct LDAP connection. Instead, J2EE agents obtain support for their entire functionality by communicating with Access Manager solely with XML over HTTP.

Benefit - Removal of Dependency on LDAP: The benefit of not having an LDAP dependency includes greater flexibility and scalability of deployments. Since J2EE agents no longer depend on LDAP connections, they do not require the opening of LDAP communication ports in firewalls, which was a requirement with certain deployment scenarios in prior J2EE agent releases. With the LDAP dependency removed, the 2.2 release of J2EE agents requires fewer configuration changes during installation in protected regions, such as in a demilitarized zone (DMZ), giving more deployment flexibility and easing administrative overhead. Removal of the LDAP dependency also ensures that LDAP server resources are focused to support Access Manager instances. A focus on Access Manager instances facilitates the sizing process by eliminating considerations about the load that an agent would require. This makes the deployment easily scalable and more flexible and provides the optimal utilization of deployed resources.

Removal of J2EE Agent Dependency on Administrative Accounts

With the authorization of administrators now being handled by an agent profile account, the dependence on two administrative accounts, the amAdmin account and the amldapuser account, has been removed. Now, during installation, the agent installer prompts you for the agent profile account.

Benefit - Removal of Dependency on Administrative Accounts: The benefit of not using the amAdmin or amldapuser administrative accounts is greater security. The 2.2 release of J2EE agents depends solely on a limited agent profile. This dependence does not rely on the existence of sensitive account information in the agent deployment configuration.

Enhanced J2EE Agent Installation Process

Starting with this release of J2EE agents, the installation process includes the following features that allow for a smoother, less restrictive, more secure installation process and deployment:

J2EE Agent Support for Installation Using Non-Administrative User Accounts

The requirement in prior agent releases that the installation user have root (or Administrator) privileges has been removed. The agent can now be installed by any user regardless of access privileges.

Benefit - Support for Installation Using Non-Administrative User Accounts: The benefit of this feature is that it contributes to a more flexible installation process. Because privileged user accounts are not required, you can install agents in any directory location based on user preferences.

Secure Handling of Sensitive Information by J2EE Agents

All sensitive information, such as passwords, is now read from files. This information is not typed in clear text during an interactive session. Therefore, it is never displayed on the command line or in any logs. See Using the Installation Program of Agent for Apache Tomcat Servlet/JSP Container for information about creating and using a password file during the agent installation process.

Benefit - Secure Handling of Sensitive Information: The benefit of this feature is increased security. With the use of this feature in the new installation process, the need for typing passwords in clear text on the console has been eliminated, thereby making the installation process less vulnerable to password theft.

Self-Contained Installation of J2EE Agents

All J2EE agent configuration and log files are generated and maintained within an agent’s installation directory. This installation directory is referred to as the Policy Agent base directory. In code examples this directory is listed as such, PolicyAgent-base. For more information about the Policy Agent base directory, see J2EE Agent Directory Structure in Policy Agent 2.2. The distribution files for the 2.2 release of J2EE agents are provided to you in three formats. You can choose the format that best fits your needs: zip format, tar format, or a package format. The files are small in size since the installer for this release uses a simple configuration mechanism. In summary, when you unpack the binaries, the configuration and log files remain within the installation directory.

Benefit - Self-Contained Installation: This feature contributes to a more flexible installation process. The fact that an installation is self-contained facilitates the installation process and the subsequent administration process.

J2EE Agent Support for Multiple Physical Installations

There is no longer any restriction on using multiple different binaries of the same agent on the same machine.

Benefit - Support for Multiple Physical Installations: This feature contributes to a more flexible installation process. The fact that multiple binaries of the same agent can co-exist on the same machine allows for flexibility in securing complex environments where more than one server is installed on the same machine. Typically such environments are used for development purposes or for production using high capacity hardware systems.

J2EE Agent Coexistence With Access Manager

Starting with this release, you can deploy a J2EE agent on an instance of a deployment container where Access Manager has already been installed. This situation only applies when the J2EE agent and Access Manager both support the deployment container.

Note that Access Manager should be installed prior to the agent being installed.

Benefit - Coexistence With Access Manager: Certain situations benefit from having a J2EE agent and Access Manager on one machine, which is commonly desired for development environments and for environments where the deployment container is installed on a high capacity system which can support customer applications along with the Access Manager deployment.

J2EE Agent Support for Client Identification Based on Custom HTTP Headers

Starting with this release, J2EE agents can be configured to use custom HTTP headers to identify the remote client IP address and host name. This client IP address is used to validate an Access Manager session or to evaluate applicable policies.

Benefit - Support for Client Identification Based on Custom HTTP Headers: This feature is specially useful in situations where a proxy server exists between the remote client and the agent-protected server. In such situations a problem occurs in that the client address information carried within the request is replaced by the address information of the proxy server. This address replacement adversely affects session validations and policy evaluations, which depend upon the correct address information. However, when proxy servers can be configured to send the actual client address information in separate headers, then J2EE agents in the 2.2 release can use that information. In summary, this feature allows agents to use the actual client address information in this type of deployment as if the request were never intercepted by an intermediate proxy server.

J2EE Agent Specific Application for Housekeeping Tasks

Starting with this release of J2EE agents, a bundled application is available to perform housekeeping tasks on the deployment container.

This bundled application, when deployed on an agent-protected deployment container instance, expands the agent’s functionality. For example, this bundled application allows the agent to receive notifications and to support cross-domain single sign-on. In previous releases, this functionality was tied to an application referred to as the primary application, which was secured by the agent.

Benefit - Agent Specific Application for Housekeeping Tasks: The benefit of including this application with J2EE agents is that previously imposed restrictions have been removed from the primary application. In prior releases of J2EE agents, the primary application had to support such housekeeping tasks, often requiring additional configuration. For instance, in prior releases, deploying the primary application with blind web-tier declarative security required changes to the agent configuration to ensure that the agent would function properly. This additional configuration is not necessary with the current release since the agent-specific application for housekeeping tasks takes care of all such functionality.

J2EE Agent URL Policy Enhancements

Starting with this release of J2EE agents, the following features are available that enhance Uniform Resource Locator (URL) policy:

The aforementioned features affect how agents enforce policy decisions. These features are described in the following paragraphs.

Remote Policy Evaluation Failover in J2EE Agents

J2EE agents can now leverage session failover functionality to ensure that remote policy evaluation failover can occur if an Access Manager instance becomes unavailable.

Benefit - Remote Policy Evaluation Failover: The benefit of this feature is the potential for a seamless user experience in the event of a failure or maintenance related outage of various servers within the Access Manager deployment.

Configurable Policy Evaluation Mechanism in J2EE Agents

Starting with this release, J2EE agents can be configured to use two different mechanisms to remotely evaluate policies as follows:

Benefit - Configurable Policy Evaluation Mechanism: The configurable policy evaluation mechanism has a variety of benefits depending on the situation. The very fact that you can configure the policy evaluation mechanism is beneficial in that it enables you to choose the mechanism that best fits your needs. Moreover, each mechanism has its advantages and disadvantages.

When configured to perform policy evaluation for all resources within an agent’s scope of protection the first request is, by design, time consuming while subsequent requests are faster since the results get cached locally by the agent.

For the second mechanism, the first request is no slower or faster than subsequent requests. All requests are processed relatively quickly. However, this mechanism increases network communication between the agent and Access Manager. Furthermore, the two mechanism can produce different types of cache growth in agent memory and thus need to be evaluated closely to select the best option for your deployment. Key factors that could affect such a decision include the number of possible distinct resources and the number of policies applicable to an average user.

Composite Advice in J2EE Agents

In the 2.2 release, J2EE agents provide a composite advice feature. This feature allows the policy and authentication services of Access Manager to decouple the advice handling mechanism of the agents. This allows you to introduce and manage custom advices by solely writing Access Manager side plug-ins. Starting with this release, you are not required to make changes on the agent side. Such advices are honored automatically by the composite advice handling mechanism.

Benefit - Composite Advice: A benefit of composite advice is that you can incorporate a custom advice type without having to make changes to an agent deployment.

Policy Based Response Attributes in J2EE Agents

The policy-based response attribute feature allows the policy service to provide static and dynamic attributes based on the resource accessed by the user. These attributes can be made available to the agent protected application as HTTP headers, request attributes, or cookies.

Benefit - Policy Based Response Attributes: A benefit of the policy-based response attribute feature is that it provides more flexible support for application-specific agent customizations compared to prior Policy Agent releases, which only allowed for static profile attributes to be fetched.

J2EE Agent Support for Flexible User Mapping Mechanisms

Starting with this release, J2EE agents provide support for user mapping modes that have flexibility in the user names they choose. In prior releases, a user name had to be an Access Manager user ID. Now, user names can be chosen from a few different sources as long as the names are for authenticated users who have trusted identities. A trusted identity can be established on the agent-protected server for a security principal (or for an equivalent trusted identity of the user). This mechanism allows the agent to choose a user ID for the authenticated user from the user’s profile attributes, the user’s session properties, or an HTTP header accompanying the user request.

Benefit - Support for Flexible User Mapping Mechanisms: The main benefit of this feature is that it enables a J2EE agent to integrate with a greater number of applications. Some applications do not accept Access Manager user IDs as user names. J2EE agents can now integrate with those applications since Policy Agent 2.2 can be configured to provide different types of user names.

J2EE Agent Support for Fetching User Session Attributes

Before this release of J2EE agents, information for HTTP headers, request attributes, or cookies was retrieved, or sourced, solely from profile attributes. Now, this information can also be sourced from session properties.

Benefit - Support for Fetching User Session Attributes: The benefit of this feature is that session properties can be more effective for transferring information, especially dynamic information. Prior to this release, agents could only fetch users’ profile attributes, which tend to be static attributes. However, session attributes allow applications to obtain dynamic user information when necessary.

J2EE Agent Support for Version Checking

Starting with this release of J2EE agents, you can easily check the exact version of the agent you are using, including build date, build number, and client SDK version. Prior to this release, administrators could not easily identify the build date of the agent they were using. Since code changes occur between build dates, identifying the exact build can be useful. For the details on how to check the version of an agent instance, see agentadmin --version.

Benefit - Support for Version Checking: The benefit of this feature is that it allows you to quickly check the version of the J2EE agent you are using, enabling you to determine which features and bug fixes are included.

J2EE Agent Support for Not-Enforced IP List

Starting with this release, J2EE agents support not-enforced IP lists. This new feature is similar to a pre-existing Policy Agent feature that also concerns not-enforced lists, specifically not-enforced URI lists.

The two features share similarities, but are really quite different. Again, the pre-existing feature supports not-enforced URI lists. With that feature, an agent always grants access to a URI that appears on a specified list in the J2EE agent AMAgent.properties configuration file. On the other hand, the new feature supports not-enforced IP lists. With this feature, an agent always grants access to resources when the request comes from a machine with an IP address that appears on a specified list in the J2EE agent AMAgent.properties configuration file.

With the new feature, when a request is made to access a resource, a J2EE agent determines the IP address of the machine where the request originated. The agent compares that IP address to all the addresses on the not-enforced IP list. If that address is on the list, then that request and all subsequent requests from that IP address are treated as if the resources requested are not enforced.

The not-enforced IP list can include exact IP addresses and IP addresses that use the asterisk, *, wildcard character to represent one or more characters.

Benefit - Support for Not-Enforced IP Lists: The benefit of this feature is that it allows clients on the not-enforced IP list to by-pass authentication and authorization requirements. This feature can be employed for administrative, troubleshooting, and testing purposes, too.

J2EE Agent Support for Custom Response Headers

Starting with this release, J2EE agents provide support for custom response headers. The agent can be configured so that custom response headers are set on every request. Such headers are defined statically in the J2EE agent AMAgent.properties configuration file and are honored on all enforced web resources as identified by the agent.

Benefit - Support for Custom Response Headers: The benefit of this feature is that it enables instructions, by way of custom response headers, to be sent to a client or any intermediate entity between the agent-protected server and the client browser. For example, a custom response header could be sent instructing an intermediate proxy server not to cache server responses to client requests.

J2EE Agent Support for Application Logout Integration

Starting with this release, J2EE agents can be configured to identify an application logout event and to synchronize the event with the Access Manager logout. The agent can identify the logout of an application based on preconfigured information sent with a request as follows:

Benefit - Support for Application Logout Integration: The benefit of this logout integration feature is that end users can potentially perform a global log out by simply logging out of an application. Also, J2EE agents, starting with the 2.2 release, are very flexible in terms of the variety of ways they can identify the log out of an application. This flexibility facilitates the integration between J2EE agents and applications since applications will rarely need any modifications to enable them to match any requirements of the agent.

J2EE Agent Support for Application Specific Agent Filter Operation Modes

The application-specific filter operation mode mechanism allows different applications to use different levels of protection as necessary. Different filter operation modes provide different levels of functionality, thus enabling the selection of the best mode for each protected application.

Benefit - Support for Application Specific Agent Filter Operation Modes: This feature provides customized protection for every application. For example, if two applications are deployed where one uses J2EE policies and the other does not, the agent can be configured to use different filter modes for each application. The agent will provide support for J2EE policies, but only for the application that has such policies. The results is the optimal use of system resources since the agent does not enforce the evaluation of J2EE policies for the application that does not have any J2EE policies.

J2EE Agent Support for Affinity-Based Login URL Selection

Starting with this release, J2EE agents support a prioritized (or an affinity-based) selection of login URLs for authenticating users. End users are directed to the URL highest on the list if it is available. If not, the second URL on the list is targeted. If a URL higher on the list becomes available again, the agent switches to that URL.

You can disable this affinity-based selection process if desired, which would allow you to use a round-robin selection scheme.

Benefit - Support for Affinity-Based Login URL Selection: This feature is used when two or more Access Manager instances are deployed in geographically distant locations. To best manage the authentication process, you can give the highest priority to URLs of locally available Access Manager instances, resulting in faster response times.

J2EE Agent Support for a Sample Application

Starting with this release, the J2EE agents provide a bundled sample application to demonstrate the key features and functionality of the agent. Some of the features demonstrated are:

For more information about the sample application, see The Sample Application and see the list following Table 2–2 for information about locating the sampleapp directory within the J2EE agent base directory. The sampleapp directory includes instructions on how to use the sample application.

Benefit - Support for a Sample Application: The sample application illustrates how applications need to be configured to take advantage of the protection that agents provide. The sample application also demonstrates how key functionality, such as support for J2EE security and Access Manager based URL policies, can be used.

J2EE Agent Backward Compatibility With Access Manager 6.3

Policy Agent 2.2 is backward compatible with Access Manager 6.3 Patch 1 or greater.

Note –

Policy Agent 2.2 is only compatible with Access Manager 6.3 when the Access Manager patch has been applied.

By default, J2EE agents in the Policy Agent 2.2 release work with Access Manager 7. While the 2.2 release of Policy Agent requires some configuration to work with Access Manager 6.3 Patch 1 or greater, the amount of configuration required is relatively limited. For more information, see Configuring A J2EE Agent With Access Manager 6.3.

Be aware that Policy Agent 2.2 takes advantage of certain features that exist in Access Manager 7 that do not exist in Access Manager 6.3, such as “composite advices,” “policy-based response attributes,” and others.