Sun logo      Previous      Contents      Index      Next     

Web Policy Agents Guide

Chapter 2
Policy Agents on Solaris and HP-UX

SunTM ONE Identity Server Policy Agents work in tandem with SunTM ONE Identity Server to control user access to web servers in an enterprise. This chapter explains how to install and configure the Web Policy Agents available for the web and proxy servers running on Solaris 8 and 9 and HP-UX 11.11 operating systems.

Topics in this chapter include:

Before You Begin

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

Installing the Agent

The agent installation program has two interfaces: the Graphical User Interface (GUI) and the Command-Line Interface (CLI). The following sections present instructions to install the agent using both these interfaces.

Installation Using the GUI

Use the following instructions to install the agent using the GUI on the Solaris and HP-UX operating systems.

Installing the Policy Agent for a Web Server

You must have root permissions when you run the agent installation program.

  1. Unpack the product binary using the following command:

    2. # gunzip -dc binaryname.tar.gz| tar -xvof -

  2. Run the setup program. You’ll find the program in the directory where you untarred the binaries. At the command line, enter the following:

    3. # ./setup

  3. Set your JAVAHOME environment variable to a JDK version 1.3.1_04 or higher. The installation requires that you set up your JAVAHOME variable correctly. However, if you have incorrectly set the JAVAHOME variable, the setup script will prompt you for supplying the correct JAVAHOME value:

    4. Please enter JAVAHOME path to pick up java:

  4. Type the full path to the directory where JDK is located. The installation program starts with the Welcome page.
  5. In the Welcome page, click Next.
  6. Read the License Agreement. Click Yes to agree to the license terms.
  7. In the Select Installation Directory panel, specify the directory where you would like to install the agent.

    8. Install Sun ONE Identity Server Policy Agent in this directory: Enter the full path to the directory where you want to install the agent. The default installation directory is /opt.

  8. Click Next and provide the following information about the web server the agent will protect:

    9. Host Name: Enter the FQDN of the machine where the web server is installed. For example, mycomputer.eng.example.com

    Web Server Instance Directory: This prompt appears only if you are installing the agent for Sun ONE Web Server. Specify the web server instance that this agent will protect. Enter the full path to the directory where the web server instance is located. Example: /web_server_root/https-mycomputer.example.com

    Configuration Directory: Specify the directory where the httpd.conf file is located. This field appears only when you are installing the agent for IBM HTTP server.

    Apache Binary Directory: Select the directory where the Apache binary, that is, httpd binary is installed. This field appears only when you are installing the agent for Apache Server.

    Lotus Domino Data directory: Enter the full path to the directory where the Domino data is located. The default data directory is /local/notesdata. This field is available only if you are installing the policy agent for Lotus Domino.

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

    Web Server Protocol: If the web server has been configured for SSL, choose HTTPS; otherwise choose HTTP.

    Agent Deployment URI: Enter a Universal Resource Identifier (URI), which will be used to access the agent. The default value is /amagent.

    Note

    The agent uses the value of the com.sun.am.policy.agents.agenturiprefix property to support some essential functions such as notification and post-data preservation. Agent URI prefix is a configurable subset of Agent Deployment URI. It is important to set a valid URL for this property. Its value should be http://host.domain:port/agent_deployment_uri where host, domain and port are FQDN and port number of the web server where the agent is installed and agent_deployment_uri is the URI where the web server will look for agent's related HTML pages. Its default value is amagent.

    SSL Ready: The installation program displays this option only when you are installing the Apache web server agent. Select this option if the Apache web server you are using has support for SSL. Your Apache web server is considered SSL ready if it has support for mod_ssl and its sources have been compiled using EAPI rule.

    To find out if your Apache web server has been compiled with the EAPI flag, go to the bin directory of the Apache web server and type the command:

    # ./httpd -V

    You can see various flags that the Apache web server was compiled with. If the flag -D EAPI is displayed in this list, it indicates that your Apache Web Server is SSL ready. However, if you do not see this flag, it does not necessarily indicate that the Web Server does not have support for mod_ssl.

    The supported configuration for Apache web server are:

    • Apache web server without mod_ssl support
    • Apache web server with mod_ssl and EAPI flag enabled.

      • Note

      Apache web server with mod_ssl support and EAPI flag disabled configuration is not supported by Sun ONE Identity Server policy agents.

  9. When you have entered all the information correctly, click Next.
  10. Enter information about the web server that runs Sun ONE Identity Server. The policy agent will connect to this server.

    11. 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.eng.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 server 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 server 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 server host exists, then leave this field blank.

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

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

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

  11. When all the information is entered correctly, click Next.
  12. 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.

    13. If you want to make changes, click Back. If all the information is correct, click Next.

  13. In the Ready to Install panel, click Install Now.
  14. When the installation is complete, you can click Details to view details about the installation, or click Exit to end the installation program.
  15. If you are installing the agent for Sun ONE Web Server or Apache web server, you must restart the web server for the installation to be complete.

    16. Note

    If you are installing the policy agent for Lotus Domino 5, you must configure the Domino DSAPI filter after installation. See the section "Web or Web Proxy Server Running in SSL Mode" for detailed steps.

