Sun logo      Previous      Contents      Index      Next     

Web Policy Agents Guide

Chapter 4
Policy Agents on Red Hat, SuSE, and Debian Linux

This chapter explains how to install and configure Web Policy Agents available for the web servers running on Red Hat Linux 7.2, Red Hat Linux 9.0 and Red Hat Advanced Server 2.1.

Topics include:

Before You Begin

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

Pre-installation Tasks

Before you install the supported agents on the Linux platforms, you must perform the following pre-installation tasks.

Policy Agent for Apache 1.3.27

If you are installing the agent for Apache 1.3.27 on Linux, you must complete the following tasks in the order they are listed below, to make sure Apache Web Server is configured with POSIX Threads library. Failing to perform these tasks may result in the application becoming unusable or may result in the entire system becoming unstable and unusable.

  1. Get the Apache source from http://httpd.apache.org/
  2. Before you run configure, set an environment variable LIBS=-lpthread as shown in the table.

    Table 4-1  Setting the Environment Variable

    Shell

    Environment Variable

    sh

    LIBS=-lpthread;export

    bash

    export LIBS=-lpthread

    tcsh

    setenv LIBS '-lpthread'

  3. Configure your Apache Web Server with the following flags:

    4. configure --enable-rule=SHARED_CORE --enable-shared=max

  4. Rebuild and install Apache Web Server.
  5. Install the Apache agent.

Policy Agent for Apache 2.0.48

If you are installing the policy agent for Apache 2.0.48 on Red Hat Advanced Server 2.1, make sure that the following, or a later version, of Red Hat’s Program Managers (RPM) are installed on the system for the agent to run correctly:

The RPMs are available at the following locations:

Policy Agents for IBM Lotus Domino 6.0.2 and 6.5

If you are installing the agents for IBM Lotus Domino 6.5 or 6.0.2 on RedHat Advanced Server 2.1, make sure that C++ libraries from GCC 3.3.2 are installed on the system.

This is due to a bug with exception handling in Domino Server on Red Hat Advanced Server 2.1.

The GCC 3.3.2 libraries needed by the agents libraries are:

These can be built and installed from GCC 3.3.2 sources available at:

http://gcc.gnu.org/releases.html

Policy Agents for Apache 1.3.29 and 2.0.52 on SuSE Linux

The pre-installation information in this section applies specifically to enabling SSL on Apache 1.3.29 and 2.0.52 on SuSE Linux. You first need to download and uncompress the source file.

Obtaining the Apache Server Source File

If you want to compile Apache source by enabling SSL, execute the following command.

./configure --prefix=/opt/apache_install --enable-ssl

make

make install

Where apache_install refers to the directory where the Apache server binary is located.

Stopping and Starting the Apache Server

The command for starting the Apache server is different when SSL is enabled. However, the command for stopping the Apache server is the same if SSL is enabled or not.

To start the Apache server when SSL is enabled, use the following command.

/opt/apache_install/bin/apachetl -D SSL -k start

To start the Apache server when SSL is not enabled, use the following command.

/opt/apache_install/bin/apachetl -k start

To stop the Apache server, whether SSL is enabled or not, use the following command.

/opt/apache_install/bin/apachetl -k stop

Policy Agent for Apache 2.0.52 on Debian Linux

The pre-installation information in this section applies specifically to enabling SSL on Apache 2.0.52 on Debian Linux.

Obtaining OpenSSL

If you want to compile Apache 2.0.52 source for Debian Linux by enabling SSL, you must have OpenSSL on your system. If you do not have SSL on your system, download it from http://www.openssl.org/source/openssl-0.9.7e.tar.gz,open the compressed file, and perform the following steps:

  1. In the directory where you downloaded OpenSSL, execute the following command:

    2. ./config --prefix=/usr/local/openssl

    make clean

    make install

  2. Ensure that openSSL is installed at /usr/local/openssl.
  3. Add /usr/local/openssl into your PATH variable.

Enabling SSL

To compile Apache source by enabling SSL, follow these steps:

  1. Change to the following directory:

    2. /opt/apache_src/httpd-2.0.52

  2. Execute the following command:

    3. ./configure --prefix=/opt/apache_install --enable-ssl

    make

    make install

    Where apache_install refers to the directory where the Apache server binary is located.

  3. Change to the following directory:

    4. /opt/apache_install/conf

  4. Open the httpd.conf file.
  5. Change the name of the group associated with the httpd.conf file from #-1 to nobody.

Stopping and Starting the Apache Server

The command for starting the Apache server is different when SSL is enabled. However, the command for stopping the Apache server is the same if SSL is enabled or not.

To start the Apache server when SSL is enabled, use the following command.

/opt/apache_install/bin/apachetl -D SSL -k start

To start the Apache server when SSL is not enabled, use the following command.

/opt/apache_install/bin/apachetl -k start

To stop the Apache server, whether SSL is enabled or not, use the following command.

/opt/apache_install/bin/apachetl -k stop

Installing the Agent

The following sections provide step-by-step instructions to help you use the agent installation program in the GUI and the command-line modes.

