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



Chapter 2   Policy Agents for Solaris 8 and 9

Sun ONE Identity Server Policy Agents work in tandem with Sun ONE Identity Server to grant or deny user access to web servers in an enterprise. This chapter explains how to install and configure the policy agents for servers running on the Solaris 8 and Solaris 9 operating systems.

Topics 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:

Supported Solaris Web Servers

Sun ONE Identity Server Policy Agents support the following servers running on the Solaris 8 operating system:

  • Sun ONE Web Server 6.0 SPx

  • Sun ONE Web Server 4.1 SP8

  • Sun ONE Web Proxy Server 3.6 (in reverse proxy mode)

  • Apache 1.3.26

  • IBM HTTP Server 1.3.19

  • Lotus Domino 5.0.10

Sun ONE Identity Server Policy Agents support the following servers running on the Solaris 9 operating system:

  • Sun ONE Web Server 6.0 SPx

  • Apache 1.3.26

Patch Cluster for Solaris

When running Apache 1.3.26 Web Server on platforms Solaris 8 and 9, you must ensure that the recommended patches 109234-09 and 113146-01are installed. You can download these patches from http://sunsolve.sun.com

Installation Using the GUI

Use the following instructions for installing agents on the following servers on the Solaris 8 operating system.

To Install a Web Server Policy Agent

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

  1. Unpack the product binaries using the following commands.

    2. For Sun ONE Web Server 4.1:

    # gunzip -dc agent_SunOS_es41.tar.gz| tar -xvof -

    For Sun ONE Web Server 6.0 SPx:

    # gunzip -dc agent_SunOS_es6.tar.gz| tar -xvof -

    For Apache 1.3.26 Web Server:

    # gunzip -dc agent_SunOS_apache.tar.gz| tar -xvof -

    For IBM HTTP Server 1.3.19:

    # gunzip -dc agent_SunOS_ibmhttp.tar.gz | tar -xvof -

    For Lotus Domino 5.0.10

    gunzip -dc agent_SunOS_domino.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 JAVA_HOME environment variable to a JDK version 1.3.1_04 or higher. The installation requires that you setup your JAVA_HOME variable correctly. However, in case you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for supplying the correct JAVA_HOME 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 the agent to be installed. 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.siroe.com

    Web Server Instance Directory: This prompt appears only if you have selected a Sun ONE Web Server agent. 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.siroe.com

    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.

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

    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.


    Note

    The Agent uses value of com.sun.am.policy.agents.agenturiprefix property to support some essential functions such as notification and post data preservation. It is important to set a valid URL for this property. Its 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 which the web server will look for agent's related HTML pages. Its default value is amagent.

    SSL Ready: This option is displayed 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:

    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 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 policy and management. 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.siroe.com.

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

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

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

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

    Failover Server Host: Enter the 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.

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

    CDSSO Component URL: Enter the CDSSO Component URL.

  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. 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. You must restart your Sun ONE Web Server or Apache web server for the installation to be complete.


    16. Note

    If you are installing the Policy Agent for Lotus Domino 5.0.10, you must configure the Domino DSAPI filter after installation. See the section "Configuring the Domino DSAPI Filter" for detailed steps.

Installing a Proxy Server Policy Agent

Use these instructions for installing a Policy Agent on Sun ONE Web Proxy Server 3.6 (in reverse proxy mode) on the Solaris 8 operating system.

To Install a Web Proxy Server Policy Agent

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.siroe.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.siroe.com.

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

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

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

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

    Failover Server Host: Enter the 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.

    CDSSO Component URL: Enter the CDSSO Component URL.

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

Installation Using the Command-Line

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

To Install a Web Server Agent Using the Command-Line

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

    2. # setup -nodisplay

  2. Set your JAVA_HOME environment variable to a JDK version 1.3.1_04 or higher. The installation requires that you set up your JAVA_HOME variable correctly. However, in case you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for supplying the correct JAVA_HOME 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 (Lotus Domino Data Directory if you are installing the Policy Agent for Lotus Domino.)

    • Web Server Protocol

    • Agent Deployment URI

    • SSL Ready (only for Apache agent)

    For more information on each of these items, see "To Install a Web Server Policy Agent."

  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

    • CDSSO Component URL

    For more information on each of these items, see "To Install a Web Server Policy Agent."

  7. The following text is displayed:

    8. Ready to Install

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

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

  8. The following text is displayed:

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

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

