Sun logo      Previous      Contents      Index      Next     

Web Policy Agents Guide

Chapter 3
Policy Agents on Microsoft Windows

This chapter explains how to install and configure Web Policy Agents available for the web servers running on Microsoft Windows operating system.

Topics include:

Before You Begin

Be sure that your are familiar with the concepts presented in Chapter 1, "Read This First." The chapter includes brief but important information on the following topics:

Overview of Policy Agents for Microsoft Windows

The Sun ONE Identity Server policy agents that support Microsoft Windows have some variety and the web servers they are deployed on can vary a great deal. For example, the architecture of Microsoft IIS web servers is quite unique, which can affect how you prepare for the installation of the policy agent. For more information, see "Preparing for Agent Installation on Microsoft IIS Web Servers".

Furthermore, some variety exists among the policy agents for Microsoft Windows in how they are installed and configured. The installation of the agents for Microsoft Windows can be categorized into two distinct types. Therefore, for purposes of written organization these agents have been divided in this chapter into the two following groups.

The agent installation program can be run in two modes: the graphical user interface (GUI) mode and the command-line interface (CLI) mode. The different installation types apply to the GUI mode. The CLI mode applies to all agents regardless of installation type.

Supported Servers for Microsoft Windows

The following table shows the installation type for each Sun ONE Identity Server policy agent that supports Microsoft Windows. The table also specifies which platforms each agent supports.

Table 3-1  Supported Servers for Microsoft Windows

Agent for

Supported Platform

Installation Type I

Sun ONE Web Server 6.0 SPx

Microsoft Windows 2000

IBM Lotus Domino 6.0.1

Microsoft Windows 2000

IBM Lotus Domino 5.0.11

Microsoft Windows 2000

Microsoft IIS 5.0

Microsoft Windows 2000

Sun ONE Web Server 6.1

Microsoft Windows 2000

SAP Internet Transaction Server 2.0

Microsoft Windows 2000 Advanced Server

Sun Java System Web Server 6.1

Microsoft Windows Server 2003 EE

IBM Lotus Domino 6.5

Microsoft Windows 2000

 

Microsoft Windows Server 2003 EE

Installation Type II

 

Microsoft IIS 6.0

Microsoft Windows Server 2003 EE

Apache 2.0.50

Microsoft Windows Server 2003 EE

The Agent Installation Types

All the Installation Type I agents share the same installation steps. The agents for Domino 5 and 6 require additional configuration of the Domino server.

Both the Installation Type II agents, Microsoft IIS 6.0 and Apache 2.0.50, also share the same installation steps. However, after the installation steps are completed, both of these agents require configuration. The configuration steps are divided into two sets of steps. The three sets of procedures for installation and configuration of the Installation Type II agents are as follows:

  1. Installing the agent
  2. Creating the agent configuration file for the web site that is to be protected by the agent
  3. Configuring the agent for that web site

Preparing for Agent Installation on Microsoft IIS Web Servers

The policy agent for Microsoft IIS 5.0 enforces policy on URL access for Microsoft's 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 system where the agent will be installed has a domain name set. If the web server that runs Sun ONE Identity Server 6.0 is running on a separate system, make sure the server is also in the DNS query list.

Note

The policy agent for Microsoft IIS 6.0 is an ISAPI application. It is deployed as a wildcard application mapping to a web site. This implies that the agent for Microsoft IIS 6.0 when deployed for a particular web site intercepts every request for accessing the resources on that web site. It does authentication and policy evaluation. If all the conditions are met the agent allows access to the resource.

One new feature in the agent for Microsoft IIS 6.0 is that multiple agents can be configured on the same machine. This was not possible in the policy agent for Microsoft IIS 5.0. Using this new feature, the policy agent can be configured for multiple web sites on multiple application pools. However, the agent cannot currently be configured for multiple web sites on the same application pool.

Installing and Configuring the Installation Type I Agents

This section explains how to install most policy agents supported on Microsoft Windows. For a list and explanation of the Installation Type I and Installation Type II agents, see "Overview of Policy Agents for Microsoft Windows". Of the Installation Type I agents, only the agents for Lotus Domino 5.0 and 6.0 require configuration. Therefore, this section provides the configuration steps for them only. This section does not explain how to install the agents for Microsoft IIS 6.0 and Apache 2.0.50. For instructions on installing the agents for these two web servers see "Installing the Installation Type II Agents".

The following steps help you to install the Installation Type I policy agents in the GUI mode. To install an agent in command-line mode, see "Installing Any Agent from the Command Line".

