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



Chapter 4   Policy Agents for Windows NT

Sun ONE Identity Server Policy Agents work in tandem with Sun ONE Identity Server to grant or deny user access to web servers in an enterprise. 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 NT Web Server

The Sun ONE Policy Agent supports the following web server running on the Windows NT Server 4.0 SP6 operating system:

  • Microsoft IIS 4.0

Installation Using the GUI

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 Sun ONE Identity Server 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.

  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. To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next.

  5. Enter the information about the web server where this agent will be installed:

    6. Host Name: Enter the FQDN of the system where the Agent web server is installed. For example, mycomputer.siroe.com.

    IIS Document Root: Enter the document root directory. This directory needs to be accessible by the web server root w3svc.

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

    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.


    Note

    Agent uses value of com.sun.am.policy.agents.agenturiprefix property to support some essential functions such as notification and post data preservation. It is important to set a valid URL for this property. Its default value is:

    http://host.domain:port/agent_deployment_uri

    where host, domain and port are the FQDN and port number of the server where agent is installed. agent_deployment_uri is the prefix to URI which tells the web server where to look for agent's related HTML pages. Its default value is amagent.

    When all the information is entered correctly, click Next.

  6. Provide the following information about web server that runs Sun ONE Identity Server:

    7. Primary Server Host: Enter the FQDN of the system where the primary web server that runs Sun ONE Identity Server is installed. For example, myserver.siroe.com.

    Primary Server Port: Enter the port number for the web server that runs Sun ONE Identity Server.

    Primary Server Protocol: If the web server that runs Sun ONE Identity Server is SSL-enabled, select HTTPS; otherwise select HTTP.

    Primary Server Deployment URI: Enter the location that was specified when Sun ONE Identity Server was installed. The default URI for Sun ONE Identity Server is /amserver.

    Primary Console Deployment URI: Enter the location that was specified when Sun ONE Identity Server console was installed. The default URI for Sun ONE Identity Server is /amconsole.

    Failover Server Host: Enter the fully qualified name for the secondary web server that will run Sun ONE Identity Server if the primary web server becomes unavailable. If no failover host exists, then leave this field blank.

    Failover Server Port: Enter the port number of the secondary web server that runs Sun ONE Identity Server. If no failover host exists, then leave this field blank.

    Failover Server Deployment URI: Enter the location that was specified when Sun ONE Identity Server was installed. The default URI for Sun ONE Identity Server is /amserver.

    Agent Identity Server Shared Secret: Enter the password for the Identity Server internal LDAP authentication user password.

    Re-enter Shared secret: Re-enter the password for the Identity Server internal LDAP authentication user password.

    CDSSO Enabled: Check this box if you want to enable CDSSO feature.

    CDSSO Component URL: Enter the CDSSO Component URL.

  7. If all the information entered is correct, click Next.

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

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

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


    11. 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. From the Start Menu, choose Settings > Control Panel.

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

  3. In the Add/Remove Programs window, choose Sun ONE Identity Server Policy Agent.

  4. Click Change/Remove.

  5. Click Next on the Welcome panel.

  6. Click Uninstall Now.

  7. Click Close after uninstallation is complete.

Disabling a Policy Agent Installed on Microsoft IIS 4.0

  1. Launch Internet Services Manager.

    1. From the Start Menu, choose 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 pane, right click 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 "Sun ONE Identity Server Policy Agent."

      5. Click on 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 starting iisadmin and w3csvc.

Installation Using the Command-Line

The command-line version of the Installation program provides you an alternative to the GUI version.

To Install an Agent Using the Command Line

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

    2. setup.bat -nodisplay

  2. When prompted, provide the following information:

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

    Install Sun One Policy Server 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 the full path.

  3. 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 Part , "Installation Using the GUI"."

  4. When prompted, provide the following information about the web server that runs Sun ONE Identity Server Services:

    • Primary Server Host

    • Primary Server Port

    • Primary Server Protocol

    • Primary Server Deployment URI

    • Primary Console Deployment URI

    • Failover Server Host

    • Failover Server Port

    • Failover Server Deployment URI

    • Failover Console Deployment URI

    • Agent-Identity Server Shared secret

    • Re-enter Shared secret

    • CDSSO feature enabled

    • CDSSO Component URL

    For information about these items, refer to "Installation Using the GUI."

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

  6. The following text is displayed:


    7. Ready to Install

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

    What would you like to do

    When prompted, What would you like to do?, enter 1 to start the installation.

  7. The following text is displayed:

    Product                            Result     More Information
    1.  Sun ONE Identity Server Agent  Installed  Available
    2.  Done

    8. To see log information, enter 1. To exit the Installation program, enter 2.

  8. When installation is complete, 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:

    2. java uninstall_Sun_ONE_Identity_Server_Policy_Agent -nodisplay

  2. When prompted, provide the following information:

    3. The uninstaller detects agents that were previously installed using the setup program. Enter 1 to uninstall the agent.

  3. The following message is displayed:
    1. Uninstall Now
    2. Start Over
    3. Exit Uninstallation
    What would you like to do?

    4. When prompted, What would you like to do?, enter 1 to start the uninstallation.

  4. The following text is displayed:
    Product                            Result     More Information
    1.  Sun ONE Identity Server Agent  Full       Available
    2.  Done

    5. To see log information, enter 1. To exit the uninstallation program, enter 2.

  5. When uninstallation is completed, reboot the system.

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

    %TEMP%\Sun_ONE_Identity_Server_Policy_Agent_uninstall.*

