Sun Java System Access Manager Policy Agent 2.2 User's Guide

Web and J2EE Agents: Similarities and Differences

Both web agents and J2EE agents protect resources hosted on deployment containers (such as web and application servers) or enforce single sign-on with systems that use deployment containers as the front-end in an environment secured by Access Manager. The two types of agents are similar in some ways and yet different in others as outlined in this section.

Web Agents

Web agents control access to content on web servers and proxy servers. The content that web agents can protect include a multitude of services and web resources based on policies configured by an administrator. When a user points a browser to a URL deployed on a protected web or proxy server, the agent intercepts the request and validates the user’s session token, if any exists. If the token’s authentication level is insufficient (or none exists), the appropriate Authentication Service is called for a login page, prompting the user for (further) authentication. The Authentication Service verifies that the user credentials are valid. For example, the LDAP service verifies that the user name and password are stored in an LDAP v3 compliant directory server, such as Sun Java System Directory Server. After the user’s credentials are properly authenticated, the agent examines all the roles and groups (which contain the policies) assigned to the user. Based on the aggregate of all policies assigned to the user, the individual is either allowed or denied access to the URL.

J2EE Agents

Access Manager provides agents for protecting J2EE applications in a variety of deployment containers, such as application and portal servers.

A J2EE policy agent can be installed for protecting a variety of hosted J2EE applications, which might require a varying set of security policy implementation. The security infrastructure of J2EE provides declarative as well as programmatic security that are platform-independent and are supported by all the J2EE-compliant servers. For details on how to use J2EE platform declarative as well as programmatic security, refer to J2EE documentation at

The agent helps enable role-to-principal mapping for protected J2EE applications with Access Manager principals. Therefore, at runtime, when a J2EE policy is evaluated, the evaluation is against the information available in Access Manager. Using this functionality, you can configure hosted J2EE applications so that they are protected by the J2EE agent, which provides real security services and other key features such as single sign-on. Apart from enabling J2EE security for hosted applications, J2EE agents also provide complete support for Access Manager based URL policies for enforcing access control over web resources hosted in deployment containers, such as an application servers.

While web agents and J2EE agents both work with Access Manager to implement authentication and authorization processes, the design of the J2EE agents allows them to also enforce J2EE security. The J2EE agents are generally comprised of two components (although this is partially subject to the interfaces exposed and supported by the deployment container): an agent filter for authentication and an agent realm for authorization.

Agent Filter and Authentication

In J2EE agents, the agent filter component manages authentication. The agent filter is a servlet filter, which is supported starting with J2EE 1.3. The agent filter intercepts an inbound request to the server. It checks the request to see if it contains a session token. If one is available, the agent filter validates the token using the Access Manager Session Service. If no token is available, the browser is redirected to the Authentication Service as in a typical SSO exchange. Once the user credentials are authenticated, the request is directed back to the server where the agent filter once again intercepts it, and then validates the newly acquired token. After the user's credentials are validated, the filter enforces J2EE policies or fine-grained URL policies on the resource the user is trying to access. Through this mechanism, the agent filter ensures that only requests with a valid Access Manager token are allowed to access a protected application.

Agent Realm and Authorization

In J2EE agents, the agent realm component manages authorization. A realm is a means for a J2EE-compliant application server to provide information about users, groups, and access control to applications deployed on it. It is a scope over which security policy is defined and enforced.

The server is configured to use a specific realm for validation of users and their roles, when attempts are made to access resources. By default, many application servers ship with a number of realm implementations, including the default File Based as well as LDAP, NT, UNIX, and Relational Database Management System (RDBMS). The agent realm component implements the server’s realm interface, and allows user and role information to be managed by the Access Manager deployment. The agent realm component makes it possible to provide granular role-based authorization of J2EE resources to users who have been authenticated by the agent filter component.

Key Similarities of the Two Agent Types

The section Example of Policy Decision Process describes a deployment that emphasizes the similar tasks performed by web agents and J2EE agents. The two agent types share various other features and tasks that are not described in that section. Though this section describes similarities of the two agent types, the features and tasks that they have in common tend to have some differences. However, those differences are often subtle. The details about agent features and tasks are not provided in this guide. For details about the features and tasks for each agent type (web agent or J2EE agent), see any of the individual agent guides for that agent type: see Chapter 2, Access Manager Policy Agent 2.2 Web Agents: Compatibility, Supported Servers, and Documentation for information about the individual web agent guides and see Chapter 3, Access Manager Policy Agent 2.2 J2EE Agents: Compatibility, Supported Servers, and Documentation for information about the individual J2EE agent guides. A list of key features and tasks that web agents and J2EE agents have in common follows along with an explanation of each item:

Configuration Properties

Both agent types use a single text file named to configure agent properties. Agent configuration is controlled to a great extent by the properties in this file.