You must have administrator privileges to run the installation program.

  1. Unzip the product binaries.

    2. Note

    On Microsoft Windows 2003, the zip file is not automatically unpacked. Therefore, after you download the agents zip file, be sure to extract the zip file to a directory first and then execute setup.exe. To extract the zip file, right click on the zip file in the File Manager and select Extract. After extracting to a directory, double click setup.exe to execute it.

  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 want to install the agent.
  6. Enter the applicable information about the web server where this agent will be installed in the dialog box.

    7. The dialog box provides fields for entering the required information. Some of the information required varies depending upon the web server. You are prompted for information in the order shown in the following table.

    Table 3-2  Prompted Web Server Information

    Web Server

    Field

    Details

    All Supported Web Servers

    Host Name

    Enter the fully qualified domain name (FQDN) of the system where the agent web server is installed. For example, mycomputer.example.com.

    Microsoft IIS Specific

    IS Document Root

    Enter the document root directory. This directory needs to be accessible by the web server root World Wide Web Publishing Service (w3svc). This field is available only if you are installing the policy agent for Microsoft IIS

    Sun ONE Specific

    Web Server Instance Directory

    Enter the full path to the directory where the Sun ONE Web Server instance is located. This is the web server instance that the agent will protect. For example,

    /web_server_root/https-mycomputer.example.com

    IBM Lotus Domino Specific

    Lotus Domino Data directory

    Enter the full path to the directory where the Domino data is located. The default path is \Lotus\Domino. This field is applicable only if you are installing the policy agent for Lotus Domino 5.0 or 6.0.

    All Supported Web Servers

    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 Universal Resource Identifier (URI) on the agent.

    Note

    This URI is used to form the value of the com.sun.am.policy.agents.agenturiprefix property in AMAgent.properties. The value formed should be valid. The agent uses the value of the com.sun.am.policy.agents.agenturiprefix property to support some essential functions such as post data preservation. It is important that the value of this property be valid where the protocol, host, and port are reachable by external users. The following is the default value:

    Server_Protocol://Server_Host:Server_Port/amagent

  7. When all the information is entered correctly, click Next.
  8. Provide the following information about the web server that runs Sun ONE Identity Server:

    9. 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.example.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 FQDN 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. If no failover host exists, then leave this field blank.

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

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

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

  9. If all the information entered is correct, click Next.
  10. Review the installation summary to be sure that the information you’ve entered is correct. Note that it displays the CDCServlet URL if you have checked the CDSSO Enabled box in the previous panel. If you want to make changes, click Back. If all the information is correct, click Next.
  11. In the Ready to Install page, click Install Now.
  12. When the installation is complete, you can click Details to view details about the installation, or click Close to end the installation program.
  13. Restart your computer.

    14. Restarting your computer is necessary for the agent to work properly. The installation modifies the system path by appending to it the location of the agent libraries. This change takes effect only after your computer is restarted.

Configuration is only necessary for Lotus Domino 5 and 6. You must configure the Domino DSAPI filter as explained in "Configuring the Domino DSAPI Filter".

Configuring the Domino DSAPI Filter

The policy agent for Lotus Domino supports Domino versions 5.0 and 6.0. When configuring the DSAPI filter, you must direct the policy agent to use the DSAPI file filter appropriate to the version of Domino you are attempting to protect. Use the following procedure to configure the Domino DSAPI filter.

  1. In Lotus Domino Administrator, choose Administrator Tab > Server > All Server Documents.
  2. From the listed servers, select the server you want to configure.
  3. Click Internet Protocols > HTTP tab.
  4. At the DSAPI Filter File names field, enter Agent_Install_Dir\domino\bin\amdomino6.dll

    5. If you installing the agent for Lotus Domino 5, enter the DSAPI Filter file name as Agent_Install_Dir\domino\bin\amdomino.dll.

  5. Save the changes and close the window.
  6. Open Domino console and restart the server by entering the following commands:

    7. tell http quit

    load http

Configuring Domino DSAPI Filter for Multiple Server Partitions

If you are configuring Domino DSAPI Filter for multiple server partitions, you must:

You can configure the filter for the different partitions by performing the following steps:

  1. In Lotus Domino Administrator, choose Administrator Tab > Server > All Server Documents.
  2. From the listed servers, select the required server.
  3. Now go to Internet Protocols > HTTP.
  4. At the DSAPI Filter File names field, enter the following:

    5. Agent_Install_Dir\domino\bin\amdomino6.dll

    If you installing the agent for Lotus Domino 5, enter the DSAPI Filter file name as follows:

    Agent_Install_Dir\domino\bin\amdomino.dll

  5. Save the changes and close the window.
  6. Open Domino console and restart the server by entering the following commands:

    7. tell http quit

    load http

Installing Any Agent from the Command Line

In addition to the GUI mode of installation, the installation program also offers a command-line interface for installing an agent. The command-line interface applies to all agents, Installation Type I and Installation Type II agents. However, configuration is still necessary for Lotus Domino 5 and 6 amongst the Installation Type I agents and for both the Installation Type II agents.