Installing the Policy Agent for a Web Proxy Server

Use these instructions to install the policy agent for Sun ONE Web Proxy Server 3.6 (in reverse proxy mode) using the GUI on the Solaris 8 operating system.

You must have root permissions when you run the agent installation program.

  1. Unpack the product binaries using the following command:

    2. # gunzip -dc agent_SunOS_proxy.tar.gz | tar -xvof -

  2. Run the setup program. You will find the program in the directory where you untarred the binaries. At the command line, enter the following:

    3. # ./setup

  3. In the Welcome page, click Next.
  4. Read the License Agreement. Click Yes to agree to the license terms.
  5. To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next.
  6. When prompted, provide the following information about the web proxy server where this agent will be installed:

    7. Host Name: Enter the FQDN of the system where the remote web server is installed. For example, mycomputer.example.com.

    Proxy Server Instance Directory: Enter the full path to the directory where the Sun ONE Web Proxy Server instance is located. For example:

    proxy_server_root_dir/proxy-mycomputer-proxy

    Proxy Server Port: Enter the port number for the Proxy server instance.

    Proxy Server Protocol: If the proxy server has been configured for SSL, choose HTTPS; otherwise choose HTTP.

    Agent Deployment URI: Enter a directory name. The default URI is /amagent.

  7. When all the information is entered correctly, click Next.
  8. When prompted, 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.

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

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

  9. When all the information is entered correctly, 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 Exit to end the Installation program.
  13. Restart the Proxy Server.

Installing From the Command Line

The following sections describe how to use the CLI of the installation program to install the web policy agents.

Installing the Policy Agent for a Web Server

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

    2. # setup -nodisplay

  2. Set your JAVAHOME environment variable to a JDK version 1.3.1_04 or higher. The installation requires that you set up your JAVAHOME variable correctly. However, in case you have incorrectly set the JAVAHOME variable, the setup script will prompt you for supplying the correct JAVAHOME value:

    3. Please enter JAVAHOME path to pick up java:

  3. Type the full path to the directory where JDK is located and press Enter.
  4. When prompted, provide the following information:

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

    Install Sun ONE Identity Server Agent in this directory: Enter the full path to the directory in which you want to install the policy agent.

  5. Provide the following information about the web server this agent will protect:
    • Host Name
    • Port
    • Web Server Instance Directory (if you are installing the policy agent for Lotus Domino, IBM HTTP server, or Apache Server, the installation program will prompt for the Lotus Domino Data Directory, the Configuration Directory or the Apache Binary Directory as appropriate.)
    • Web Server Protocol
    • Agent Deployment URI
    • SSL Ready (only for Apache agent)

      • For more information on each of these items, see "Installing the Policy Agent for a Web Server."

  6. Provide the following information about the web server that runs Sun ONE Identity Server:
    • 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 Enabled

      • For more information on each of these items, see "Installing the Policy Agent for a Web Server."

      The following text is displayed:

      Ready to Install

      1. Install Now

      2. Start Over

      3. Exit Installation

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

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

Installing the Policy Agent for a Web Proxy Server

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

    2. # setup -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? Enter yes.

    Install Sun ONE Identity Server Agent in this directory: Enter the full path to the directory in which you want to install the policy agent.

  3. Provide the following information about the Web Server this agent will protect:
  4. Provide the following information about the proxy web server that runs Sun ONE Identity Server:
    • 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 Enabled

      • For more information on each of these items, see "Installing the Policy Agent for a Web Proxy Server."

      The following text is displayed:

      Ready to Install

      1. Install Now

      2. Start Over

      3. Exit Installation

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

    6. The following text is displayed:

    Product                            Result     More Information

    1.  Sun ONE Identity Server Agent  Installed  Available

    2.  Done

  6. To see log information, enter 1. To exit the installation program, enter 2.
  7. Restart the Proxy Server.

