Chapter 1 Role of Policy Agent Software

Sun JavaTM SystemPolicy Agent 2.2 software consists of web
agents and J2EE agents. This chapter explains the similarities and differences
of these two types of agents.

An Overview of Policy Agent

Access control in Sun Java System Access Manager is enforced using agents.
Agents protect content on designated deployment containers, such as web servers
and application servers, from unauthorized intrusions. Agents are separate
from Access Manager.

Note –

The most current agents in the Policy Agent software set can
be downloaded from the Identity Management page of the Sun Microsystems Download
Center: http://www.sun.com/software/download

Web agents and J2EE agents differ in a few ways. One significant way
the two agent types differ is in the resources that the two agent types protect.
Web agents protect resources on web and proxy servers while J2EE agents protect
resources on application and portal servers. However, the most basic tasks
that the two agent types perform in order to protect resources are similar.

This chapter does the following:

Explains what agents do.

Describes briefly what a web agent is.

Describes briefly what a J2EE agent is.

Explains how these two types of agents are similar to each
other and yet different.

All agents do the following:

Enable cross-domain single sign-on (CDSSO).

Determine whether a user is authenticated.

Determine whether a resource is protected.

For an authenticated user attempting to access a protected
resource, determine whether the user is authorized to access that resource.

Allow or deny a user access to a protected resource according
to the results of the authentication and authorization processes.

Log access information and diagnostic information.

The preceding task descriptions provide a simplified explanation
of what agents do. Agents perform these tasks in conjunction with Access Manager.
More specifically, agents work with various Access Manager services, such as
Authentication Service, Naming Service, Session Service, Logging Service,
and Policy Service to perform these tasks.

For example, user authentication is handled by Access Manager Authentication
Service. After authentication, users still cannot access a protected resource
until the defined policies regarding user privileges are approved. The agent
and Access Manager continue to interact, performing several small tasks back
and forth, until the agent finally enforces a policy decision to either allow
or deny access. The interactions that take place between Policy Agent and Access Manager are
not covered in detail in Policy Agent documentation. For a more detailed
explanation of these interactions, see Chapter 2, User Session Management and Single Sign-On, in Sun Java System Access Manager 7 2005Q4 Technical Overview

Example of Policy Decision Process

When a user attempts to access content on a protected resource,
many deployment variables are involved. For example, a firewall might or might
not be present. Another example of a deployment variable concerns authentication
levels. In a real-world deployment, different resources on a deployment container
(such as an application or web server) might require different levels of authentication.
These two examples hint at the complexity involved in providing an example
of a policy decision process: the process varies greatly depending on the
specifics of the deployment. Many other factors can affect the policy decision
process, such as the IP address, time zone, and policy expiration time.

Each deployment variable can add a layer of complexity, which might
affect how an agent reacts and how Access Manager reacts. This section provides
a simple example of a policy decision process that highlights the role of
an agent. Therefore, many of the detailed tasks and interactions, especially
those processes that occur in Access Manager are left out. Do not expect the
deployment represented in this example to match the deployment at your site.
This is a generalized example that is applicable to both web and J2EE agents.
Some of the basic steps in the policy decision process are depicted in Figure 1–1. The figure is followed by a written
description of the process.

For this example, in order to focus on stages of the process most relevant
to Policy Agent, certain conditions are assumed as follows:

The user is attempting to access a protected resource after having already
accessed a protected resource on the same Domain Name Server (DNS) domain.
When the user accessed the first protected resource, Access Manager started
a session. The user's attempt to access a second resource, makes this user's
session a single sign-on (SSO) session. Therefore, at this point, the following
already occurred:

The user attempted to access a protected resource through
a browser (the first resource that the user attempts to access during this
session).

The browser request was intercepted by the agent.

The browser was redirected to a login uniform resource locator
(URL), which is the interface to Access Manager Authentication Service.

After the user entered valid credentials, the service authenticated
the credentials.

The following figure and the corresponding step descriptions demonstrate
what occurs after a previously authenticated user attempts to access a second
protected resource through a browser. This figure depicts user profiles and
policy stored together. Note that these data types are often stored separately.

Figure 1–1 Policy Agent and the Policy Decision Process

The browser sends a request for the protected resource to
the deployment container (such as a web or application server) protected by
the agent.

The agent intercepts the request, checks for a session token embedded
in a cookie, and validates the SSO token.

As explained in preceding
text, this example assumes that the user's credentials have already been authenticated.
Though an SSO session such as this often would not require Policy Agent and Access Manager to
contact each other during session validation, such contact is sometimes necessary
and, therefore, is depicted in Figure 1–1.

The agent sends a request to Access Manager Policy Service for
user access to the protected resource.

Access Manager replies with the policy decision.

The agent interprets the policy decision and allows or denies
access.

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 http://java.sun.com/j2ee.

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.

Configuration Properties

Both agent types use a single text file named AMAgent.properties 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 AMAgent.properties file
for J2EE agents has extra constructs such as map constructs and list constructs.
Configuration properties that are present in the AMAgent.properties 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 AMAgent.properties 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 AMAgent.properties 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.