Use the following steps to install the agent from the command-line.

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

    2. # setup.exe -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 Identity Server Policy Agent in this directory: Specify the directory where you want the agent to 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 that this agent will protect:
    • Host Name
    • Web Server Instance Directory, Lotus Domino Data Directory or IIS Document Root depending on the web server for which you are installing the agent.
    • Server Port
    • Server Protocol
    • Agent Deployment URI

      • For details on these items, see the corresponding information as described in "Installing and Configuring the Installation Type I Agents".

  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
    • Secondary Console Deployment URI
    • Agent-Identity Server Shared Secret
    • Re-enter Shared secret
    • CDSSO feature enabled

      • For details on these items, see the corresponding information as described in "Installing and Configuring the Installation Type I Agents".

  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:

    Ready to Install

    1. Install Now

    2. Start Over

    3. Exit Installation

    What would you like to do

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

  7. To see log information, enter 1. To exit the installation program, enter 2.
  8. Restart your computer

    9. Restarting your computer is necessary for the agent to work properly. The installation modifies the system path by appending to it the location of the agent libraries. This change takes effect only after your computer is restarted.

    Note

    If the Microsoft IIS 5.0 or the Lotus Domino policy agent was previously installed and uninstalled on your computer, you do not need to reboot the computer if you are installing the same agent in the same directory.

For the Installation Type I Agents, configuration is only necessary for Lotus Domino 5 and 6. You must configure the Domino DSAPI filter as explained in "Configuring the Domino DSAPI Filter".

For Installation Type II Agents, configuration is necessary for both agents. For detailed information, see "Configuring the Installation Type II Agents".

Installing the Installation Type II Agents

The following steps help you to install the Installation Type II policy agents in the GUI mode. To install an agent in command-line mode, see "Installing Any Agent from the Command Line".

To install the policy agent for Microsoft IIS 6.0 or Apache 2.0.50 perform the following steps:

  1. Unzip the product binaries.
  2. Double click setup.exe to run the installation program.
  3. In the Welcome window, click Next.
  4. Read the License Agreement and click Yes to accept the license agreement.
  5. Select the directory where you want to install the agent.

    6. The default directory is C:\Sun\Identity_Server\Agents\2.1. The installation program will install the agent under this directory.

  6. If you are given the option, click Create Directory.

    7. If the directory does not exist a dialog box appears giving you the option to create a directory.

  7. Click Install Now. The program installs the agent.
  8. Click Yes when the program asks if want to reboot the computer. Once the installation is complete, you must create agent configuration files to configure the agent for web sites. The following section explains the procedure for creating the agent configuration file.

Configuring the Installation Type II Agents

After you have installed an Installation Type II agent, Microsoft IIS 6.0 or Apache 2.0.50, you need to perform the following general procedures:

  1. Creating the agent configuration file for the web site that is to be protected by the agent
  2. Configuring the agent for that web site

Ensure that you create the agent configuration file before you configure the agent.Refer to the proper section as follows:

Creating the Microsoft IIS 6.0 Agent Configuration File

The agent for Microsoft IIS 6.0 provides a Visual Basic (VB) script to help you create the agent configuration file. When you run it, the VB script prompts for information related to the Web Site Identifier, the agent you are installing, and Sun ONE Identity Server and creates the agent configuration file based on the information. About the Web Site Identifier, Microsoft IIS 6.0 has a unique Identifier associated with every web site on the web server. The Web Site Identifier is displayed when you start the Microsoft Internet Information Services Manager and click Web Sites. The Identifier column indicates the unique identifier associated with every web site.

Note

When you are deploying the agent on multiple web sites, you must create a unique agent configuration file for each of the web sites. You can use the following steps to create multiple agent configuration files. Only, make sure that you give a unique file name to each of the configuration files.

To create the agent configuration file, perform the below steps.

  1. Change to the directory \Agent_Install_Dir\iis6\bin. This directory stores the script required to create the agent configuration file.
  2. Run the following command:

    3. cscript.exe IIS6CreateConfig.vbs defaultConfig

    where, IIS6CreateConfig.vbs is the VB script and defaultConfig is the agent configuration file created by this command.

    Note

    Make sure that you give a unique name for the configuration file since you will need the same file to unconfigure the agent.

    The script prompts for information as it progresses with the creation of the agent configuration file. The following is output from running the command.

    Microsoft (R) Windows Script Host Version 5.6

    Copyright (C) Microsoft Corporation 1996-2001. All rights reserved

    Copyright c 2004 Sun Microsystems, Inc. All rights reserved

    Use is subject to license terms

    -----------------------------------------------------

    Microsoft (TM) Internet Information Server (6.0)

    -----------------------------------------------------

    Enter the Agent Resource File Name [IIS6Resource.en] :

    Fully Qualified Host Name :

    drake1.red.iplanet.com

    Displaying the list of Web Sites and its corresponding Identifiers

    Site Name (Site Id)

    Default Web Site (1)

    Test web site (1285842265)

    Microsoft SharePoint Administration (2)

    Web Site Identifier :

    1

    Protocol [http] :

    Port Number [80] :

    Agent Deployment URI [/amagent] :

    ------------------------------------------------

    Sun Java (TM) Enterprise System Identity Server

    ------------------------------------------------

    Primary Server Host :

    drake2.red.iplanet.com

    Primary Server Protocol [http] :

    Primary Server Port [80] :

    Primary Server Deployment URI [/amserver] :

    Primary Server Console URI [/amconsole] :

    Failover Server Host :

    Agent-Identity Server Shared Secret:

    Re-enter Shared Secret :

    CDSSO Enabled [false]:

    -----------------------------------------------------

    Agent Configuration file created ==> defaultConfig

    Execute the below command for Agent Configuration :

    cscript.exe IIS6admin.vbs -config defaultConfig

    -----------------------------------------------------

  3. When prompted, provide the following information about the web server instance that this agent will protect:
  4. When prompted, provide the following information about the web server that runs Sun ONE Identity Server Services:

