Sun ONE logo     Previous     Contents     Next     
Sun ONE Identity Server Policy Agent Pack Guide



Chapter 1   Read This First


This chapter provides a brief overview of Policy Agents, as well as some concepts you will need to understand before proceeding with the Installation program.

Topics include:



How Policy Agents Work

Sun ONE Identity Server Policy Agents protect content on your web servers and Proxy Servers from unauthorized intrusions. They control access to services and web resources based on the policies configured by an administrator.


Uses for Policy Agents

Policy agents are installed on web servers for a variety of reasons. Here are three examples:

  • An agent on a Human Resources server prevents non-Human Resources personnel from viewing confidential salary information and other sensitive data.

  • An agent on an Operations web server allows only network administrators to view network status reports or to modify network administration records.

  • An agent on an Engineering web server allows authorized personnel from many internal segments of a company to publish and share research and development information. At the same time, the agent restricts external partners from gaining access to the proprietary information.

In each of these situations, a system administrator must set up policies that allow or deny users access to content on a web server. For information on setting policies and for assigning roles and policies to users, see the Sun ONE Identity Server Administration Guide.


How an Agent Interacts with Identity Server

Figure 1-1 illustrates how a Policy Agent installed on a remote web server interacts with Sun ONE Identity Server. When a user points a browser to a particular URL on a protected web server, the following interactions take place:

  1. The agent intercepts the request and validates the existing authentication credentials. If the existing authentication level is insufficient, the appropriate Identity Server authentication service will present a login page. The login page prompts the user for credentials such as username and password.

  2. The authentication service verifies that the user credentials are valid. For example, the default LDAP authentication service verifies that the username and password are stored in Sun ONE Directory Server. You might use other authentication modules such as RADIUS or Certificate modules. In such cases, credentials are not verified by Directory Server but are verified by the appropriate authentication module.

  3. If the user's credentials are properly authenticated, the Policy Agent examines all the roles assigned to the user.

  4. Based on the aggregate of all policies assigned to the user, the individual is either allowed or denied access to the URL.

Figure 1-1    An agent's interaction with Identity Server Policy and Management Services.



Supported Servers


Policy Agent Pack 1.1 supports the following servers running on the Solaris 8 platform:

  • iPlanet Web Server 6.0 SPx

  • iPlanet Web Server 4.1 SP8

  • iPlanet Proxy Server 3.6

  • Apache 1.3.12

Policy Agent Pack 1.1 supports the following servers running on the Windows 2000 platform:

  • Microsoft IIS 5.0

  • iPlanet Web Server 6.0 SP2

Policy Agent Pack 1.1 supports the following servers running on the Windows NT platform:

  • Microsoft IIS 4.0

Policy Agent Pack 1.1 supports the following servers running on the Solaris 9 platform:

  • iPlanet Web Server 6.0 SPx

  • Apache 1.3.22

Other independent agents are:

  • Apache 1.3.22 from Red Hat on Linux 7.2 platform

  • Apache 1.3.26 on Solaris 8 and 9 platforms

  • Lotus Domino 5.0.10 on Windows 2000 platform

  • IBM HTTP Server 1.3.19 on Solaris 8 platform



Before You Begin Installation

The following are issues or concepts that you should be familiar with before you start the Installation program:


Java Runtime Environment (JRE) 1.3.1_04 Requirement

You must have the Java Runtime Environment (JRE) 1.3.1_04 or higher version installed or available on a shared file system in order to run the graphical user interface (GUI) version of the Agent Installation program.

If you are using the Solaris operating system, and JRE 1.3.1_04 is not available, you can use the command-line version of the Agent Installation program.

If you are running the Windows operation system, the Installation program will install JRE 1.3.1_04 if it is not detected.


The Web Server that Runs Identity Server Services vs. Remote Web Servers

You can use the Installation program install a Policy Agent on the web server where Identity Server is installed. In Sun ONE documentation, this server is referred to as the web server that runs the Identity Server services.You can also use the Installation program to install additional Policy Agents on remote web servers in your enterprise. A remote web server in a Identity Server deployment is any web server other than the one that runs Sun ONE Identity Server policy and management services. It is "remote" relative to the Identity Server-dedicated web server.