Using Secure Sockets Layer (SSL) with an Agent

During installation, if you choose the HTTPS protocol, the agent is automatically configured and ready to communicate over SSL.


Note

Before proceeding with the following steps, ensure that the Web Server is configured for SSL.

The Agent's Default Trust Behavior

By default, the policy agent installed on a remote Microsoft IIS 4.0 will trust any server certificate presented over SSL by the web server that runs Sun ONE Identity Server services; the agent does not check the root Certificate Authority (CA) certificate. If the web server that runs Sun ONE Identity Server 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 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 Sun ONE Identity Server.

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.sun.am.policy.agents.trustServerCerts=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.sun.am.policy.agents.trustServerCerts=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 Sun ONE Identity Server.

To Install the Root CA Certificate on Microsoft IIS

  1. Go to the following directory:

    2. Agent_Install_Dir\iis\cert

  2. Add the same root certificate that is installed on the web server that runs Sun ONE Identity Server into the existing certificate database. At the command line, enter the following command:

    3. \Agent_Install_Dir\bin\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 NT the location is

      • Agent_Install_Dir\bin

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

    • For more information on certutil, type certutil -H

    To verify that the root certificate was installed properly in the certificate database, enter the following command:

    Agent_Install_Dir\bin\certutil -L -d .

    You should see the root certificate added and listed in the output of the command.

  3. Restart IIS.

Setting the REMOTE_USER Server Variable

The REMOTE_USER server environment variable can be set to a Sun ONE Identity Server 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. From the Windows Start menu, choose Programs > Windows NT Option Pack > Microsoft Internet Information Server > Internet Services Manager.

    2. This will launch the Microsoft Management Console.

  2. On the web site that you want the Sun ONE Identity Server 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 globally not-enforced URLs as specified in the AMAgent.properties file (these are URLs that can be accessed by unauthenticated users), you must set the following property in the AMAgent.properties file to TRUE (by default, this value is set to FALSE):

com.sun.am.policy.agents.anonRemoteUserEnabled=TRUE

When you set this property value to TRUE, the value of REMOTE_USER will be set to the value contained in the following property in the AMAgent.properties file (by default, this value is set to anonymous):

com.sun.am.policy.agents.unauthenticatedUser=anonymous

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

Shared Secret Encryption Utility

The Sun ONE Identity Server Policy Agent stores the shared secret in the AMAgent.properties file. By default, this password is the Identity Server internal LDAP authentication user password. This can be changed on the server side by editing the file AMConfig.Properties.

The property com.sun.am.policy.am.password in the file AMConfig.Properties is set with the encrypted shared secret while installing the agent.

