Previous     Contents    
iPlanet Policy Agent Pack Installation Guide


Chapter 3   URL Policy Agents for Windows 2000


iPlanet URL policy agents work in tandem with iPlanet Directory Server Access Management Edition (DSAME) to grant or deny user access to Web Servers in an enterprise. The iPlanet Policy Agent Pack 1.0 provides a set of URL policy agents for use with various web and proxy servers. This chapter explains how URL access agents can be configured for various Web Servers running on the Windows 2000 operating system.

Topics include:



Supported Windows Web Servers

The Agent Pack supports the following Web Servers on the Windows 2000 Server operating system:

  • Microsoft IIS 5.0

  • iPlanet Web Server 6.0 SP2



Before You Begin

Be sure you're familiar with the concepts presented in Chapter 1 "Read This First" on page 9. The chapter includes brief but important information on the following topics:



Using the Graphical User Interface (GUI) Version of the Installation Program

Use the GUI version of the Installation program to install one agent at a time.


Installing the Policy Agent for Microsoft IIS

The IIS agent enforces policy on URL access for Microsoft's Internet Information Services (IIS) Web Server. The agent is an IIS ISAPI filter installed at the IIS web service level that will enforce policy on all IIS web sites. Technical considerations prevent the agent from being installed at the web site level.

Prior to installation, be sure that the entry for the computer system where the agent will be installed has a domain name set. If the Web Server that runs DSAME services is running on a separate computer system, make sure the server is also in the DNS query list.


To Install the Policy Agent on Microsoft IIS

You must have administrator privileges to run the installation program.

  1. Unzip the product binaries file.

  2. Run the Installation program by double-clicking setup.exe.

  3. In the Welcome window, click Next.

  4. Read the License Agreement. Click Yes to accept the license agreement.

  5. Select the directory where you would like to install the agent by clicking Browse, or click Next to accept the default.

  6. Select the component "DSAME Agent for IIS" and click Next. Note that only one component may be installed for each time the Installation program is run.

  7. Enter the information about the Web server where this agent will be installed:

    Host Name: Enter the fully qualified domain name of the computer system where the remote Web Server is installed. For example, mycomputer.iplanet.com.

    Web Server Document Root: Enter the document root directory. This directory needs to accessible by the Web Server root W3SVC.

    Web Server Port: Enter the port number for the Web Server that will be protected by the agent.

    Web Server Protocol: If you Web Server has been configured for SSL, then select HTTPS; otherwise select HTTP.

    Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.

    The URI prefix tells the Web Server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the Web Server Document Root.

    When all the information is entered correctly, click Next.

  8. Provide the following information about Web Server that runs DSAME services:

    DSAME Services Host: Enter the fully qualified domain name of the computer system where the primary Web Server that runs DSAME services is installed. For example, myserver.iplanet.com.

    DSAME Services Port: Enter the port number for the primary Web Server that runs DSAME services.

    DSAME Services Protocol: If the Web Server that runs DSAME services has been configured for SSL, then select HTTPS; otherwise select HTTP.

    DSAME Services Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.

    Failover Server Host: Enter the fully qualified domain name for the secondary Web Server that will run DSAME services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.

    Failover Server Port: Enter the port number of the secondary Web Server that will run DSAME services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.

    Password: Enter the password for the DSAME user amAdmin. This user is the Super Administrator, and has unrestricted access and privileges on the Web Server that runs DSAME services.

  9. If all the information entered is correct click Next.

  10. Review your selections in the Summary panel and click Install Now.

  11. When the installation is complete you may review the details, and then click Exit.

  12. The installation modifies the system path by appending to it the location of the Agent libraries. In order for the change to take effect and for the Agent to work properly, you must reboot your computer. If you would like to reboot your computer immediately click Reboot Now in the popup window.


Installing the Policy Agent for iPlanet Web Server

You must have administrator privileges to run the Installation program.


