test

Sun Java System Access Manager Policy Agent 2.2 Guide for BEA WebLogic Server 9.0/9.1

Chapter 1 Introduction to J2EE Agents for Policy Agent 2.2

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.

Deployment container:

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:

This chapter provides information about J2EE agents for the 2.2 release of Policy Agent as follows:

Uses of J2EE Agents

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:

J2EE Agents and an Online Auction Application

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.

J2EE Agents and a Web-Based Commerce Application

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.

J2EE Agents and a Content-Based Web Application

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.

How J2EE Agents Work

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.

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 in the command line or in any logs. For more information about the use of a password file, see the related pre-installation step in the following section,Preparing to Install Agent for BEA WebLogic Server 9.0/9.1 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 command line 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.

Information About Using J2EE Agents in Policy Agent 2.2

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.

Enhanced Installation Process for J2EE Agents in Policy Agent 2.2

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.

Increased Functionality of the agentadmin Program for J2EE Agents 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.

The Sample Application

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:

PolicyAgent-base/sampleapp/dist/agentsample.ear