Post-installation Tasks

The following sections present tasks you need to perform after the installation of some of the agents.

Configuring the Domino DSAPI Filter

Use the following procedure to configure DSAPI filter if you are installing the policy agent for IBM Lotus Domino:

  1. In Lotus Domino Administrator, choose Administrator Tab > Server > All Server Documents.
  2. From the listed servers, select the required server.
  3. Click Internet Protocols > HTTP tab.
  4. At the DSAPI Filter File Names field, enter the file names as follows:
    • For IBM Lotus Domino 5.0.11, enter Agent_Install_Dir/SUNWam/Agents/Domino/lib/libamdomino.so
    • For IBM Lotus Domino 6.5, enter Agent_Install_Dir/SUNWam/agents/domino6/lib/libamdomino6.so
  5. Click the Save and Close button to save the changes.
  6. Open Domino console and restart the server by entering the following commands:

    7. tell http quit

    load http

Setting File Ownership and Permissions

For the agents for IBM Lotus Domino to work properly, make sure that the user that Domino server is running as has ‘read’ permission to the following files:

To set the required permission, you can use the commands as shown in the following examples:

chown notes:notes Agent_Install_Dir/SUNWam/agents/domino6/lib/libamdomino6.so

chmown notes:notes /Agent_Install_Dir/SUNWam/domino6/config/_opt_lotus_notes_notesdata/AMAgent.prop erties

chown notes:notes (+w) /var/tmp/debug/_opt_lotus_notes_notesdata/amAgent

In the above examples, notes is the default user created during IBM Lotus Domino installation.

Additionally, if Sun ONE Identity Server is running with SSL, the files cert7.db and key3.db must also allow ‘read’ access to the user the Domino Server is running as. These files are available in the directory specified by the property com.sun.am.sslCertDir in the AMAgent.properties file.

For example, if the property is set as com.sun.am.sslCertDir = /opt/my-agents-dir, ensure that /opt/my-agents-dir/{cert7.db,key3.db} has the necessary permissions by using the following command:

chown notes:notes /opt/my-agents-dir/cert7.db /opt/my-agents-dir/key3.db

Configuring the Agent for Multiple Web Server Instances

To configure an agent for multiple web server instances on a single computer, use the GUI or command-line version of the agent installation program to install the first agent. After the first agent is installed, you can then configure the agent for multiple web server instances using the config script. This script must be run from the command line as described in the next section.

In this release, you cannot install more than one type of agents on the same machine. For example, you cannot install an Apache agent and a Sun ONE Web Server agent on the same machine.

Configuring the Agent for Multiple Web Server Instances on the Same Computer

Once you have installed an agent on a system, you can configure it for multiple instances of the web server on that system using the config script that is copied into the system during the agent installation. The two scripts, config and unconfig, are located in the following directory:

Agent_Install_Dir/SUNWam/agents/WS_TYPE/bin

WS_TYPE can be es6, proxy, apache or domino depending on which web server the agent is protecting.

Note

On HP-UX 11.11, you must use the scripts config_es6 and unconfig_es6 to configure and unconfigure the agent for multiple web server instances. These scripts are available in the following directory:

Agent_Install_Dir/agents/WS_TYPE/bin

  1. To configure the agent for additional web server instances on a system, run the config script from the bin directory using the following command:

    2. # ./config

  2. Follow the prompts to configure additional web server instances. For information on each of the prompts, see "Installing the Policy Agent for a Web Server." In general, information needs to be entered for both the protected web server instance and the Sun ONE Identity Server server(s). The following text shows an example.

    3. If you are installing the agent for Lotus Domino, the following example will show the Lotus Domino Data Directory in the place of the Web Server Instance Directory.

    # ./config

    Enter the Web Server Instance Directory: [/web_server_root/https-server_instance]

    Enter the Local Hostname: [mycomputer.eng.example.com]

    Enter the Agent Web Server Port: [80]

    Select Agent Web Server Protocol: [1] http [2] https-->[1]

    Enter the Agent Deployment URI: [/amagent]

    Select Identity Server Protocol: [1] http [2] https --> [1]

    Enter the Identity Server Hostname: [mycomputer.eng.example.com]

    Enter the Identity Server Port: [58080]

    Enter the Identity Server Deployment URI [/amserver]

    Enter the Identity Server's Console Deployment URI [/amconsole]

    Select Failover Identity Server Protocol: [1] http [2] https [3] no failover --> []

    Enter the Failover Identity Server Hostname: []mycomputer.example.com

    Enter the Failover Identity Server Port: []

    Enter the Identity Server Deployment URI [/amserver]

    Enter the Identity Server's Console Deployment URI [/amconsole]

    Enter Agent-Identity Server shared secret:

    Re-enter Agent-Identity Server shared secret:

    Is CDSSO Enabled: [1] yes [2] no --> [2] 1

    Configuring webserver ... Webserver version: 6.0

    Done

    Note

    Be sure to use the unconfig script to uninstall any agent that was installed using the config script—you cannot use the GUI installation program to uninstall agents that were installed from the command line. The GUI uninstallation program must be executed only after unconfiguring all the existing agents using the command-line unconfig script.

