The Sun JavaTM System Access Manager Policy Agent 2.2 software set includes web agents and Java 2 Platform Enterprise Edition (J2EE) agents. This guide discusses J2EE agents, the functionality of which has increased for this release. This chapter provides a brief overview of J2EE agents in the 2.2 release as well as some concepts you need to understand before proceeding with a J2EE agent deployment. For a general introduction of agents, both J2EE agents and web agents, see Sun Java System Access Manager Policy Agent 2.2 User’s Guide.
This term is used throughout this book to refer to a J2EE-compliant container that is either an application server or a portal server.
As was true in previous releases, J2EE agents enable deployment containers to enforce authentication and authorization using Sun Java System Access Manager services. To ensure secure client access to hosted J2EE applications, J2EE agents enforce the following:
J2EE Declarative and Programmatic Security (defined in the deployment descriptor of individual applications)
URL Policies (defined in Access Manager)
Single sign-on (SSO)
This chapter provides information about J2EE agents for the 2.2 release of Policy Agent as follows:
J2EE agents can protect a variety of hosted J2EE applications, which can in turn require policy implementation that varies greatly from application to application. The security infrastructure of J2EE provides declarative as well as programmatic security that is platform-independent and is supported by all the J2EE-compliant deployment containers. For details on how to use the declarative and programmatic security of the J2EE platform, refer to J2EE documentation, available at http://java.sun.com/j2ee
The way J2EE agents are used has not changed significantly in the 2.2 release. The agents perform more effectively and efficiently in this release, but the basic functions are the same.
J2EE agents help enable role-to-principal mapping for protected J2EE applications with Access Manager principals. Thus at runtime, when a J2EE policy is evaluated, it is done against the information available in Access Manager. Using this functionality, administrators can configure their hosted J2EE applications to be protected by the agent, which provides real security services and also other key features such as single sign-on. Apart from enabling the J2EE security for hosted applications, the J2EE agents also provide complete support for Access Manager based URL policies for enforcing access control over web resources hosted in the deployment container.
The following examples demonstrate how the J2EE agents can be put to use:
Consider a web-based application that facilitates the auction of various kinds of merchandise between interested parties. A simple implementation for such an application will require the users to be in one of three abstract roles, namely Buyer, Seller, or Administrator. Buyers in this application will have access to web pages that display the listed auction items, whereas the Sellers may have access to web pages that allow them to list their merchandise for new auctions. The Administrators may have access to yet another set of web pages that allow them to finalize or cancel existing auctions in whatever state they may be in. Using the deployment descriptors, the application developer can express this intent by protecting such components using abstract security role names. These abstract role names in turn can be mapped to real principals in a J2EE agent. For example, the role Buyer may be mapped to an Access Manager role called Employee, the role Seller to an Access Manager role called Vendor, and the role Administrator to an Access Manager role called Admin. The abstract role names used by the application developer can be used to protect the necessary web pages and any specialized Enterprise JavaBeans (EJB) components from unauthorized access by using declarative as well as programmatic security. Once this application is deployed and configured, the agent will ensure that only the authorized personnel get access to these protected resources. For example, access to the pages meant for Sellers to list their merchandise for auctions will be granted to user Deepak only if this user belongs to the Access Manager role called Vendor. Similarly, users Scott and Gina can place bids on this listed item only if they belong to the role called Buyer. Once the auction period expires, the auction can be finalized by user Krishnendu only if he is in the role called Admin.
A web-based commerce application may have a variety of specialized EJB components that offer a spectrum of services to clients. For instance, there could be a specialized component that enables the creation of purchase orders. Similarly, there could be a specialized component that allows the approval of purchase orders. While such components provide the basic business services for the application to function, the very nature of tasks that they accomplish requires a security policy to enforce appropriate use of such services. Using the deployment descriptors, the application vendor or developer can express this intent by protecting such components using abstract security role names. For example, a developer can create a role called Buyer to protect the component that allows the creation of a purchase order and a role called Approver to protect the component that enables the approval of a purchase order. While these roles convey the intent of an application developer to enforce such security policies, they will not be useful unless these abstract role names are mapped to real life principals such as actual users or actual roles that reside in Access Manager. The J2EE agent enables the container to enforce such a runtime linkage of abstract security roles to real life principals. Once the agent is installed and configured, the application security roles can be mapped to real principals. For example, the role Buyer is mapped to an Access Manager role called Staff, and the role Approver is mapped to an Access Manager role called Manager. Thus when user Arvind tries to access the application's protected resources to create a purchase order, the agent allows this access only if this user is a member of the mapped role Staff. Similarly, a user Jamie may wish to approve this purchase order, which will be allowed by the agent only if this user is a member of the mapped role Manager.
A content-based web application can offer pay per-view services. The application may be partitioned into two domains: the public domain that is accessible to anonymous users, and the private domain that is accessible only to the subscribers of this particular service. Furthermore, the protected domain of this application can also be subject to strict conditions based on how the user has authenticated, the time of day, IP address-based conditions and so on. Using Access Manager based URL policies for web resources, an administrator specifies such complex policies for the application resources, which are evaluated by the agent in order to ensure that access to these resources is granted only when all conditions are satisfied. An administrator can set policies that govern access to these resources at any level of granularity, such as that for a single user or for an entire organization. For example, one such policy may govern access to certain resources in such a manner that the user must belong to a particular LDAP Group called Customer and that the time of the day be between 9:00 am and 5:00 p.m. Thus, if user Rajeev attempts to access this resource, the agent allows access only if this user is a member of the LDAP Group Customer, and if the time of day is between 9:00 am and 5:00 p.m.
All J2EE agents communicate with Access Manager by XML over HTTP. J2EE agents contain two main components: The agent realm and the agent filter. Together, these two components affect the operation of the deployment container and the behavior of protected applications on the deployment container.
The agent realm, which is installed as a deployment container-specific platform component, enables the deployment container to interact with principals stored in Access Manager. The deployment container then communicates with Access Manager about user profile information. The agent realm needs to be configured correctly for the agent to enforce J2EE security policies for protected applications.
The agent filter is installed within the protected application and facilitates the enforcement of the security policies, governing the access to all resources within the protected application. Every application protected by the agent must have its deployment descriptors changed to reflect that it is configured to use the agent filter. Applications that do not have this setting are not protected by the agent and might malfunction or become unusable if deployed on a deployment container where the agent realm is installed.
The agent realm and agent filter work in tandem with Access Manager to enforce J2EE security policies as well as Access Manager based URL policies for authentication and authorization of clients attempting to access protected J2EE applications.
The agent provides a fully configured and ready-to-use client installation of Access Manager SDK for the deployment container. This SDK offers a rich set of APIs supported by Access Manager that can be used to create security-aware applications that are tailored to work in the security framework offered by Access Manager. For more information on how to use Access Manager SDK, see Sun Java System Access Manager 7 2005Q4 Developer’s Guide.
J2EE agents offer greater functionality in the 2.2 release. Several important new features have been added as follows:
In the 2.2 release, certain restrictions have been removed as follows:
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
Starting with this release, J2EE agents can be configured to use two different mechanisms to remotely evaluate policies as follows:
The agent remotely requests policy evaluation for all resources applicable to a user within the agent’s scope of protection.
The agent remotely requests policy evaluation for the resource accessed by the user and not any other resources that the user might access later.
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.
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.
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.
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.
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.
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.
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.
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.
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:
The request URI
A query parameter sent with the request
A request parameter sent within the request body
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.
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.
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.
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:
J2EE declarative security
J2EE programmatic security
URL policy-based access control deployed on an agent-protected deployment container
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.
Policy Agent 2.2 is backward compatible with Access Manager 6.3 Patch 1 or greater.
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.
This section provides information about J2EE agents in Policy Agent 2.2 that will help you install and get accustomed to the product. J2EE agents have undergone some major changes for the 2.2 release that affect how you interact with them. Read the following subsections to understand the more significant ways that changes made in the 2.2 release affect the manner in which you use a J2EE agent.
The installation process for J2EE agents is quite different for the 2.2 release. This guide provides you with a chapter that explains all the details necessary for understanding this process, from unpacking the J2EE agent binaries to installation related commands, to the directory structure of J2EE agents once the binaries are unpacked. See Chapter 2, Vital Installation Information for a J2EE Agent in Policy Agent 2.2.
The agentadmin program is a required tool for the 2.2 release of J2EE agents. The functionality has increased significantly. The most basic of tasks, such as installation and uninstallation can only be performed with this tool.
For detailed information on installation related tasks performed with this program, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.
For information on all the tasks performed with this program, see Key Features and Tasks Performed With the J2EE agentadmin Program.
Deploy, and interact with the sample application included with Policy Agent 2.2. Interacting with the sample application is perhaps the best way available to you to learn how J2EE agents work. The sample application is deployed at URI/sampleapp. The sample application demonstrates agent configuration options and features. With this application, you can view agent configuration examples and you can test if an agent was deployed successfully. To learn more about this application, read about the sampleapp directory explained in the list following Table 2–2. Moreover, the sampleapp directory includes a README.TXT explaining how to build and deploy the sample application. While you can build the sample application if you desire, this step is not required. When you unpack the J2EE agent distribution, a sample application named agentsample.ear is created for you. The full path to this application is as follows: