Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents

Previous: Chapter 4 Common Web Agent Tasks and Features in Policy Agent 3.0
Next: Appendix B Silent Installation and Uninstallation of a Web Agent in Policy Agent 3.0

An Overview of Policy Agent 3.0

Access control in Sun OpenSSO Enterprise 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 OpenSSO Enterprise.

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.

Agents do the following:

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.
Support cross-domain single sign-on (CDSSO). CDSSO applies to most agents.

The preceding task descriptions provide a simplified explanation of what agents do. Agents perform these tasks in conjunction with OpenSSO Enterprise. More specifically, agents work with various OpenSSO Enterprise services, such as Authentication Service, Session Service, Logging Service, and Policy Service to perform these tasks. Both agent types, J2EE agents and web agents interact with these OpenSSO Enterprise services in a similar manner.

Interaction Between Policy Agent 3.0 and OpenSSO Enterprise Services

This section shows how J2EE agents and web agents interact with OpenSSO Enterprise Services.

The figure that follows applies to web agents and J2EE agents. At this level, the agent types are the same in what they accomplish, even though at a deeper level the methods used vary to some degree.

Figure A–1 Policy Agent Interaction with OpenSSO Enterprise Services

This figure illustrates how Policy Agentinteracts
with the OpenSSO Enterprise services.

A key point is that the agent must interact continuously with various OpenSSO Enterprise services. The interactions that take place between Policy Agent and OpenSSO Enterprise are not covered in detail in Policy Agent documentation. For a more information on such interactions, see Sun OpenSSO Enterprise 8.0 Administration Guide.

A Generalized Example of the Policy Decision Process

When a user attempts to access content on a protected resource, many deployment variables are involved. For example, firewalls might be present or load balancers might be involved. From a high level, the two agent types (J2EE agents and web agents) handle these deployments in the same manner. The following reference presents figures that demonstrate how web agents and J2EE agents have the same role in a complex OpenSSO Enterprise deployments: Part I, About This Deployment, in Deployment Example: Single Sign-On, Load Balancing and Failover Using Sun OpenSSO Enterprise 8.0.

Therefore, J2EE agents and web agents do not differ in the general role they play in an OpenSSO Enterprise deployment. However, at the policy decision level, the differences between the two agent types are more easily observed, and components such as firewalls and load balancers can add complexity to the policy decision process. Therefore, for the basic example provided in this section about the policy decision process, such complex details are not included.

Another example of a deployment variable concerns authentication levels. In a real-world deployment, different resources on a deployment container (such as an application server or web server) might require different levels of authentication. Suffice to say a great deal of complexity is involved in providing a generic example of a policy decision process, especially one that applies equally to J2EE agents and web agents. For one, 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 OpenSSO Enterprise 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 OpenSSO Enterprise 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 agents and J2EE agents. Some of the basic steps in the policy decision process are depicted in Figure A–2. The figure is followed by a written description of the process. Notice that the figure illustrates the policy decision process in terms of the components the decision passes through. To see the policy decision process in a flow chart view, see Figure A–3 for the J2EE agent view and Figure A–4 for the web agent view.

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, OpenSSO Enterprise 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 OpenSSO Enterprise 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 A–2 Policy Agent and the Policy Decision Process

This figure focuses on Policy Agent while demonstrating
the basic steps involved in a 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 session via OpenSSO Enterprise session service.
The agent sends a request to OpenSSO Enterprise Policy Service for user access to the protected resource.
OpenSSO Enterprise replies with the policy decision.
The agent interprets the policy decision and allows or denies access.

Examples of the Policy Decision Process by Agent Type

This section illustrates the policy decision process through the use of flow charts: one for J2EE agents and one for web agents. These two flow charts show how J2EE agents and web agents can differ in that J2EE security can be enabled for J2EE agents.