Installing Multiple Web Server Agents on the Same Computer System

If you have multiple web servers or Proxy servers installed on one computer system, you can install a different agent for each server or server instance. Note that since only one instance of Microsoft IIS server can be installed per computer system, you cannot install multiple Microsoft IIS agents on the same computer system.

For more information, see Installing Multiple Web Server Agents on the Same Solaris Computer System.


Providing Failover Protection for Identity Server Agents

When you install a Policy agent, you can specify a failover or backup web server for running the Sun ONE Identity Server Policy and Management services. This is essentially a high availability option. It ensures that if the web server the runs Identity Server service becomes unavailable, the agent can still process access requests through the secondary or failover web server running Identity Server service.

To set up failover protection for the Policy Agent, you must first install two different instances of Identity Server on two separate web servers. See the detailed instructions in the Sun ONE Identity Server Installation and Configuration Guide. Then follow the instructions in the subsequent sections of this manual to install the appropriate Agent. The agent Installation program will prompt you for the host name and port number of the failover web server you configured to work with Identity Server.


Note

The protocol (for example, http or https) must be the same for both primary web server and the failover web server.



Updating the Agent Cache

Each agent maintains a cache that stores the policies for each user session. The cache can be updated by either a polling mechanism or a notification mechanism. By default the polling mechanism is enabled.


Note

The iPlanet Proxy server agent does not maintain any cache.



Polling Cache Updates

In the polling mode, the agent sends a request (polls) to the Identity Server for any session and policy changes after a specified interval of time. The agent then updates the cache with the information received from the poll.

The agent uses the polling mechanism to update the cache when the property com.iplanet.am.policy.cAPI.notification.enable is set to FALSE in the AMAgent.properties file.

The following two properties are activated in the AMAgent.properties file when the agent is in polling mode:

com.iplanet.am.policy.cAPI.cacheUpdateInterval

com.iplanet.am.policy.cAPI.cacheEntryLifeTime

The com.iplanet.am.policy.cAPI.cacheUpdateInterval property specifies the interval, in minutes, after which the agent performs a cleanup operation to remove all the stale entries in the cache. By default, this property is set to a polling interval of 120 minutes.

The com.iplanet.am.policy.cAPI.cacheEntryLifeTime property determines the amount of time an entry remains valid after it has been added to the cache. The value of the property represents the number of minutes the entry remains valid. After this time has elapsed, this entry in the cache will be ignored and re-fetched from the Identity Server. The default value for this property is 3 minutes.


Notification Cache Updates

In the notification mode, the agent gets notified by the Identity Server session service about session changes. Session changes include events such as a session log-out or a session time-out. When notified of a session change, the agent updates the corresponding entry in the cache.

The agent uses the notification mechanism to update the cache when the property com.iplanet.am.policy.cAPI.notification.enable is set to TRUE in the AMAgent.properties file.

Restrictions due firewalls, as well as the type of web server in use, may not allow notifications to work in certain situations. In such cases, polling is the only way an agent can update its cache.


Note

The notification support is not available in the following instances:

  • If IIS 4.0 or IIS 5.0 is using HTTPS

  • If both the Apache 1.3.12 server and the Identity Server are using HTTPS

  • If you are using iPlanet Proxy Server



Global Not-Enforced List

The global not-enforced list defines the resources that should not have any policies (either allow or deny) associated with them.

By default, a policy agent denies access to all resources for the web server that it protects. However, various resources available through a web server (such as a web site or application) might not need to have any policy enforced. Common examples of such resources include the HTML pages and .gif images found in the Welcome menu for a web site. The user should be able to browse such pages without authenticating. These resources need to be on the global not-enforced list. Only one of the following two properties in AMAgent.properties file will be used for this purpose:

com.iplanet.am.policy.agents.url.notenforcedlist.local

com.iplanet.am.policy.agents.url.notenforcedlist.remote

The property you use depends on where the agent is installed relative to the Identity Server.


Using com.iplanet.am.policy.agents.url.notenforcedlist.local