To reset or change the shared secret, you can use the following utility and set the value in the property.

  1. Go to the following directory:

    2. Agent_Install_Dir\bin

  2. Execute the following script from the command line:

    3. cryptit shared_secret

  3. Cut and paste the output from Step 2 in the property:

    4. com.sun.am.policy.am.password

  4. Restart the Web Server and try accessing any resource protected by the agent. If the agent gets redirected to the Identity Server, this indicates the above steps were executed properly.

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%\Sun_ONE_Identity_Server_Policy_Agent_uninstall.nnnn

  • Re-install by uninstalling and then installing.

  • Verify agent loading in IIS:

    1. Launch Internet Services Manager.

    2. From the Start menu, choose Programs > Windows NT Option Pack > Microsoft Internet Information Server > Internet Services Manager.

      3. 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 "Sun ONE Identity Server Agent."

      7. If the Filter name "Sun ONE Identity Server 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%\Sun_ONE_Identity_Server_Policy_Agent_uninstall.nnnn

      A green arrow pointing up in the Status column to the right of the "Sun ONE Identity Server 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:

      8. # \Agent_Install_Dir\bin

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

      • Check the path of the Agent DLL by clicking "Sun ONE Identity Server 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 lib directory:

        • amsdk.dll

        ames6.dll

        libnspr4.dll

        libplc4.dll

        libplds4.dll

        libxml2.dll

        nss3.dll

        ssl3.dll

      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. From the Start menu, choose 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 Sun ONE Identity Server 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.sun.am.policy.am.logFile

    In the AMAgent.properties file located in the directory:

    Agent_Install_Dir\iis\config\_PathInstanceName

    Agent_Install_Dir\iis\config\_PathInstanceName

    The property com.sun.am.policy.am.loglevels controls the verbosity of the log information. Set the logging level for the specified logging categories.

    The format of the values is:

    ModuleName[:Level],ModuleName[:Level]]*

    The currently used module names are AuthService, NamingService, PolicyService, SessionService, PolicyEngine, ServiceEngine, Notification, PolicyAgent, RemoteLog, and all. If the level is omitted, then the logging module will be created with the default logging level, which is the logging level associated with the 'all' module.

    The all module can be used to set the logging level for all modules. This will also establish the default level for all subsequently created modules.The meaning of the 'Level' value is described below:

    The property com.sun.am.policy.am.loglevels controls the verbosity of the log information. The meaning of the 'Level' value is described below:

    0 = Disable logging from specified module*

    1 = Log error messages

    2 = Log warning and error messages

    3 = Log info, warning, and error messages

    4 = Log debug, info, warning, and error messages

    5 = Like level 4, but with even more debugging messages.

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

    • The agent uses the registry key

    HKEY_LOCAL_MACHINE\Software\Sun Microsystems\Identity Server IIS Agent to locate the AMAgent.properties file. The AMAgent.properties file is located at:

    Agent_Install_Dir\iis\config\_PathInstanceName

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

    1. From the Start menu, choose Programs > Administrative Tools > Event Viewer.

    2. Select the Application Log.

    3. Check for Error messages with Source Sun ONE Identity Server IIS Agent.

Cannot install Agent after previous installation is removed

The following is an example message displayed when you run the Agent installer:

"Sun ONE Identity Server Policy Agent 2.0 for Microsoft Internet Information Services is installed. Please refer to installation manual to configure this agent for another web server instance. Or uninstall it before installing another agent."

Possible Causes:

  • You might have an existing installation of Agent.

  • You might have a previously installed Agent and did not use Agent's uninstaller to uninstall the Agent.

  • The installer's productregistry file may be corrupted.

Solution:

  • Check that you have uninstalled any existing installation of Agent.

  • The productregistry file may be corrupted if there is no existing installation of Agent. This file is used by the installer to track installed products. It is found in C:\WINT\system32 directory.


    • Note

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

    Remove the Agent product entry in this file. This entry starts with the following lines:


    <compid>SUNWamcom
    <compversion>2.0
    <uniquename>SUNWamcom</uniquename>
    <vendor></vendor>
    ......
    </compid>
    <compid>Agent uninstall script
    <compversion>2.0
    <uniquename>Agent uninstall script</uniquename>
    <vendor>Sun Microsystems, Inc.</vendor>
    ......
    </compid>
    <compid>Agent installer resource bundle
    <compversion>2.0
    <uniquename>Agent installer resource bundle</uniquename>
    <vendor>Sun Microsystems, Inc.</vendor>
    ......
    </compid>
    <compid>Agent Common Core and SDK
    <compversion>2.0
    <uniquename>Agent Common Core and SDK</uniquename>
    <vendor></vendor>
    ......
    </compid>
    <compid>SUNWames6
    <compversion>2.0
    <uniquename>SUNWames6</uniquename>
    <vendor></vendor>
    ......
    </compid>
    <compid>Agent for ...
    <compversion>2.0
    <uniquename>Agent for ...</uniquename>
    <vendor></vendor>
    ......
    </compid>
    <compid>Sun ONE Identity Server Policy Agent
    <compversion>2.0
    <uniquename>Sun ONE Identity Server Policy Agent</uniquename>
    </compid>

Unable to uninstall Agent from Windows Start menu > Settings > Control Panel-> Add/Remove Programs.

Possible Cause: Java's classpath may not be set correctly on the machine.

Solution: Use the following steps to uninstall the Agent:

  1. Open command prompt window

  2. Go to the directory where Agent is installed

  3. Execute java uninstall_Sun_ONE_Identity_Server_Policy_Agent

Known Problems

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:

    2. c:\>net stop iisadmin /y

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

    1. From the Start menu, choose Settings > 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:

    3. c:\>net start iisadmin

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

    1. From the Start menu, choose Settings > 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:

    4. c:\>net start w3svc

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

    1. From the Start menu, choose Settings > Control Panel.

    2. Click on Services.

    3. Select World Wide Web Publishing.

    4. Click Start.

IIS 4.0 stop problem

After installing a Policy Agent on IIS 4.0, stopping individual web sites may occasionally lead to memory corruption messages. You can ignore these messages and restart the IIS server

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