To Install the URL Policy Agent on iPlanet Web Server

  1. Unzip the product binaries file.

  2. Run the Installation program by double-clicking setup.exe.

  3. In the Welcome window, click Next.

  4. Read the License Agreement. Click Yes to agree to the license terms.

  5. Select the directory where you would like to install the agent by clicking Browse, or click Next to accept the default.

  6. Select the component "DSAME Agent for iWS 6.0" and click Next. Note that only one component may be installed at a time.

  7. Provide the following information about the Web server where this agent will be installed:

    Host Name: Enter the fully qualified domain name of the computer system where the remote Web Server is installed. For example, mycomputer.iplanet.com.

    Web Server Install Location: Enter the full path to the directory where the iPlanet Web Server is installed. This is the Web Server that the agent will protect. The directory should contain the https-adminserv and https-instance_identifier.yourdomainname directories.

    Web Server Port: Enter the port number for the Web Server that will be protected by the agent.

    Web Server Protocol: If the Web Server has been configured for SSL, then select HTTPS; otherwise select HTTP.

    Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) for the policy agent is /amagent.

    The Universal Resource Identifier (URI) prefix tells the Web Server where to look for HTML pages the agent needs to display. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory denoted by this URI, will be created in the Web Server Document Root you supplied.

    If all the information entered is correct click Next.

  8. Enter the information about the Web Server that runs DSAME services.

    DSAME Services Host: Enter the fully qualified domain name of the computer system where the primary Web Server that runs DSAME services is installed. For example, myserver.iplanet.com.

    DSAME Services Port: Enter the port number for the primary Web Server that runs DSAME services.

    DSAME Services Protocol: If the Web Server that runs DSAME services has been configured for SSL, then select HTTPS; otherwise select HTTP.

    DSAME Services Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.

    Failover Server Host: Enter the fully qualified domain name for the secondary Web Server that will run DSAME services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.

    Failover Server Port: Enter the port number of the secondary Web Server that will run DSAME services. If no failover server exists, then leave this field blank.

  9. Password: Enter the password for the DSAME administrator amAdmin. This user has unrestricted access and privileges on the Web Server that runs DSAME services.

  10. If all the information entered is correct click Next.

  11. Click Install Now.

  12. When the installation is complete you may review the details, and then click Exit.

  13. You must restart your iPlanet Web Server for the installation to be complete.


Disabling and Uninstalling URL Policy Agents

When you no longer require the URL policy agent, you can uninstall it or disable it. To uninstall an agent, run the Installation program. You can disable the URL access policy agent by modifying the Web Server configuration files.

Another way to temporarily disable the agents is to add an asterisk (*) to the property: com.iplanet.comam.policy.agents.url.notenforcedlist located in the AMAgent.properties file. See also The AMAgent.properties File.


Uninstalling a URL Policy Agent

Use the following instructions to disable an agent on iPlanet Web Server or on Microsoft IIS. Note that you can disable an agent installed on Microsoft IIS by either uninstalling the agent using these steps, or by uninstalling the IIS filter. Uninstalling the IIS filter is the recommended method. See the following section "Disabling a URL Policy Agent Installed on Microsoft IIS."


To Uninstall a URL Policy Agent

  1. In the Start Menu, open Settings > Control Panel.

  2. In the Control Panel, open Add / Remove Programs

  3. In the Add/Remove Programs window, choose iPlanet Directory Services Access Management Edition Agent 1.0

  4. Click Change/Remove.

  5. Click Next on Welcome Panel.

  6. On Type of Install Panel, select Full.

  7. Click Uninstall Now.

  8. Click Exit after uninstallation is complete.


Disabling a URL Policy Agent Installed on Microsoft IIS

This is the recommended method for disabling an agent on Microsoft IIS.


To Uninstall the Agent IIS Filter

  1. Launch Internet Services Manager.

    1. In the Start Menu, click Programs > Administrative Tools > Internet Services Manager

  2. Check the filter status.

    1. Open properties for the host computer in the Tree Pane of the Internet Services Manager window which is titled "Internet Information Services."

    2. The host computer name should appear in the tree underneath the Internet Information Services root.

    3. Click Edit in the Master Properties section of the Internet Information Services tab.

    4. Select the ISAPI Filters tab in the WWW Service Master Properties dialog that appears.

    5. Highlight the filter named "DSAME IIS Agent."

      You can click Edit to view the filter name and executable path. You'll need this information when you want to re-enable the agent. Click Cancel to return to the program.

    6. Click Remove

    7. Click Apply and exit from the WWW Service Master Properties dialog.

    8. Restart Microsoft IIS.