Deploying the Agent with Multiple Instances of Sun ONE Identity Server

When you have to install multiple instances of Sun ONE Identity Server along with the policy agents, it is recommended that you deploy all the instances of Sun ONE Identity Server first and then install the agents as necessary. If you add another instance of Identity Server after the agents have been installed, you must edit the magnus.conf file of the new instance of Identity Server to remove the entries corresponding to the installed agents. Then you can install an agent to protect this instance, if necessary.

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.

You should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation that comes with your web server. If you’re using Sun ONE Web Server, you can access the documentation at:

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

Configuring the IBM HTTP Server

Use the following instructions to configure the IBM HTTP Server to run in SSL mode.

  1. Create a new key database using the key management utility (IKEYMAN). For information on creating new key database, see the documentation at: http://www-3.ibm.com/software/webservers/httpservers/doc/v1319/9atikeyu.htm#HDRKMU2G
  2. Create a self-signed certificate using IKEYMAN. For information on creating a self-signed certificate, see the documentation at: http://www-3.ibm.com/software/webservers/httpservers/doc/v1319/9atikeyu.htm#HDRKMU4G
  3. Start the Administration Server

    4. # /opt/IBMHTTPD/bin/adminctl start

  4. Setup SSL using the IBM Administration Server. For information on setting up SSL, see the documentation at:

    5. http://www-3.ibm.com/software/webservers/httpservers/doc/v1319/9atstart.htm#ssl

Web or Web Proxy Server Running in SSL Mode

If your web or web proxy server is running in the SSL mode, and your agent is in the notification mode, you must install the root CA certificate of your web or web proxy server onto Identity Server if it is not already installed.

The Agent’s Default Trust Behavior

By default, the policy agent installed on a remote web server or proxy 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 Identity Server is SSL-enabled, and you want the policy agent to perform certificate-checking, you must do the following:

  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 be the same as the one installed on the web server that runs Sun ONE Identity Server service.

Disabling the Agent’s Default Trust Behavior

The following property in the AMAgent.properties file controls the agent’s trust behavior, 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

  1. Set the following property to false:

    2. com.sun.am.trustServerCerts=false

  2. Set the directory Cert DB in the file AMAgent.properties as shown in the following example:

    3. com.sun.am.policy.am.sslCertDir= /opt/SUNWam/servers/alias

    For Apache agent, set as following:

    com.sun.am.policy.am.sslCertDir= /etc/apache/cert

    For IBM HTTP Server, set as following:

    com.sun.am.policy.am.sslCertDir=/opt/IBMHTTPD/cert

    For Domino Web Server, set as following:

    com.sun.am.policy.am.sslCertDir=/opt/domino/cert

  3. Set the Cert DB Prefix, if required.

    4. In cases where the specified Cert DB directory has multiple certificate databases, the following property must be set to the prefix of the certificate database to be used.

    com.sun.am.policy.am.certDbPrefix

    For example, set the property for Sun ONE Web Server as this:

    com.sun.am.policy.am.certDbPrefix =https-host.domain.com.host-

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 Sun ONE Web Server

See the instructions for installing a root CA certificate in the documentation that comes with the web server. Generally, you install a root CA certificate through the web server’s Administration console.

You can 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

To Install the Root CA Certificate on Apache 1.3.27

You can use the certutil program to install the root CA certificate on Apache 1.3.27.

  1. In C shell, at the command line, enter the following commands (assuming /etc/apache is the directory where the apache configuration file is located):

    2. # cd /etc/apache/cert

    # setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/agents/apache/lib:/Agent_Install_Dir/SUNWam/agents/lib:/usr/lib/mps

  2. Create the necessary certificate database if you have not already done so.

    3. # /Agent_Install_Dir/SUNWam/agents/apache/cert/certutil -N -d .

  3. Install root CA certificate.

    4. # /Agent_Install_Dir/SUNWam/agents/apache/cert/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

    In the commands above, the variables represent the following:

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

      • For more information on the certutil utility, enter certutil -H for online Help.

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

    5. # ./certutil -L -d .

    Trust database information will be displayed including the name of the root CA certificate you installed. For example:

    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

