Previous     Contents    
iPlanet Policy Agent Pack Installation Guide


Chapter 4   URL Policy Agents for Windows NT


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 IIS 4.0 running on the Windows NT operating system, version 4.0, with Service Pack 6.

Topics include:



Supported Windows Web Server

The Agent Pack supports the following Web Server on the Windows NT Server 4.0 SP6 operating system:

  • Microsoft IIS 4.0



Before You Begin

Be sure you're familiar with the concepts presented in Chapter 1 "Read This First" on page 11. 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 4.0

The IIS agent enforces policy on URL access for Microsoft's Internet Information Services (IIS 4.0) 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 4.0

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 4.0" and click Next.

  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 Agent Web Server is installed. For example, mycomputer.iplanet.com.

    Web Server Document Root: Enter the document root directory. This directory needs to be 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 your 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.

  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.


    Note If the IIS 4.0 agent was already installed on your machine, you do not need to reboot if you are installing the same IIS 4.0 agent in the same directory.



Uninstalling and Disabling URL Policy Agents

When you no longer require the URL policy agent, you can uninstall it or disable it.


Uninstalling 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 the Welcome panel.

  6. On the 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 4.0

  1. Launch Internet Services Manager.

    1. In the Start Menu, click Programs > Windows NT 4.0 Options Pack > Microsoft Internet Information Server: Internet Services Manager.

  2. Check the status of the filter.

    1. In the left side of the window, right click on the hostname of the computer and select Properties.

    2. In the Master Properties section, select WWW Service, and click Edit.

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

    4. Highlight the filter named "DSAME Agent."

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

    5. Click Remove

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

  3. Restart Microsoft IIS 4.0 by stopping iisadmin, and then staring iisadmin and w3csvc.



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 4.0

    First, do one of the following:

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

    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.

    Web Server Doocument Root: Enter the document root directory. The directory needs to be accessible by the web server root w3svc.

    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.

  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 IIS 4.0 .


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 only one instance of IIS per computer system, and you can install only one global agent per IIS. The global agent protects all websites on the server.



Using Secure Sockets Layer (SSL) with an Agent


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 with DSAME services.


The Agent's Default Trust Behavior

By default, the URL policy agent installed on a remote Microsoft IIS 4.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 Microsoft IIS:

  1. Go to the root certificate directory, agent_install_directory\Agents\iis40\utils.

  2. Add the same root certificate, which 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

    use 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\iis40\cert.

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

    • For more information on certutil, type certutil -H



Setting the Remote_User Server Variable

This feature allows the REMOTE_USER server environment variable to be set to the DSAME authenticated user, or anonymous user, and make it available to web applications such as CGI, or Servlet and ASP programs, to personalize content.

To enable the REMOTE_USER feature, perform the following steps:

  1. In the Windows Start menu, select Programs > Windows NT Option Pack > Microsoft Internet Information Server > Internet Services Manager.

    This will launch the Microsoft Management Console.

  2. On the web site that you want the DSAME agent to protect, select Properties.

  3. Select the Directory Security tab.

  4. In the Anonymous Access and Authentication Control section, click Edit, and select Allow Anonymous Access (selected by default), Basic Authentication (not selected by default), and deselect Challenge/Response (selected by default).

To enable the REMOTE_USER setting for globally non-enforced pages by unauthenticated users, the com.iplanet.am.policy.agents.anonRemoteUser.enable property must be set to true (by default, it is set to false). This property can be found in the AMAgent.properties file located in <agent_root>\Agents\iss40\config.

The com.iplanet.am.policy.agents.unauthenticatedUser property will be used for the value of the REMOTE_USER setting. By default, it is set to anonymous.



Troubleshooting



Policy Agent for IIS 4.0

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

  • Check the installation log file %TEMP%\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 > Windows NT Option Pack > Microsoft Internet Information Server > Internet Services Manager.

      This will launch the Microsoft Management Console.

    3. In the left window, right click on the hostname of the computer and select Properties.

    4. In the Master Properties section, select WWW Service and click Edit.

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

    6. 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.

    7. 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\iis40\lib

        libamUrlAccessAgentIis40.dll

        libamPolicy.dll

        libnspr4.dll

        libplc4.dll

        libplds4.dll

        nss3.dll

        ssl3.dll

        smime3.dll

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

    9. 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, it 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\iis40\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\4.0 to locate the AMAgent.properties file. The AMAgent.properties file is located at: agent_install_directory\Agents\iis40\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.



Known Issue

The following section contains a description of a known issue that you should be aware of before using this product.


Issue

Internet services hang when you attempt to shutdown individual websites.


Workaround

It is highly recommended that you do not shut down your websites individually. Instead, you should shut them down collectively by stopping the IIS Admin Service, restarting the IIS Admin Service, and then restarting the individually managed services.

  1. To stop the IIS Admin Service, issue the following command from the command line:

    c:\>net stop iisadmin /y

    Alternatively, you can shutdown the IIS Admin Service from the Services menu:

    1. Under the Start menu, select Control Panel.

    2. Click on Services.

    3. Select IIS Admin Service.

    4. Click Stop.

    This will shutdown all internet services managed by the iisadmin process, including FTP services, WWW services and SMTP services.

  2. To restart the ISS Admin Service, issue the following command from the command line:

    c:\>net start iisadmin

    Alternatively, you can restart the services from the Services menu:

    1. Under the Start menu, select Control Panel.

    2. Click on Services.

    3. Select IIS Admin Service.

    4. Click Start.

  3. To restart the individual services, issue the following command from the command line:

    c:\>net start w3svc

    Alternatively, you can restart the individual services from the Services menu:

    1. Under the Start menu, select Control Panel.

    2. Click on Services.

    3. Select World Wide Web Publishing.

    4. Click Start.


Previous     Contents    
Copyright © 2002 Sun Microsystems, Inc.

Last Updated March 28, 2002