Disabling a URL Policy Agent Installed on iPlanet Web Server

You can disable the agent by editing the magnus.conf file.

In the file magnus.conf, remove or comment out lines containing the following strings:

    • web_agent_init

    • validate_session_policy



Using the Command-Line Version of the Installation Program

The command-line version of the Installation program provides you an alternative to the graphical user interface (GUI) version.


To Install an Agent Using the Command Line

  1. In the directory where you unzipped the binaries file, at the command line, enter the following command:

      java setup.bat -nodisplay

  2. When prompted, provide the following information:

    Have you read, and do you accept, all of the terms of the preceding Software License Agreement?

    Install DSAME Agent in this directory: Specify the directory where you want the agent o be installed. To accept the default directory that is displayed in brackets, press Enter. Otherwise, enter a full path.

  3. The following text displays:

    DSAME Agent components showing a checked box will be installed. Only one agent may be installed at a time.
    [ ] 1 DSAME Agent for IIS 5.0
    [ ] 2 DSAME Agent for iPlanet Web Server 6.0 SP2

    First, do one of the following:

    • To install the agent for Microsoft IIS 5.0, enter 1.

    • To install the agent for iPlanet Web Server 6.0 SP2, enter 2.

    Then, when a checkmark appears beside your choice, enter 0 to continue.

  4. When prompted, provide information about the Web Server instance this Agent will protect.

    Host Name: Enter a fully-qualified domain name. Example: clio.madisonparc.com

    Web Server Port: Enter the port number for the Web Server the agent will protect.

    Web Server Protocol: If the Web Server is SSL-enabled, enter HTTPS. If the Web Server is not SSL-enabled, enter HTTP.

    iPlanet Web Server Instance Directory: Enter the path to the directory where iPlanet Web Server is installed. The directory name must consist of the prefix https- and the name of the server instance. Example:

    C:\web_server_root\https-madisonparc.com]

    Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.

    The URI prefix tells the Web Server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the Web Server Document Root.

  5. When prompted, provide information about the Web Server that runs DSAME Services. The following fields refer to the computer system where DSAME is installed:

    Host Name: Enter the fully qualified domain name of the computer system where the Web Server that runs DSAME services is installed. Example: blue.madisonparc.com.

    Port Number: Enter the port number for the Web Server that runs DSAME Services.

    Protocol: If the Web Server that runs DSAME services is SSL-enabled, Enter HTTPS; otherwise, enter HTTP.

    Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.

    Failover Host: If you have configured a failover Web Server to run DSAME Services, enter the IP address or host name of the failover computer system. Examples: 29.153.345.89 or blue.madisonparc.com

    If no failover server exists, then leave this field blank.

    Failover Port: If you have configured a failover Web Server to run DSAME Services, enter the Web Server port number. If no failover host servers exist, then leave this field blank.

    amAdmin Password: amAdmin is the DSAME SuperAdministrator and has unrestricted access and privileges. Enter the amAdmin user's password; the password the agent authenticates to.

  6. When displayed, review the summary of installation information you've specified. Press Enter to continue, or enter and exclamation point (!) to exit the program.

  7. The following message displays:

    Ready to Install

    1. Install Now
    2. Start Over
    3. Exit Installation

    What would you like to do

    To continue with installation, enter 1.

  8. When installation is complete, you must restart the iPlanet Web Server.


To Uninstall an Agent Using the Command Line

  1. In the agent_root directory, at the command line, enter the following command:

      java uninstall_DSAME_Agent -nodisplay

  2. When prompted, provide the following information:

    Please select the type of uninstall to perform from the following choices: To remove the product and all of the components, enter. To select some, but not all, product components to removed, enter Partial.

  3. The following message displays:

    1. Uninstall Now
    2. Start Over
    3. Exit Uninstallation
    What would you like to do?

    To begin uninstalling the agent, enter 1.

  4. When the Installation program is finished, you must reboot the computer system.