Installing using the GUI

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

  1. Unpack the product binaries 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. 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 server this agent will protect:

    7. Install Sun ONE Identity Server Policy Agent in this directory: Enter the full path to the directory where you want this agent to be installed, and then click Next.

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

    Apache Configuration Directory: Specify the Apache server configuration directory where the httpd.conf file is located.

    Apache Binary Directory: Enter the full path to the directory where the httpd binary is located, for example usr/local/apache2/bin. This field is available only if you are installing the policy agent for Apache 2.0.47 and 2.0.48.

    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 directory name. The default Universal Resource Identifier (URI) is /amagent.

    SSL Ready: You should select this option if the Apache web server you are using has support for SSL. If you are using Apache Web Server 1.3.27, 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:

    1. Apache Web Server without mod_ssl support
    2. Apache Web Server with mod_ssl and EAPI flag enabled.

      3. Note

      Apache Web Server with mod_ssl support and EAPI flag disabled configuration is not supported by Web Policy Agents.

  7. When all the information is entered correctly, click Next.
  8. Enter information about the web server that runs Sun ONE Identity Server policy and management. The policy agent will connect to this 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 feature.

  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 Close to close the installation program.
  13. Restart your Apache web server for the installation to be complete.

Installing from the Command-Line

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

  1. Unzip the Solaris tar file 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 -nodisplay

  3. When prompted, provide the following information:

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

  4. Provide the following information about the Web Server this agent will protect:
    • Web Server Host Name
    • Apache Configuration Directory (Apache Binary Directory if you are installing the agent for Apache 2.0.47 or 2.0.48)
    • Web Server Port
    • Web Server Protocol
    • Agent Deployment URI
    • SSL Ready

      • For more information on each of these items, see "Installing using the GUI."

  5. 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 Protocol
    • 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 using the GUI."

      The following text is displayed:

      Ready to Install

      1. Install Now

      2. Start Over

      3. Exit Installation

  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.

Post-installation Tasks

After you have installed the policy agent, you must perform a set of post-installation tasks as explained in the following sections.

Agent for IBM Lotus Domino 6.5

For the agent for IBM Lotus Domino 6.5 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 Domino DSAPI Filter

Configure the DSAPI filter as explained here if you are installing the policy agent for IBM Lotus Domino 6.5.1:

  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 Agent_Install_Dir/agents/domino/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

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 the command-line version of the agent installation program to install the first agent. After the first agent is installed, you can then install successive agents using the config script. This script must be run from the command line as described in the following section.

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

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

Agent_Install_Dir/agents/apache/bin

To configure additional agents on a system after the original agent has been installed, run the config_linux script from the bin directory using the following command:

# ./config_linux

Follow the prompts to install the additional agents. For information on each of the prompts, see "Installing using the GUI." In general, information needs to be entered for both the protected Apache server instance and the Sun ONE Identity Server server(s). The following text shows an example run:

# ./config_linux

Enter the Apache Server Configuration Directory: [/etc/httpd/conf]

SSL Ready: [true] false

Enter the Local Hostname: [mycomputer.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.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]

Configuring Apache Web Server ...

Done

Note

Be sure to use the unconfig_linux script to uninstall any agent that was installed using the config_linux 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 installed using command-line unconfig script.

Using Secure Sockets Layer (SSL) with an Agent

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

Note

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

The Agent’s Default Trust Behavior

By default, the policy agent installed on a remote Apache 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 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 the be same one that is 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. 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 Root CA Certificate on the Remote Web Server

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

To Install the Root CA Certificate

You can use the certutil program to install the root CA Certificate on Apache web server.

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

    2. # cd /etc/apache/cert

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

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

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

  3. Install root CA certificate.

    4. # /Agent_Install_Dir/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 include the name of the root CA certificate you installed. 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

Setting the REMOTE_USER Server Variable

The REMOTE_USER server environment variable can be set to a Sun ONE Identity Server authenticated user or an 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 non-authenticated users), you must set the following property in the AMAgent.properties file to TRUE (by default, the value of this property is set to FALSE):

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

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

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

Validating Client IP Addresses

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

The AMAgent.properties file contains a property named com.sun.am.policy.agents.client_ip_validation_enable, which by default is set to false.

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

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

Shared Secret Encryption Utility

The 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 AMConfig.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. If the agent gets redirected to the Sun ONE Identity Server, this indicates the above steps were executed properly.

Uninstalling the Policy Agent

The following sections explain the procedure to uninstall a policy agent.

Removing an Agent using the unconfig Script

To remove an agent that was installed from the command line using the config_linux script, use the script unconfig_linux. The unconfig_linux script is located in the following directory:

Agent_Install_Dir/agents/apache/bin

Here is an example run of the unconfig_linux script.

# ./unconfig_linux /web_server_root/httpd/conf

Unconfiguring webserver ...

done.

Uninstalling using the GUI

Use the following steps to uninstall the policy agent using the GUI of the installation program:

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

    2. # ./uninstall_linux_apache_agent

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

Uninstalling from the Command Line

Use the following steps to uninstall the policy agent from the command line:

  1. In the Agent_Install_Dir directory, at the command line, enter the following command at the command line:

    2. # ./uninstall_linux_apache_agent -nodisplay

    The following text is displayed:

    The uninstaller has detected the following agents on this system:

    1. Agent 2.1 for Apache [/usr/local]

    2. Exit

    Please select an installed agent from the following list:

  2. Enter 1, to remove the product.

    3. The following text is displayed:

    Ready to Uninstall

    1. Uninstall Now

    2. Start Over

    3. Exit Uninstallation

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

    4. The following text is displayed:

    Product                                  Result   More Information

    1. Sun ONE Identity Server Policy Agent  Full     Available

    2. Done

  4. To see log information on the agent, enter 1. To exit the uninstallation program, enter 2.
  5. Restart the web server.

Troubleshooting

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

Solution: 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 to Apache server documentation at http://httpd.apache.org/



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.