Creating the Apache 2.0.50 Agent Configuration File

The agent for Apache 2.0.50 provides a Visual Basic (VB) script to help you create the agent configuration file. When you run it, the VB script prompts for information related to, the agent you are installing and Sun ONE Identity Server and creates the agent configuration file based on the information.

Note

When you are deploying the agent on multiple web sites, you must create a unique agent configuration file for each of the web sites. You can use the following steps to create multiple agent configuration files. Only, make sure that you give a unique file name to each of the configuration files.

To create the agent configuration file, perform the following steps.

  1. Change to the directory \Agent_Install_Dir\apache\bin. This directory stores the VB script required to create the agent configuration file.
  2. Run the following command:

    3. cscript.exe ApacheCreateConfig.vbs defaultConfig

    where, ApacheCreateConfig.vbs is the VB script and defaultConfig is the agent configuration file created by this command.

    The script prompts for information as it progresses with the creation of the agent configuration file. The script prompts for information as it progresses with the creation of the agent configuration file. The following is output from running the command.

    Microsoft (R) Windows Script Host Version 5.6

        Copyright (C) Microsoft Corporation 1996-2001. All rights reserved

        Copyright c 2004 Sun Microsystems, Inc. All rights reserved

        Use is subject to license terms

        -----------------------------------------------------

         Apache 2.0.50 Server

        -----------------------------------------------------

        Enter the Agent Resource File Name [ApacheResource.en] :

        Fully Qualified Host Name :

        drake.red.iplanet.com

        Apache Binary Directory

        C:\Program Files\Apache2\bin

        Web Server Protocol [http] :

        Web Server Port [80] :

        Agent Deployment URI [/amagent] :

        ------------------------------------------------

        Sun Java (TM) Enterprise System Identity Server

        ------------------------------------------------

        Primary Server Host :

        tao.red.iplanet.com

        Primary Server Protocol [http]

        Primary Server Port Number [80] :

        Primary Server Deployment URI [/amserver] :

        Primary Server Console URI [/amconsole] :

        Agent-Identity Server Shared Secret:

        Re-enter Shared Secret :

        CDSSO Enabled [false]:

        -----------------------------------------------------

        Agent Configuration file created ==> defaultConfig

        Execute the below command for Agent Configuration :

         cscript.exe ApacheAdmin.vbs -config defaultConfig

    -----------------------------------------------------

  3. When prompted, provide the following information about the web server instance that this agent will protect:
  4. When prompted, provide the following information about the web server that runs Sun ONE Identity Server Services:

Configuring the Agent for Microsoft IIS 6.0 for a Web Site

Configure the agent for Microsoft IIS 6.0 for a web site after you have created an agent configuration file. If you have not already created an agent configuration file, create one as explained in "Creating the Microsoft IIS 6.0 Agent Configuration File".

Note

If you want to configure the agent for multiple web sites, you must create a separate agent configuration file for each of the web sites.