If you want to see more details of the uninstallation, a log file is written in the following location:

%TEMP%\DSAME_Agent_uninstall.*



Installing Multiple Policy Agents on the Same Windows Computer System

You can install multiple iPlanet Web Servers on a single computer system, and you can install a separate agent against each server or server instance. Note that since you can install only one instance of IIS per computer system, you can install only one global agent against it. The global agent protects all websites on the server.

You can, however, install one instance of IIS along with multiple iPlanet Web Servers on the same computer system. In this case, you can install multiple agents against the iPlanet Web Servers in addition to the single agent on the IIS—all on the same computer.

You can run the Installation program multiple times to install the multiple agents. But you can only install one agent each time you run the program.

Note When installing multiple iPlanet Web Server policy agents, whether you use the GUI version or CLI version, be sure to specific a different install directory for each agent.




Using Secure Sockets Layer (SSL) with an Agent


You can configure a remote Web Server (with policy agent installed) to communicate over SSL with the Web Server that runs DSAME services. The SSL protocol consists of rules governing encrypted communication between servers and clients. The requests and transactions between the remote Web Server and the Web Server that runs DSAME services are encrypted when SSL is fully enabled. This protects the communication between the servers from intrusion by unauthorized entities.

During Installation, if you specify the HTTPS protocol for the Web Server that runs DSAME services, the agent is automatically configured to communicate over SSL.


Note

Before proceeding with the following steps, you should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation that comes with your web server. If you're using iPlanet Web Server, you can access the following documentation on the Internet:

http://docs.iplanet.com/docs/manuals/enterprise/60sp1/ag/esecurty.htm#1011961



The Agent's Default Trust Behavior

By default the URL policy agent installed on a remote iPlanet Web Server 6.0 or Microsoft IIS 5.0 will trust any server certificate presented over SSL by the Web Server that runs DSAME services; the agent does not check the root Certificate Authority (CA) certificate. If the Web Server that runs DSAME services is SSL-enabled, and you want the URL policy agent to perform certificate-checking, you must do two things:

  1. Disable the agent's default trust behavior.

  2. Install a root CA certificate on the remote Web Server where the agent is installed. The root CA certificate must the be same one that is installed on the Web Server that runs DSAME service.


Disabling the Agent's Default Trust Behavior

The following property exists in the AMAgent.properites file, and by default it is set to true:

com.iplanet.am.policy.agents.trust_server_certs=true

This means that the agent does not perform certificate-checking.


To Disable the Default Behavior

The following property must be set to false:

com.iplanet.am.policy.agents.trust_server_certs=false


Installing the Root CA Certificate on the Remote Web Server

The root CA certificate that you install on the remote Web Server must be the same one that is installed on the Web Server that runs DSAME services.


To Install the Root CA Certificate on iPlanet Web Server

See the instructions for installing a root CA Certificate in the documentation that comes with the Web Server. Access the documentation for iPlanet Web Server 6.0 on the Internet at the following URL:

http://docs.iplanet.com/docs/manuals/enterprise/60sp1/ag/esecurty.htm#1011961


To Install the Root CA Certificate on Microsoft IIS

  1. Create a cert directory in: agent_install_directory\Agents\iis50

  2. Create a text file called passwd.txt in the cert directory created in step 1.

  3. In the passwd.txt file add a single line containing the password for the amAdmin user on the Web Server that runs DSAME services.

  4. In the directory: agent_install_directory\Agents\iis50\utils, enter the following command:

      certutil -f passwd.txt -N -d cert_directory

    This will create a new certificate database.

  5. Add the same root certificate that is installed on the Web Server that runs DSAME services into the existing certificate database. At the command line, enter the following command:

    certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

    using the following variables:

    • cert-name can be any name for this root certificate.

    • cert-dir is directory where the certificate-related files are located. On Windows the locations is Agent-Install-Directory\Agents\iis50\cert.

    • cert-file is the base-64 encoded root certificate file.

    • For more information on certutil, type certutil -H

  6. Edit the file agent_install_directory\Agents\iis50\config\AMAgent.properties. In the following property:

    com.iplanet.am.policy.agents.url.serverdir

    add the full path to the cert directory created in step 1.

    Example: com.iplanet.am.policy.agents.url.serverdir= C:\Program Files\DSAME\Agents\iis50\cert

  7. Save the AMAgent.properties file and restart IIS.