These charts illustrate possible scenarios that can take place when an end user makes a request for a resource. Therefore, the end user points a browser to a URL. That URL is a resource, such as a JPEG image, HTML page, JSP page, etc. When a resource is under the sphere of influence of the agent, the agent intervenes to varying degrees, depending on the specifics of the situation, checks the request, and takes the appropriate action, which culminates with the user either being allowed or denied access to the resource. The charts that follow reflect the potential paths a request makes before finally being allowed or denied.

Policy Decision Process for J2EE Agents

The figure that follows is a flow chart of the policy decision process for J2EE agents. This figure illustrates how a single request is processed and how the filter mode is involved in the process.

Figure A–3 J2EE Agents and the Policy Decision Process

This figure is a flow chart of the policy decision process
for a J2EE agent.

Policy Decision Process for Web Agents

The figure that follows is a flow chart of the policy decision process for web agents. This figure illustrates how a single request is processed.

Figure A–4 Web Agents and the Policy Decision Process

This figure is a flow chart of the policy decision process
for a web agent.

Web Agents 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 OpenSSO Enterprise. 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. After the user’s credentials are properly authenticated, the agent examines all the 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

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

A J2EE 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 OpenSSO Enterprise principals. Therefore, at runtime, when a J2EE policy is evaluated, the evaluation is against the information available in OpenSSO Enterprise. 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 OpenSSO Enterprise 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 OpenSSO Enterprise to implement authentication and authorization processes, the design of the J2EE agents allows them to also enforce J2EE security. You can see this difference in terms of enforcing J2EE security by comparing the flow charts of the two agents types: Figure A–3 and Figure A–4. 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 and URL policy related authorization. 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 OpenSSO Enterprise 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 OpenSSO Enterprise token are allowed to access a protected application.

Agent Realm and Authorization

In J2EE agents, the agent realm component facilitates the authorization related to J2EE security policies defined in the applications. 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 OpenSSO Enterprise 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 A Generalized Example of the 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. 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

Configuration properties for both agent types tend to be very similar in terms of functionality.

All agent configurations have an OpenSSOAgentBootstrap.properties file. Regardless of the configuration type, local or centralized, a small subset of properties that are required for the agent to start up and initialize itself are stored in the bootstrap file locally on the server where the agent is installed. This bootstrap file can only be configured by editing it directly. You cannot use either OpenSSO Enterprise Console or the ssoadm command-line utility to edit this file.

When the agents are installed using a centralized configuration (an option available starting with Policy Agent 3.0), both agent types allow the configuration properties, except those located in the OpenSSOAgentBootstrap.properties file, to be configured using either OpenSSO Enterprise Console or the ssoadm command-line utility.

If an agent is configured locally on the agent host, then for both agent types, the properties that are not stored in the bootstrap file must be configured by directly editing the OpenSSOAgentConfiguration.properties file.

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 OpenSSO Enterprise 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. Two types of not-enforced lists exist: a not-enforced URI/URL list and a not-enforced IP Address list.

A not-enforced URI/URL list is a list of URIs or URLs that are not protected by an agent.

Web agents support a not-enforced URL list. For example, http://agentHost:port/myapp
J2EE agents support a not enforced URI list. For example, /myapp/index.html.

A resource represented by a URI/URL on a not-enforced URI/URL list is widely available, without restrictions. This list can be set to have a reverse meaning. With a reverse meaning, only URIs/URLs on the list are protected. All other URIs/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, Session Attributes, and Policy Response Attributes.

Both agent types can fetch and pass along personal profile attributes, session attributes, and policy response 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.

Default Scope of Protection

When installed, a web agent automatically protects the entire set of resources available on the web server. On the other hand, J2EE agents only protect resources within a web application hosted on an application server after the web application has been 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 less restrictive mode. This mode uses only OpenSSO Enterprise 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 web agents, by default, SSO_ONLY and URL_POLICY modes are both on. If you want only SSO set, enable the property labeled SSO Only Mode (Tab: Global, Name: com.sun.identity.agents.config.sso.only).

For both J2EE agents and web agents, the modes can be set in OpenSSO Enterprise Console.

In the J2EE_POLICY and ALL modes of operation, J2EE agents enforce J2EE declarative policies as applicable for the protected application.