If the Identity Server and Policy agent are running on the same web server, use the com.iplanet.am.policy.agents.url.notenforcedlist.local property to read the list of resources that has no policy enforced on them. The default value in the list defines a set of resources that are used by the Identity Server services. Add to this list by separating additional items with commas. Wild cards can be used in the expressions that are used in global not-enforced list.


Note

This list is used only in the following instances:

  • When an iPlanet Web Server 6.0 agent is installed on the Identity Server.

  • When you are using an iPlanet Proxy Server 3.6 agent



Using com.iplanet.am.policy.agents.url.notenforcedlist.remote

If the agent and Sun ONE Identity Server are running on different web servers, use the com.iplanet.am.policy.agents.url.notenforcedlist.remote property to maintain the global not-enforced list. Additions to this list must be separated by commas. Wild cards can be used in the expressions that are used in global not-enforced list.


Note

You cannot use this list in the following instances:

  • When an iPlanet Web Server 6.0 agent is installed on the Identity Server.

  • When you are using an iPlanet Proxy Server 3.6 agent.



The AMAgent.properties File

The AMAgent.properties file stores configuration parameters used by the Policy Agent. From time to time, you may need to make changes to the default parameters in this file. For example, when you want to specify a different failover web server for running Identity Server services, or when you want to enable validation by agent on client IP addresses.

The AMAgent.properties file includes information for the following configurations:

  • debugging

  • policy agent

  • Identity Server services

  • policy API

  • service and agent deployment descriptors

  • session failover

The AMAgent.properties file also contains configuration information on advanced features, such as forwarding LDAP user attributes via HTTP headers, client IP address validation, and so on. The AMAgent.properties file has comments before each property; refer to the file for more details.

Table 1-1 provides the default location for AMAgent.properties on the various supported servers.


Table 1-1    Locating AMAgent.properties on different platforms

Server

Location

All Supported UNIX web servers  

 /etc/opt/SUNWam/conf/WebServer/_PathInstanceName/config/

Here, WebServer can be:

  • iWS60

  • iWS41

  • Proxy

  • APACHE

 

iPlanet Web Server 6.0
Windows 2000  

 \Agent_Install_Dir\Agents\iws60\web-apps\agent\WEB-INF\config\

 

Microsoft IIS 5.0
Windows 2000  

 \Agent_Install_Dir\Agents\iis50\config\

 

Microsoft IIS 4.0
Windows NT  

 \Agent_Install_Dir\Agents\iis40\config\

 

Apache 1.3.22 from Red Hat  

 /Agent_Install_Dir/apagent/conf

 

Apache 1.3.26  

 /etc/opt/SUNWam/conf/APACHE/_PathInstanceName/

 

Lotus Domino 5.0.10  

 \Agent_Install_Dir\Agents\domino\config

 

IBM HTTP Server 1.3.19  

 /etc/opt/SUNWam/conf/IBMHTTP/_opt_IBMHTTPD_conf/

 

Changing that AMAgent.properties file can have serious and far-reaching effects. Remember that you can safely change many of the properties in this file by simply re-installing the agent. However, if you must make manual changes, keep the following in mind:

  • Make a backup copy of this file before you make changes.

  • Trailing spaces are significant; use them judiciously.

  • Use forward-slash (/) to separate directories, not back-slash (\). This holds true even on Windows systems.

  • Spaces in the Windows file names are allowed.


    Note

    If you make changes to the AMAgent.properties file, you must restart the web server to make your changes take effect.



Verifying a Successful Installation

After installing a Policy Agent, it is good practice to make sure that the agent was installed successfully and works as you expect it to work. There are two things you can check to verify a successful agent installation.

First, try to access some web content on the web server where the agent is installed. If the agent is installed correctly, you should see the Identity Server login page. Figure 1-2 is an example of a Identity Server login page that uses LDAP authentication. Secondly, check the AMAgent.properties file. Make sure that each property is set properly.

Figure 1-2    The Sun ONE Identity Server Login page



Previous     Contents     Next     
Copyright 2002   Sun Microsystems, Inc. All rights reserved.

Last Updated November 20, 2002