To Install the Root CA Certificate on Web Proxy Server

You can use the certutil program to install the root CA Certificate on Proxy Server.

  1. In C shell, at the command line, enter the following commands:

    2. # mkdir Proxy_Server_Instance_Dir/cert

    # cd Proxy_Server_Instance_Dir/cert

    # setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/agents/proxy/lib:/Agent_Install_Dir/SUNWam/agents/lib:/usr/lib/mps

  2. Create the necessary certificate database if you have not already done so.
  3. Install root CA certificate.

    4. # /Agent_Install_Dir/SUNWam/agents/proxy/cert/certutil -N -d .

    # /Agent_Install_Dir/SUNWam/agents/proxy/cert/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

    In the commands above, the variables represent the following:

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

To Install the Root CA Certificate on IBM HTTP Server 1.3.19

You can use the certutil program to install the root CA certificate on IBM HTTP Server 1.3.19.

  1. In C shell, at the command line, enter the following commands:

    2. # mkdir server_instance_dir/cert

    # setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/agents/
    ibmhttp/lib:    /Agent_Install_Dir/SUNWam/agents/lib

  2. Create the necessary certificate database if you have not already done so.

    3. # /Agent_Install_Dir/SUNWam/agents/ibmhttp/cert/certutil -N -d .

    Note

    This will create the following three files in the directory server_instance_dir/cert:

    • secmod.db
    • key3.db
    • cert7.db

    Make sure that the UNIX user that the IBM HTTP server runs as (for example nobody), has read permissions on these three files.

  3. Install root CA certificate.

    4. # /Agent_Install_Dir/SUNWam/agents/ibmhttp/cert/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

    In the command above, the variables represent the following:

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

      • For more information on the certutil utility, enter certutil -H for online Help.

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

    5. # ./certutil -L -d .

    Trust database information will be displayed including the name of the root CA certificate you installed. See the following example.

    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

To Install the CA Certificate on Domino Web Server

See the instructions for installing a CA Certificate in the documentation that comes with the web server. Generally, this is done through the web server's Administration console.

  1. Go to the following directory:

    2. Agent_Install_Dir/Agents/domino/utils

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

  3. In the command above, the variables represent the following:
    • 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 certutil, type certutil -H

  4. Restart Domino Web Server.

Setting the REMOTE_USER Server Variable

The REMOTE_USER server environment variable can be set to a 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 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

Note

This feature is not available for the Sun ONE Web Proxy Server agent.

Validating Client IP Addresses

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

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 incoming 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. Users can preserve POST data, which are submitted to web servers through HTML forms before users login to Sun ONE Identity Server. Presumably, the HTML page containing the form should be in the not-enforced list. By default, this feature is set 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

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

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.

Note

This feature is available only on the agent for Sun ONE Web Server 6.0 SPx.

Shared Secret Encryption Utility

The 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 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 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. # ./crypt_util 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.

Uninstalling a Policy Agent

The following sections provide steps for uninstalling the agent. Note the following:

Unconfiguring a Policy Agent

To remove an agent that was configured using the config script, use the script unconfig. The unconfig script is located in the following directory:

Agent_Install_Dir/SUNWam/agents/es6/bin

WS_TYPE can be es6, proxy, apache or domino depending on which web server the agent is protecting.

On HP-UX 11.11, you must use the script unconfig_es6 instead of the unconfig script. You can find the script in the following directory:

Agent_Install_Dir/agents/es6/bin

Here is an example run of the unconfig script.

# ./unconfig /web_server_root/https-server_instance

Unconfiguring webserver ...

done.

Note

If you are removing the agent for Lotus Domino 5.0.10, you should specify the path to the Domino data directory instead of https-server_instance. Additionally, you should remove the DSAPI filter file for the required Domino server using the Domino Administrative Client and then restart the Domino Web Server.

Before Uninstalling the Policy Agent for Lotus Domino

Before you uninstall the policy agent for Lotus Domino 5.0.11 or 6.0.1, you should perform the following steps on the Lotus Domino Administrator client from a Windows machine.

  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 Lotus Domino agent.
  6. Click the Save and Close button to save the changes.
  7. Open the Domino console and restart the server by entering the following commands:

    8. tell http quit

    load http