Troubleshooting


Policy Agent for IIS

If you are experiencing problems with your installation try the following:

  • Check the installation log filleting%\DSAME_install.nnnn for errors.

  • Re-install by uninstalling and then installing.

  • Verify agent loading in IIS

    1. Launch Internet Services Manager

    2. Start >Programs > Administrative Tools > Internet Services Manager

    3. Open the properties for the host computer in the Tree Pane of the Internet Services Manager window that is titled Internet Information Services.

    4. The host computer name should appear in the tree underneath the Internet Information Services root.

    5. Click Edit in the Master Properties section of the Internet Information Services tab.

    6. Select the ISAPI Filters tab in the WWW Service Master Properties dialog that appears.

    7. Look for the filter name "DSAME agent."

      If the Filter name "DSAME agent" does not appear at all, then check that the installer was run, and look for any errors during installation. The install log is located at: %TEMP%\DSAME_install.nnnn

      A green arrow pointing up in the Status column to the right of the "DSAME agent" indicates the agent loaded successfully into IIS. A red arrow pointing down indicates that the filter failed to load. The most likely cause of the filter not loading successfully (red arrow) is that it cannot locate the required dll files.

    8. If the filter did not load successfully check the following:

      • Check the path of the Agent dll by clicking "DSAME agent" and then Edit. Ensure that the path in the text box labeled Executable is valid.

      • The agent also needs several dll files. Check that the following exist in the directory agent_install_directory\Agents\iis50\lib

        libamPolicy.dll

        libnspr4.dll

        libplc4.dll

        libplds4.dll

        nss3.dll

        ssl3.dll

    9. Check your system path to ensure that the agent_install_directory\Agents\iis50\lib directory is present.

    10. If the libraries are in your system path try rebooting the computer system.

  • IIS logs filter loading errors in the System Event Log. To check the event log:

    1. Start > Programs > Administrative Tools > Event Viewer

    2. Select the System Log

    3. Check for Error messages with Source W3SVC.

  • If the agent loads but returns HTTP 500 Internal Server Error for all URL requests to the IIS Web Server.

    This indicates that the agent has loaded but did not properly initialize. Returning HTTP 500 Internal Server Error for all HTTP requests is a fail-safe to protect URL resources when the Agent cannot initialize. The most likely cause is a DSAME agent or server misconfiguration or unavailability.

  • Check the agent debug log.

    The log is located by default at the agent_root directory.This is the best source of debug information for resolving initialization and agent operation issues. The log file directory is specified by the property: com.iplanet.services.debug.directory in the AMAgent.properties file located in the directory: agent_install_directory\Agents\iis50\config.

    The property com.iplanet.services.debug.level controls the verbosity of the log information. Setting this property to "message" yields the most debug information. The value "message" should not be used in production environments since it reduces performance and quickly generates large debug outputs to the file.

  • Check that the agent can locate the AMAgent.properties configuration file.

    The agent uses the registry key HKEY_LOCAL_MACHINE\Software\iPlanet\DSAME IIS Agent\5.0 to locate the AMAgent.properties file. The AMAgent.properties file is located at: agent_install_directory\Agents\iis50\config.

  • The agent uses the Application Event Log to log errors that occur before the debug log file specified in AMAgent.properties is started.

    1. Start> Programs > Administrative Tools > Event Viewer

    2. Select the Application Log

    3. Check for Error messages with Source DSAME IIS Agent.


Previous     Contents    
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated February 05, 2002