To configure the agent for a web site, follow these steps:

  1. Change to the directory \Agent_Install_dir\iis6\bin
  2. Run the following command:

    3. cscript.exe IIS6admin.vbs -config defaultConfig

    where defaultConfig is the agent configuration file.

    The script displays messages to indicate the progress of the configuration as shown in the following sample.

    Microsoft (R) Windows Script Host Version 5.6

    Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

    Copyright c 2004 Sun Microsystems, Inc. All rights reserved

    Use is subject to license terms

    Enter the Agent Resource File Name [IIS6Resource.en] :

    Creating the Agent Config Directory

    Creating the AMAgent.properties File

    Updating the Windows Product Registry

    Loading the IIS 6.0 Agent

    Completed Configuring the IIS 6.0 Agent

  3. Once the configuration is complete, change to the directory \Agent_Install_Dir\iis6\config\Identifier_1

    4. where Identifier_1 is the identifier of the web site for which the agent is being configured.

  4. Optionally, open the AMAgent.properties file and change the value of the property com.sun.am.logLevels to all:5.

    5. Before you modify any of the agent properties, refer the appendix Appendix A, "AMAgent Properties" for more information.

  5. Save the AMAgent.properties file.
  6. Restart the application pool and the web site.
  7. Try accessing the web site (http://fqdn:port/index.html). This link should take you to the Sun ONE Identity Server login page. After a successful authentication, if the policy is properly defined, the user should be able to view the resource.

If you want to view the agent log file amAgent, do so at the following location:

\Agent_Install_Dir\debug\Identifier_1

where Identifier_1 is the identifier of the web site for which the agent is being configured.

Note

If you want to configure the agent for multiple web sites, you must follow the above steps for each of the web sites.

Configuring the Agent for Apache 2.0.50 for a Web Site

Configure the agent for Apache 2.0.50 for a web site after you have created an agent configuration file. If you have not already created an agent configuration file, create one as explained in "Creating the Apache 2.0.50 Agent Configuration File".

Note

If you want to configure the agent for multiple web sites, you must create a separate agent configuration file for each of the web sites.

To configure the agent for a web site, follow these steps:

  1. Change to the directory \Agent_Install_dir\apache\bin
  2. Run the following command:

    3. cscript.exe Apacheadmin.vbs -config defaultConfig

    where defaultConfig is the agent configuration file.

    The script displays messages to indicate the progress of the configuration as shown in the following sample.

    Microsoft (R) Windows Script Host Version 5.6

        Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

        Copyright c 2004 Sun Microsystems, Inc. All rights reserved

        Use is subject to license terms

        Enter the Agent Resource File Name [ApacheResource.en] :

        Creating the AMAgent.properties File

        Modifying httpd.conf

        Completed Configuring the Agent for Apache 2.0.50.

        Re-start your server instance.

  3. Once the configuration is complete, change to the directory \Agent_Install_Dir\Apache\config\apache_80
  4. Optionally, open the AMAgent.properties file and change the value of the property com.sun.am.logLevels to all:5.

    5. Before you modify any of the agent properties, refer to Appendix A, "AMAgent Properties" for more information.

  5. Save the AMAgent.properties file.
  6. Change to the directory where the Apache server was installed.
  7. Restart the Apache 2.0.50 server.
  8. Try accessing the web site (http://drake.red.iplanet.com). This link should take you to the Identity Server login page. After a successful authentication, if the policy is properly defined, the user should be able to view the resource.

    9. If you want to view the agent log file amAgent, do so at the following location:

    \Agent_Install_Dir\debug\apache_portnumber

    where portnumber is the port number, such as 80, to which the agent is configured.

Note

If your web server is running in SSL and notification is enabled, make sure that you perform the following:

1.  Add the server certificate’s root CA certificate to the Identity Server’s certificate database.

2.  Mark the CA root certificate as trusted to enable Identity Server to send notifications to the agent successfully.

For more information on installing a trusted root CA certificate, refer to the documentation for your web server.

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

You should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation for Sun ONE Web Server at the following location on the Internet:

http://docs.sun.com/source/816-5682-10/esecurty.htm#1011961

The Agent’s Default Trust Behavior

This section only applies when Identity Server itself is running SSL. By default, the policy agent installed on a supported web server will trust any server certificate presented over SSL by the web server that runs Sun ONE Identity Server; 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.properties file, and by default it is set to true:

com.sun.am.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.trustServerCerts=false

Installing the Identity Server Root CA Certificate on the Agent Web Server

The root CA certificate that you install on the web server the agent protects must be the same one that is installed on the web server that runs Sun ONE Identity Server.

Installing the Root CA Certificate on Sun ONE Web Server

See the instructions for installing a root CA Certificate in the documentation that comes with the web server. Generally, this is done through the web server’s Administration console. Access the documentation for Sun ONE Web Server 6.0 on the Internet at the following URL: http://docs.sun.com/source/816-5682-10/esecurty.htm#1011961

Installing the Root CA Certificate on Domino Web Server

The CA certificate that you install on the Domino Web server must be the same one that is installed on the web server that runs Identity Server services.

  1. Go to the following directory:

    2. Agent_Install_Dir\Agents\domino\utils

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

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

    where:

    • cert-name can be any name for this certificate.
    • cert-dir is the directory where the certificate and key stores are located. The location is:

      • Agent_Install_Dir\Agents\domino\cert

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

      • For more information on the certutil utility, see the online help by entering the following command:

      certutil -H

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

    4. Agent_Install_Dir\bin\certutil -L -d cert-dir

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

    Table 3-3  Example of certutil -L Output

    Certificate Name                             Trust Attrubutes

    cert-name                                      C,C,C

    p Valid peer

    P Trusted peer (implies c)

    c Valid CA

    T Trusted CA to issue client certs (implies c)

    C Trusted CA to certs(only server certs for ssl) (implies c)

    u User cert

    w Send warning

     

  4. Restart Domino Web Server.

Installing the Root CA Certificate on Microsoft IIS 5.0

  1. Go to the following directory:

    2. Agent_Install_Dir\iis\cert

  2. Add the same root CA 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

    where:

    • cert-name can be any name for this root CA certificate.
    • cert-dir is the directory where the certificate and key stores are located. The location is:

      • Agent_Install_Dir\iis\cert

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

      • For more information on the certutil utility, see the online help by entering the following command:

      certutil -H

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

    4. Agent_Install_Dir\bin\certutil -L -d cert-dir

    You should see the root CA certificate added and listed in the output of the command. See Table 3-3 for an example of output after running the certutil -L command.

  4. Restart IIS.

Installing the Root CA Certificate on Microsoft IIS 6.0

You can use the certutil program to install the root CA certificate on Microsoft IIS 6.0.

  1. Check if the certificate database is created or not. To do this, open the Microsoft Windows command line and change to the following directory:

    2. Agent_Install_Dir\iis\cert

  2. Create the certificate database if you have not already done so, using the following command:

    3. \Agent_Install_Dir\bin\certutil -N -d .

  3. Install the root CA certificate.

    4. \Agent_Install_Dir\bin\certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

    where:

    • cert-name can be any name for this root CA certificate.
    • cert-dir is the directory where the certificate and key stores are located. The location is:

      • Agent_Install_Dir\iis6\cert

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

      • For more information on the certutil utility, see the online help by entering the following command:

      certutil -H

  4. To verify that the certificate is properly installed, at the command line, enter the following:

    5. \Agent_Install_Dir\bin\certutil -L -d cert-dir

    You should see the root CA certificate added and listed in the output of the command. See Table 3-3 for an example of output after running the certutil -L command.

  5. Restart IIS.

Installing the Root CA Certificate on Apache 2.0.50

  1. Go to the following directory: What is the directory for Apache 2.0.50? I’ve just started it below?

    2. \Agent_Install_Dir\apache\cert

  2. Add the same root CA 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

    where:

    • cert-name can be any name for this root CA certificate.
    • cert-dir is the directory where the certificate and key stores are located. The location is:
      Agent_Install_Dir\apache\cert
    • cert-file is the base-64 encoded root CA certificate file.

      • For more information on the certutil utility, see the online help by entering the following command:

      certutil -H

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

    4. Agent_Install_Dir\bin\certutil -L -d cert-dir -i cert-file

    You should see the root CA certificate added and listed in the output of the command. See Table 3-3 for an example of output after running the certutil -L command.

  4. Restart Apache 2.0.50 Server

Setting the REMOTE_USER Server Variable

The REMOTE_USER server environment variable is normally set by the agent to the user ID of the user who is accessing the page after being authenticated with Identity Server. By setting this variable to a specific user, the user becomes available to web applications (such as a CGI, servlet, or an ASP program). This feature makes it possible to personalize the content of displayed HTML pages to specific users.

However if the page a user is accessing is not enforced, the REMOTE_USER variable will not be set. To enable setting the REMOTE_USER for not-enforced URLs, you must set

the following property in AMAgent.properties to true (by default the value is 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

To enable the REMOTE_USER feature for an IIS 5.0 agent, perform the following steps:

  1. From the Windows Start menu, select Programs > Administrative Tools > Internet Services Manager.

    2. This will launch the Internet Information Services 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.
  5. In the dialog that displays, select Anonymous Access and Basic Authentication, then deselect Integrated Windows Authentication.

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.

POST Data Preservation

POST data preservation is supported on the Sun ONE Web Server 6.0 SPx agent and the Sun ONE Web Server 6.1 agent. Users can preserve POST data, which are submitted to web servers through html forms before users login to the Identity server. Presumably the html page containing the form should be in the not-enforced list. By default, this feature is turned off.

This feature is configurable through two properties in AMAgent.properties file. To turn off this feature, use the following AMAgent.properties file property and change the value of the property from true to false:

com.sun.am.policy.agents.is_postdatapreserve_enabled=true

The second property decides how long any POST data can stay valid in the web server cache. After the specified interval, a reaper thread will wake up and clean up any POST cache entries that have lived beyond the specified life time. The following property helps the administrator to configure this time interval. By default this property is set to 10 minutes.

com.sun.am.policy.agents.postcacheentrylifetime=10

Note

This feature is not available on the other agents.

Shared Secret Encryption Utility

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

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

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

To reset the shared secret
  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.

Disabling, Uninstalling, and Unconfiguring Microsoft Windows Policy Agents

When you no longer require a Microsoft Windows policy agent, you can disable it, or you can uninstall it. If you no longer require a policy agent to protect a particular web site, you can unconfigure the agent from that web site.

Disabling Microsoft Windows Policy Agents

Microsoft IIS web servers provide a tool that allows you to disable the web server. Therefore, instructions are provided here for disabling the Microsoft IIS web servers using that tool.

Disabling the Policy Agent Installed on Microsoft IIS 5.0

The following steps help you disable an agent installed on Microsoft IIS.

To disable an agent on Microsoft IIS
  1. Launch Internet Services Manager.
    • From the Start menu, choose 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 Sun ONE Identity Server Agent.

      6. 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 the Policy Agent on Microsoft IIS 6.0

Follow these steps to unconfigure the policy agent installed on Microsoft IIS 6.0:

  1. From the Microsoft Windows Start menu, choose Programs > Administrative Tools > Internet Information Services Manager.
  2. Right click on the web site protected by the policy agent.
  3. Open the Properties tab.
  4. Click on Home Directory.
  5. Click on Configuration.
  6. Click \Agent_Install_dir\iis6\bin\amiis6.dll
  7. Click on Remove.
  8. Click Yes at the popup “Remove the selected Script Mapping(s)?.”
  9. Click Ok.
  10. Restart the application pool to which the web site belongs.
  11. Restart the web site.

Uninstalling Installation Type I Policy Agents

This section is divided into two subsections explaining how to uninstall Installation Type I policy agents: "Uninstalling Most Installation Type I Policy Agents" provides instructions for uninstalling all the Installation Type I policy agents except for Lotus Domino 5 or 6. For these Domino agents, see "Uninstalling the Agents for Lotus Domino 5 or 6".

For a list and explanation of the Installation Type I and Installation Type II agents, see "Overview of Policy Agents for Microsoft Windows"

Uninstalling Most Installation Type I Policy Agents

To uninstall Installation Type I policy agents
  1. From the Windows 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 Welcome panel.
  6. Click Uninstall Now.
  7. Click Exit after uninstallation is complete.

Uninstalling the Agents for Lotus Domino 5 or 6

To uninstall the policy agent for Lotus Domino 5 or 6, you should perform the following steps on the Lotus Domino Administrator client from a Windows machine.

To uninstall the agent for Lotus Domino
  1. Launch Lotus Domino Administrator.
  2. Choose Administrator Tab > Server > All Server Documents.
  3. From the listed servers, select the server you want to uninstall.
  4. Click Internet Protocols > HTTP tab.
  5. Remove the DSAPI filter file name specified for the agent and leave this field blank.
  6. Click the Save and Close button to save the changes.
  7. Open Domino console and restart the server by entering the following commands:

    8. tell http quit

    load http

  8. From the Start Menu, choose Settings > Control Panel.
  9. In the Control Panel, double-click Add / Remove Programs.
  10. In the Add/Remove Programs window, choose Sun ONE Identity Server Policy Agent and click on Change/Remove.
  11. In the Welcome Panel, click Next.
  12. In the Ready to Uninstall Panel, click Uninstall Now.
  13. Click Exit after uninstallation is complete.

Uninstalling Any Agent from the Command-Line

In addition to the GUI mode of uninstallation, the uninstallation program also offers a command-line interface for uninstalling an agent. The command-line interface applies to all agents, Installation Type I and Installation Type II agents. However, Installation Type II agents, first require you to unconfigure the agent from each web site as explained in "Unconfiguring and Uninstalling Installation Type II Policy Agents".

To uninstall an agent from 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

    The uninstallation program displays the following text:

    1. Uninstall Now

    2. Start Over

    3. Exit Uninstallation

    What would you like to do?

  2. Enter 1 to start the uninstallation.

    3. The uninstallation program displays the following text:

    Product                            Result     More Information

    1.  Sun ONE Identity Server Agent  Full       Available

    2.  Done

  3. To see log information, enter 1. To exit the uninstallation program, enter 2.
  4. When the uninstallation is completed, you must reboot the system.

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

    %TEMP%\Sun_ONE_Identity_Server_Policy_Agent_uninstall*

Unconfiguring and Uninstalling Installation Type II Policy Agents

If you no longer require an Installation Type II policy agent, Microsoft IIS 6.0 or Apache 2.0.50, to protect a particular web site, you can unconfigure the agent from that web site. Furthermore, if you want to uninstall an Installation Type II agent, you must first unconfigure the agent from all the web sites for which it was configured.

Unconfiguring the Agent for Microsoft IIS 6.0 From a Web Site

Perform the following steps to unconfigure the agent for Microsoft IIS 6.0 from a web site. Make sure that you use the agent configuration file specific to the web site you want to unconfigure.

If you need to unconfigure the agent from multiple web sites, you must repeat these steps for each of the web sites. If you want to uninstall the agent for Microsoft IIS 6.0, you must first unconfigure the agent from all the web sites for which it is configured

  1. Stop the web site for which you have configured the agent and the application pool to which the web site belongs.
  2. Change to the directory \Agent_Install_Dir\iis6\bin
  3. Run the following VB script to unconfigure the agent:

    4. cscript.exe IIS6admin.vbs -unconfig defaultConfig

    where, IIS6admin.vbs is the configuration script and defaultConfig is the agent configuration file.

    The script unconfigures the agent and displays the following messages.

    Microsoft (R) Windows Script Host Version 5.6

    Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

    Copyright c 2004 Sun Microsystems, Inc. All rights reserved

    Use is subject to license terms

    Enter the Agent Resource File Name [IIS6Resource.en] :

    Removing the Agent Config Directory

    Removing the entries from Windows Product Registry

    Unloading the IIS 6.0 Agent

    Completed Unconfiguring the IIS 6.0 Agent

The unconfiguration does the following:

Unconfiguring the Agent for Apache 2.0.50 From a Web Site

Perform the following steps to unconfigure the agent for Apache 2.0.50 from a web site. Make sure that you use the agent configuration file specific to the web site you want to unconfigure.

If you need to unconfigure the agent from multiple web sites, you must repeat these steps for each of the web sites. If you want to uninstall the agent for Apache 2.0.50, you must first unconfigure the agent from all the web sites for which it is configured

  1. Stop the web site for which you have configured the agent and the application pool to which the web site belongs.
  2. Change to the directory \Agent_Install_Dir\apache\bin
  3. Run the following VB script to unconfigure the agent:

    4. cscript.exe Apacheadmin.vbs -unconfig defaultConfig

    where, Apacheadmin.vbs is the configuration script and defaultConfig is the agent configuration file.

    The script unconfigures the agent and displays the following messages.

        Microsoft (R) Windows Script Host Version 5.6

        Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

        Copyright c 2004 Sun Microsystems, Inc. All rights reserved

        Use is subject to license terms

        Enter the Agent Resource File Name [ApacheResource.en] :

        Removing the agent configuration directory

        Restoring the original httpd.conf

        Completed Unconfiguring the Agent for Apache 2.050. Re-start your server instance

The unconfiguration does the following:

Uninstalling Installation Type II Policy Agents

The steps for uninstalling the agent are the same for both Microsoft IIS 6.0 and Apache 2.0.50.

Before running the uninstallation program, ensure that you have already unconfigured the agents from all the web sites for which they were configured as explained in the applicable section:

Please perform the following steps to uninstall the agent:

  1. Change to the directory \Agents_Install_Dir\
  2. Run the following command to uninstall the agent:

    3. java uninstall_Sun_Java_tm__System_Identity_Server_Policy_Agent

  3. Click Next on the Welcome panel.
  4. Click Uninstall Now.

    5. The program uninstalls the agent.

  5. Reboot the computer.

Troubleshooting

Cannot install the agent after a previous installation is removed

The following is an example message displayed when you run the agent installation program:

"Sun ONE Identity Server Policy Agent 2.1 for Sun ONE Web Server 6.0 SPx 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:

Solution:

Unable to uninstall the 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 Agent_Install_Dir
  3. Execute command:

    4. java uninstall_Sun_ONE_Identity_Server_Policy_Agent

Lotus Domino 6

Domino Web Server starts with an error message “Unable to load filter”.

Ensure that you have set the Domino DSAPI filter correctly. For steps to do this, see the section "Configuring the Domino DSAPI Filter".

Domino DSAPI Filter is not functioning properly on the partitioned server.

Possible Cause: The database you have selected while configuring the DSAPI Filter may be wrong.

Solution: Ensure that you have selected the correct database while configuring the DSAPI filter.

Possible Cause: The partitioned database might not have been updated.

Solution: You might have to replicate the database from the Domino Admin Server.

The agent goes into an infinite loop if the users who are redirected to the resource mentioned in the property com.sun.am.policy.agents.accessDeniedURL do not have the “Get/allow policy” assigned to them.

Solution: Assign “Get/allow policy” to all users of the resource mentioned in the com.sun.am.policy.agents.accessDeniedURL property.

Microsoft IIS 5.0 Policy Agent

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

Known Problems

Agents are not effective after modification of Sun ONE Web Server configuration using the admin console.

The changes made by the agent installation to the server configuration files are overwritten by saving the changes in admin console.

The right procedure when using the admin console should be to load configuration first (from disk file to memory), then make modification, and save the changes (from memory to disk) by clicking the Apply button.

Microsoft IIS 5.0 agent

After installing the policy agent on Microsoft IIS 5.0, stopping individual web sites may occasionally lead to memory corruption messages. You can ignore these messages and restart the Microsoft IIS server.



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.