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



Chapter 4   Policy Agent Pack 1.1 on Windows NT


Sun ONE Identity Server Policy Agents work in tandem with Sun ONE Identity Server (also referred as DSAME) to grant or deny user access to web servers in an enterprise. The Policy Agent Pack 1.1 provides a set of 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:



Before You Begin

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


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



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 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 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 system where the Agent web server is installed. For example, mycomputer.siroe.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 system where the primary web server that runs DSAME services is installed. For example, myserver.siroe.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 previously installed and uninstalled 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 Policy Agents

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


Uninstalling a 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.1.

  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 Policy Agent Installed on Microsoft IIS 4.0

  1. Launch Internet Services Manager.

    • 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:

    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 check mark appears beside your choice, enter 0 to continue.

  4. When prompted, provide the following information about the web server instance this Agent will protect:

    • Host Name

    • Web Server Port

    • Web Server Protocol

    • Web Server Doocument Root

    • Agent Deployment URI

    For information about these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 66.

  5. When prompted, provide the following information about the web server that runs DSAME Services:

    • Host Name

    • Port Number

    • Protocol

    • Deployment URI

    • Failover Host

    • Failover Port

    For information about these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 66.

  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_Install_Dir 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 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, a policy agent installed on a Microsoft IIS 4.0 that will trust any server certificate presented over SSL by the web server that runs DSAME services; the agent does not check the Certificate Authority (CA) certificate. If the web server that runs DSAME services is SSL-enabled, and you want the policy agent to perform certificate-checking, you must do two things:

  1. Disable the agent's default trust behavior.

  2. Install CA certificate on the web server where the agent is installed. The 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 CA Certificate

The CA certificate that you install on the web server must be the same one that is installed on the web server that runs DSAME services.


To Install the CA certificate on Microsoft IIS

  1. Navigate to the following directory:

    Agent_Install_Dir\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_Dir\Agents\iis40\cert

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

    • For more information on certutil, type certutil -H

  3. Restart IIS.



Setting the REMOTE_USER Server Variable

The REMOTE_USER server environment variable can be set to a DSAME authenticated user or anonymous user. By setting this variable to a specific user, the user becomes available to web applications (such as a CGI, servlet, or ASP program). This feature makes it possible to personalize the content of displayed HTML pages to specific users.

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

REMOTE_USER will be set while accessing allowed URLs.

To enable the REMOTE_USER setting for a globally not-enforced list 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_Install_Dir\Agents\iis40\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.



Forwarding LDAP User Attributes via HTTP Headers


DSAME agents has the ability to forward LDAP user attribute values via HTTP headers to end web applications. The LDAP user attribute values come from the server side of DSAME. A DSAME agent behaves like a broker to obtain and relay user attribute values to the destination servlets, CGI scripts, or ASP pages. These applications can in turn use the attribute values to personalize page content.

This feature is configurable through two properties in AMAgent.properties file. To turn this feature on and off, use the following AMAgent.properties file property:

com.iplanet.am.policy.agents.foward_ldapattr_in_http_headers.enable

By default, this property is set to false, and the feature off. To turn on attribute forwarding, set this property to true. To configure the attributes that are to be forwarded in the HTTP headers, use the AMAgent.properties file property com.iplanet.am.policy.agents.ldapattr.

Below is an example section in the AMAgent.properties file which shows how this feature is used:

# Ldap User Attributes
# format: ldap_attribute_name|http_header_name
#
# below are a few notes based on different behaviours of web servers
#
# NOTE: for iWS agents, "http_header_name" must be in lower-case letters,
# and any _ will become -
# NOTE: for IIS and Apache agents, "http_header_name" will be prefixed
# by HTTP_, and all lower case letters will become upper case,
# and any - will become _
#
com.iplanet.am.policy.agents.ldapattr=cn|common-name,ou|organiza tion-unit,o|organization,c|country,mail|email,employeenumber|emp loyee-number

By default, some LDAP user attribute names and HTTP header names are set to sample values.

To find the appropriate LDAP user attribute names, check the following XML file on the machine where the DSAME server is installed:

DSAME_Install_Dir/SUNWam/config/xml/amUser.xml

The attributes in this file could be either DSAME User attributes or DSAME Dynamic attributes (for explanation of these two types of user attributes, refer to the DSAME Administration Guide).

The attribute and HTTP header names that need to be forwarded must be determined by the end-user applications on the web server that the agent is protecting—after all, these applications are the consumers of the forwarded header values (the forwarded information is used for the customization and personalization of web pages).


Note

Each web server has its own peculiarities about HTTP header name conventions. For more information on this feature, refer to the comments listed before each property in the AMAgents.properties file.




Validating Client IP Addresses


This feature can be used to enhance security by preventing the stealing or "hijacking" of SSO tokens.

The AMAgent.properties file contains a property titled com.iplanet.am.policy.agents.client_ip_validation.enable, which by default is set to false.

If you set this property value to true, client IP address validation will be enabled for each in-coming request that contains an SSO token. If the IP address from which request was generated does not match the IP address issued for the SSO token, the request will be denied. This is essentially the same as enforcing a deny policy.

This feature should not be used, however, if the client browser uses a web proxy or if there is a load-balancing application somewhere between the client browser and the agent-protected web server. In such cases, the IP address appearing in the request will not reflect the real IP address on which the client browser runs.



Troubleshooting the IIS 4.0 Policy Agent


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

  • Check the installation log file for errors:

    %TEMP%\DSAME_install.nnnn

  • 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. Check your system path to ensure that the following directory is present:

      Agent_Install_Dir\Agents\iis40\lib

    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 files exist in the Agents\iis40\lib directory:

        libamUrlAccessAgentIis40.dll

        libamPolicy.dll

        libnspr4.dll

        libplc4.dll

        libplds4.dll

        nss3.dll

        ssl3.dll

        smime3.dll

    9. If the libraries are in your system path, try rebooting the 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_Install_Dir 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_Dir\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_Dir\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. Choose Start > Programs > Administrative Tools > Event Viewer.

    2. Select the Application Log.

    3. Check Error messages with Source DSAME IIS Agent.



Known Issues


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     Next     
Copyright 2002   Sun Microsystems, Inc. All rights reserved.

Last Updated November 20, 2002