Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Apache HTTP Server 2.0.x

Post-Installation Tasks for the Apache HTTP Server 2.0.x Agent

Using SSL With the Apache HTTP Server 2.0.x Agent (Optional)

If you specify the HTTPS protocol during the Apache HTTP Server 2.0.x agent installation, the agent is automatically configured and ready to communicate over Secure Sockets Layer (SSL). Before continuing with the tasks in this section, however, ensure that the Apache HTTP Server instance is configured for SSL. For information, see the Apache HTTP Server 2.0 documentation:http://httpd.apache.org/docs/2.0/.

Disabling the Trust Behavior of the Apache HTTP Server Agent

By default, the Apache HTTP Server 2.0.x agent installed on a remote Apache HTTP Server instance trusts any server certificate presented over SSL by the OpenSSO Enterprise host server. For the Apache HTTP Server 2.0.x agent to perform certificate checking, you must disable this behavior.

To Disable the Trust Behavior of the Apache HTTP Server Agent

Find the Apache HTTP Server 2.0.x agent's OpenSSOAgentBootstrap.properties file in the agent's /config directory. For example:

/opt/web_agents/apache_agent/Agent_001/config/OpenSSOAgentBootstrap.properties

In the OpenSSOAgentBootstrap.properties file, set the SSL-related properties, depending on your specific deployment.

Note: These properties have new names for version 3.0 web agents.
- Disable the option to trust the server certificate sent over SSL by the OpenSSO Enterprise host server:
  
  com.sun.identity.agents.config.trust.server.certs = false
- Specify the certificate database directory. For example:
  
  com.sun.identity.agents.config.sslcert.dir = /opt/apache-2.0.63/conf/certdb
- If the certificate database directory has multiple certificate databases, set the following property to the prefix of the database you want to use. For example:
  
  com.sun.identity.agents.config.certdb.prefix = prefix-
- Specify the certificate database password:
  
  com.sun.identity.agents.config.certdb.password = password
- Specify the certificate database alias:
  
  com.sun.identity.agents.config.certificate.alias = alias-name

Save the changes to the OpenSSOAgentBootstrap.properties file.

The agent uses information in the OpenSSOAgentBootstrap.properties file to start and initialize itself and to communicate with OpenSSO Enterprise server.

Installing the OpenSSO Enterprise Root CA Certificate on the Apache HTTP Server Instance

The root CA certificate that you install on the Apache HTTP Server instance must be the same certificate that is installed on the OpenSSO Enterprise host server.

Sun provides the Certificate Database Tool, certutil, in the Apache HTTP Server agent distribution file, to manage the root CA certificate and the certificate database.

For information about using certutil, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.

To Install the OpenSSO Enterprise Root CA Certificate on the Apache HTTP Server Instance

Obtain the root CA certificate file that is installed on the OpenSSO Enterprise host server.

On the Apache HTTP Server instance, locate the certutil utility.

After you unzip the Apache HTTP Server agent distribution file, certutil is available in the PolicyAgent-base/bin directory.

For example: /opt/web_agents/apache_agent/bin/certutil

Before you use certutil, set the LD_LIBRARY_PATH environment variable to the location of the certutil library files.

After you unzip the Apache HTTP Server agent distribution file, these library files are available in the PolicyAgent-base/lib directory.

For example: /opt/web_agents/apache_agent/lib

If necessary, create the certificate database using certutil. For example:

# cd /opt/web_agents/apache_agent/bin
# mkdir /opt/apache-2.0.63/conf/certdb
# ./certutil -N -d /opt/apache-2.0.63/conf/certdb

Install the OpenSSO Enterprise root CA certificate using certutil. For example:
```
# ./certutil -A -n cert-name -t "C,C,C" -d /opt/apache-2.0.63/conf/certdb -i cert-request-file
```
where:
- cert-name is the name of the OpenSSO Enterprise root CA certificate.
- cert-request-file is the binary root CA certificate request file.

To verify that the root CA certificate is installed correctly, use certutil with the -L option. For example:
```
# ./certutil -L -d /opt/apache-2.0.63/conf/certdb
```
You should see the name of the root CA certificate.

Restart the Apache HTTP Server instance.

Changing the Password for an Agent Profile (Optional)

This task is optional. After you install the agent, you can change the agent profile password, if required for your deployment.

To Change the Password for an Agent Profile

On the OpenSSO Enterprise server:
1. Login into the Administration Console.
2. Click Access Control, realm-name, Agents, Web, and then the name of the agent you want to configure.
  
  The Console displays the Edit page for the agent profile.
3. Enter and confirm the new unencrypted password.
4. Click Save.

On the server where the Apache HTTP Server 2.0.x agent is installed:
1. In the agent profile password file, replace the old password with the new unencrypted password.
2. Change to the PolicyAgent-base/bin directory. For example:
  
  # cd /opt/web_agents/apache_agent/bin
3. Encrypt the new password using the agentadmin program. For example:
  
  #./agentadmin --encrypt Agent_001 /tmp/apache2agentpw
  
  Agent_001 is the agent instance whose password you want to encrypt.
  
  passwd is the password file in the /tmp directory.
  
  The agentadmin program returns the new encrypted password. For example:
  
  The encrypted value is: /54GwN432q+MEnfh/AHLMA==
4. In the agent-instance/config/OpenSSOAgentBootstrap.properties file, set the following property to the new encrypted password from the previous step. For example:
  
  com.sun.identity.agents.config.password=/54GwN432q+MEnfh/AHLMA==
5. Restart the Apache HTTP Server instance that is being protected by the policy agent.

Configuring the Apache HTTP Server 2.0.x Agent on IBM AIX Systems

Perform this task only if you are installing the Apache HTTP Server 2.0.x agent on an IBM AIX system.

To Configure the Apache HTTP Server 2.0.x Agent on IBM AIX Systems

Set the LIBPATH variable to the agent's lib directory. For example:
```
setenv LIBPATH /opt/web_agents/apache_agent/lib:/usr/lib:/lib
```

As required, modify the libxml2.so.2 library file to libxml2.so in the agent's lib directory, which is in the following directory:

AgentHome/web_agents/apache_agent/lib, where AgentHome is where you unzipped the agent distribution file.

Setting the `SHLIB_PATH` Environment Variable on HP-UX Systems

To Set the `SHLIB_PATH` Environment Variable on HP-UX Systems

Before you start the Apache HTTP Server 2.0.x server, set the SHLIB_PATH environment variable to the agent's lib directory. For example:
```
setenv SHLIB_PATH /opt/web_agents/apache_agent/lib:/usr/lib:/lib
```