Uninstalling Using the GUI

To uninstall an agent, you must run the uninstallation program. Follow the steps below:

  1. In the directory where the agent is installed, at the command line, enter the following command:

    2. # ./uninstall_agent

    On HP-UX 11.11, use the following command:

    java uninstall_Sun_ONE_Identity_Server_Policy_Agent

  2. Click Next on Welcome panel.
  3. Click Uninstall Now on Ready to Uninstall panel.
  4. Click Close after uninstallation is complete.
  5. Restart the web server.

Uninstalling From the Command-Line

  1. From the directory where the agent is installed, enter the following command at the command line:

    2. # ./uninstall_agent -nodisplay

    The uninstallation program detects the agent that was previously installed using the setup program. Enter 1 to uninstall the agent.

    The following text is displayed:

    Ready to Uninstall

    1. Uninstall Now

    2. Start Over

    3. Exit Uninstallation

  2. When prompted, What next? enter 1 to begin uninstallation.

    3. The following text is displayed:

    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. Restart the web server.

Troubleshooting

Cannot install the agent after a previous installation is removed

The following is an example message that is 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:

The uninstallation program does not remove entries from the agent’s web server if there is another instance of web server configured using the Configuration script.

Solution:

You should remove all the instances of the agent using the unconfig script before running the uninstallation program.

On Solaris 8, the agent’s performance may suffer when multiple threads are running.

Solution:

On Solaris 8:

  1. Apply the latest Solaris 8 cluster patch (Patch Cluster Date Jan/24/03 or later).
  2. Download and install patch 111308-03 or later (showrev -p | grep 111308) from http://sunsolve.central.sun.com.
  3. Reboot the machine after applying the patches (this is recommended but not mandatory).

For agents running on Sun ONE Web Server 6.0:

  1. In your web server instance directory, open the start script.
  2. Before the first LD_LIBRARY_PATH line, add the following two lines

    3. LD_PRELOAD=libmtmalloc.so.1

    export LD_PRELOAD

  3. To make sure the patches are installed correctly, try this. It should produce a line of output.

    4. showrev -p | grep 111308

  4. To verify that libmtmalloc is being used by the web server, do the following.

    5. ps -ef |grep httpd | grep nobody

  5. Take the pid from the previous step and do

    6. pldd pid of the process | grep mtmalloc

    The output should show /usr/lib/libmtmalloc.so.1.

The browser goes into a loop for a minute or so before displaying an access-denied page when a user tries to access a resource for which a policy with a time condition has been set and the time on the agent host and the Identity Server host are not in sync.

Solution:

Login as root and run the command rdate hostname to synchronize the time on both the hosts.

Known Problems

After installing the Solaris 2.8 Patch # 109234-09, Apache Server does not startup correctly or hangs

This can happen if your system does not have JServ installed at the time of installing the patch. In order to correct this problem, edit your httpd.conf file located under /etc/apache/ directory and comment the following line:

LoadModule jserv_module /usr/apache/libexec/mod_jserv.so and include /etc/apache/jserv.conf

Error message displayed during startup

Apache server displays the following error message during startup after the agent is installed:

Syntax error on line 1 of

/etc/opt/SUNWam/agents/apache/config/_usr_local_apache_conf/dsame.conf:

Invalid command 'LoadModule', perhaps mis-spelled or defined by a module not included in the server configuration

./apachectl start: httpd could not be started

This indicates that the Apache server does not have mod_so enabled and consequently does not support dynamic shared objects. To enable mod_so support, refer Apache Server documentation at http://httpd.apache.org/.

Policies not working with Sun ONE Web Proxy Server agent.

The resource names for setting policies for the reverse proxy agent should be the URLs qualified as “URL prefix (from client)” in the Sun ONE Web Proxy Server 3.6 administrative console.

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

Modifications to the configuration of the web server’s configuration files (obj.conf, magnus.conf) may be overwritten by the server, which would disable the agent completely. To ensure this does not occur, after installing the agent, go to the Web Server’s administration console, and press the Apply Button. You could either load the configuration or click on Apply Changes that would restart the server. If you do get into this problem, go to the bin directory where unconfig script is located. Unconfigure the agent and reconfigure it for this instance of the web server. After doing this, go to the Administration console of the web server and click the Apply button to save the configuration changes made by the agent.



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.