To Install a Web Proxy Server Agent Using the Command-Line

  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:

    • Host Name

    • Proxy Server Instance Directory

    • Proxy Server Port

    • Proxy Server Protocol

    • Agent Deployment URI

    For more information on each of these items, see "To Install a Web Server Policy Agent."

  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

    • CDSSO Component URL

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

  5. The following text is displayed:

    6. Ready to Install

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

    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

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

Configuring 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 install successive agents 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.

To Configure Agent for Multiple Web Server Instances on the Same Computer System

Once you have installed an agent on a system, you can install successive agents on that system using a 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, es4, proxy, apache or domino depending on which web server the agent is protecting.

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

# ./config

Follow the prompts to install the additional agents. For information on each of the prompts, see "To Install a Web Server Policy Agent." 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.

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

# ./config
Enter the Web Server Instance Directory: [/web_server_root/https-server_instance]
Enter the Local Hostname: [mycomputer.siroe.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.siroe.com]
Enter the Identity Server Port: [58080]
Enter the Identity Server Deployment URI [/amserver]
Enter the Identity Server's Console Deployment URI [/amconsole]
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.siroe.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:
Configuring webserver ... Webserver version: 6.0
Done


Note

The config script does not allow you to enter CDSSO details. You must configure it manually. For more information, see "Configuring CDSSO."

Using the config Script for Silent Installations

The config script can also be used to do silent and non-interactive agent installations. For details on its usage, use the config -h command to display details:

# ./config -h
Usage: config [ -r response_file | -R | -h ]
-r specifies a response file.
-R prints out the response file template.
-h prints out this message.

In order to perform a silent installation, you must supply a response.file for each of the agents you want to install. The command config -R indicates the fields which you must supply in the response.file. This text file needs to be prepared before you begin the silent installation.
./config -R
Response file contains:
AGENT_PROTOCOL # agent protocol: http|https
AGENT_HOST # agent hostname
AGENT_PORT # agent server port
AGENT_DEPLOY_URI # agent deploy URI
FAILOVER_SERVER_HOST # failover identity server name
FAILOVER_SERVER_PORT # failover identity server port
FAILOVER_SERVER_DEPLOY_URI # failover identity server deploy URI
FAILOVER_CONSOLE_DEPLOY_URI # failover identity server console deploy URI
PRIMARY_SERVER_HOST # primary identity server name
PRIMARY_SERVER_PORT # primary identity server port
PRIMARY_SERVER_PROTO # primary identity server protocol: http|https
PRIMARY_SERVER_DEPLOY_URI # primary identity server deploy URI
PRIMARY_CONSOLE_DEPLOY_URI # primary identity server console deploy URI
SHARED_SECRET # shared secret between agent and DSAME server
SERVER_INSTANCE # web server instance directory
NOTIFICATION_ENABLE # notification enabled
AGENT_URL_CASE_IGNORE # url comparison case ignore

Here is an example for response.file, named response.iws60.



AGENT_PROTOCOL=http
AGENT_HOST=mycomputer.siroe.com
AGENT_PORT=80
AGENT_DEPLOY_URI=/amagent
FAILOVER_SERVER_HOST=failover_computer.siroe.com
FAILOVER_SERVER_PORT=58080
FAILOVER_SERVER_DEPLOY_URI=/amserver
FAILOVER_CONSOLE_DEPLOY_URI=/amconsole
PRIMARY_SERVER_HOST=primary_computer.siroe.com
PRIMARY_SERVER_PORT=58080
PRIMARY_SERVER_PROTO=http
PRIMARY_SERVER_DEPLOY_URI=/amserver
PRIMARY_CONSOLE_DEPLOY_URI=/amconsole
SHARED_SECRET=encrypted_shared_secret
SERVER_INSTANCE=/opt/iws6a/https-mycomputer.siroe.com
NOTIFICATION_ENABLE=true
AGENT_URL_CASE_IGNORE=true

Below is an example showing how the config script is used in conjunction with the response.iws60 response file to complete a silent installation.
# ./config -r ./response.iws60
Configuring webserver ... Webserver version: 60
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 uninstaller must be executed only after unconfiguring all the existing agents using the command-line unconfig script.


Removing an Agent Using the unconfig Script

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