The configuration properties file used for web agents is very similar to the configuration properties file used for J2EE agents. The biggest difference between the two files is that the file for J2EE agents has extra constructs such as map constructs and list constructs. Configuration properties that are present in the files for both agent types tend to be very similar in terms of functionality.

Policy Agent Log Files

Web agents and J2EE agents can log access information and diagnostic information to an agent log file. Each agent has its own log file, a flat file located on the same host system as the agent. The log file size is configurable. When the active log file reaches the size limit, the log is rotated, which means that the older log information is moved and stored in another log file.

Furthermore, both agent types are capable of logging access information to an Access Manager log file or database table.

Not-Enforced Lists

Both agent types support not-enforced lists. These lists allow for the regular authentication and authorization processes to be bypassed. These lists are set in the file. Two types of not-enforced lists exist: a not-enforced URL list and a not-enforced IP Address list.

A not-enforced URL list is a list of URLs that are not protected by an agent. A resource represented by a URL on a not-enforced URL list is widely available, without restrictions. This list can be set to have a reverse meaning. With a reverse meaning, only URLs on the list are protected. All other URLs are not protected.

A not-enforced IP Address list is a list of IP addresses that are automatically allowed access to resources. When a user is using a computer that has an IP address on the not-enforced IP address list, that user is allowed access to all the resources protected by the respective agent.

Personal Profile Attributes and Session Attributes

Both agent types can fetch and pass along personal profile attributes and session attributes. Client applications protected by an agent can then use information from these attributes to personalize content for the user.

Key Differences Between the Two Agent Types

Many differences exist between J2EE agents and web agents in the way they perform tasks. However, the basic tasks they perform are similar. While the primary purpose of both types of agents is to enforce authentication and authorization before a user can access a protected resource, the two agent types differ in the kind of resources that they can protect and in the way they enforce such policy decisions.

Differences in Protected Resources

Web agents are capable of protecting resources that can be hosted on the web or proxy servers on which they are installed. This protection includes any resource that can be represented as a uniform resource identifier (URI) available on the protected server. Such a protected URI can be resolved by the server to static content files such as HTML files or dynamic content generation programs such as CGI scripts or servlets hosted by an embedded servlet engine. In other words, before a request is evaluated by the web or proxy server, the web agent can evaluate the necessary credentials of a user and can allow or deny access for the requested resource. Once the request is granted access to the resource, it can be processed internally by the web or proxy server as applicable. In other words, the web agent uses the request URL to enforce all policy decisions regardless of what that URL maps to internally in the web server. In cases where the request URL maps to a servlet which in turn invokes other servlets or JSPs, the web agent will not intercept these subsequent resource requests unless such invocation involves a client-side redirect.

A J2EE agent is capable of protecting web and enterprise applications hosted by the application or portal server on which it is installed. These applications may include resources such as HTML pages, servlets, JSP, and Enterprise JavaBeans (EJB). Apart from these resources, any resource that can be accessed as a URI within a protected web application can also be secured by such agents. For example, images that are packaged within a web application can also be protected by the J2EE Policy Agent. These agents allow the evaluation of J2EE policies and can also enforce Access Manager based URL policies like a web agent on the resources being requested by the user. Minimally the enforcement is done at the outermost requested URL, but can also be done on any intermediate URLs being chained to this resource on most application servers.

Default Scope of Protection

When installed, a web agent automatically protects the entire set of resources available on the web server. However, in order to protect resources within a web application hosted on an application server, the web application must be configured to use the J2EE agent. Thus if multiple web applications are hosted on an application server on which a J2EE agent has been installed, only the web applications that have been specifically configured to use the J2EE agent will be protected by the agent. Other applications will remain unprotected and can potentially malfunction if they depend upon any J2EE security mechanism.

Further, the J2EE agent can only protect resources that are packaged within a web or enterprise application. Certain application servers provide an embedded web server that can be used to host non-packaged web content such as HTML files and images. Such content cannot be protected by a J2EE agent unless it is redeployed as a part of a web application.

Modes of Operation

J2EE agents provide more modes of operation than do web agents. These modes are basically methods for evaluating and enforcing access to resources. You can set the mode according to your site's security requirements. For example, the SSO_ONLY mode is a relatively non-restrictive mode. This mode uses only Access Manager Authentication Service to authenticate users who attempt to access a protected resource.

Some of the modes such as SSO_ONLY and URL_POLICY are also achievable with web agents, whereas other modes of operation such as J2EE_POLICY and ALL modes do not apply to web agents.

For both J2EE agents and web agents, the modes are set in the file.

In the J2EE_POLICY and ALL modes of operation, J2EE agents enforce J2EE declarative policies as applicable for the protected application and also provide support for evaluation of programmatic security APIs available within J2EE specifications.