Agent_Install_Dir/SUNWam/agents/WS_TYPE/bin

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

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


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 the Key Management Utility (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: http://www-3.ibm.com/software/webservers/httpservers/doc/v1319/9atstart.htm#ssl

Configuring the Domino DSAPI Filter

Use the following procedure to configure DSAPI filter:

  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/libamdomino.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

Web or Web Proxy Server Running in SSL Mode

If your web or web proxy server is running in SSL mode, and your agent is in notification mode, you must install the root certificate of your web or web proxy server onto the Sun ONE 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 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 exists in the AMAgent.properites file, and by default it is set to true:

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

This means that the agent does not perform certificate-checking.

To Disable the Default Behavior

  1. Set the following property to false:

    2. com.sun.am.policy.agents.trustServerCerts=false

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

    3. For Apache, 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 iWS 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

The procedure for installing a root CA certificate on Sun ONE Web Server 4.1 SP8 is the same.

To Install the Root CA Certificate on Apache 1.3.26

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

  1. In C shell, at the command line, enter the following commands (assuming /etc/apache is the directory where the apache config 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

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

    • cert-dir is directory where the certificate-related files are located.

    • cert-file is the base-64 encoded root 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

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

    • cert-dir is the directory where the certificate-related files are located.

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

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

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 who 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 certificate.

    • cert-dir is the directory where the certificate-related files are located.

    • cert-file is the base-64 encoded root 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 display including 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

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 directory where the certificate-related files are located. On Solaris, 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 Sun ONE Identity Server authenticated user or anonymous user. By setting this variable to a specific user, the user becomes available to web applications (such as a CGI, servlet, or ASP program). This feature makes it possible to personalize the content of displayed HTML pages to specific users.

To enable the REMOTE_USER 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 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 both Sun ONE Web Server 6.0 SPx agent and Sun ONE Web Server 4.1 SP8 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 global not enforced list. By default, this feature is switched 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 not available for Sun ONE Web Proxy Server and Apache Agent.

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

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 uninstaller must be executed only after unconfiguring all the existing agents using the command-line unconfig script.


Before Uninstalling the Policy Agent for Lotus Domino 5.0.10

Before you uninstall the Policy Agent for Lotus Domino 5.0.10, 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 (Agent_Install_Dir/Agents/Domino/lib/libamdomino.so).

  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

  2. Click Next on Welcome Panel.

  3. Click Uninstall Now on Ready to Uninstall Panel.

  4. Click Close after uninstallation is complete.

    5. In the directory where the product binary file is unpacked (and where the installation program is invoked), there is another uninstallation program named uninstall. This uninstall program can be used to detect and uninstall all agents that were previously installed using the setup program; even agents that were installed on a remote machine. Invoke uninstall using the following command:

    # uninstall

    On the other hand, uninstall_agent will uninstall only the agent (or agents) that were previously installed with the setup program in the current directory.

Uninstalling Using the Command-Line Interface

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

    2. # ./uninstall_agent -nodisplay

    The uninstaller 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

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

Troubleshooting Solaris Agents

Cannot install Agent after previous installation is removed

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

"Sun ONE Identity Server Policy Agent 2.0 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:

  • You might have an existing installation of Agent.

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

  • The installer's productregistry file may be corrupted.

Solution:

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

  • The productregistry file may be corrupted if there is no existing installation of Agent. This file is used by the installer to track installed products. It is found in /var/sadm/install directory.


    • Note

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

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


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

The Uninstallation program does not remove entries from the agent's web server if there is another instance of web server configured using the Config script.

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

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

Ensure that you have set the DSAPI filter correctly. For steps on configuring the Domino DSAPI filter, 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'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).

On Solaris 9:

  1. Apply the latest Solaris 9 cluster patch (Patch Cluster Date Jan/23/03 or later).

  2. Download and install patch 111308-03 or above (showrev -p | grep 111308) from http://sunsolve.central.sun.com.

  3. Reboot the machine after applying the patches (it 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.

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/dsam e.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 reverse proxy agent should be the URLs qualified as "URL prefix (from client)" in the Sun ONE Web Proxy Server 3.6 admin console.

Agents are not effective any more after modification of Sun ONE Web Server or Sun ONE Web Proxy Server configuration using the respective admin console.

The changes by 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.

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