Web Policy Agents Guide |
Chapter 2
Policy Agents on Solaris and HP-UXSunTM 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 BeginBe 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 AgentThe 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.
- Unpack the product binary using the following command:
# gunzip -dc binaryname.tar.gz| tar -xvof -
- Run the setup program. You’ll find the program in the directory where you untarred the binaries. At the command line, enter the following:
# ./setup
- 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:
Please enter JAVAHOME path to pick up java:
- Type the full path to the directory where JDK is located. The installation program starts with the Welcome page.
- In the Welcome page, click Next.
- Read the License Agreement. Click Yes to agree to the license terms.
- In the Select Installation Directory panel, specify the directory where you would like to install the agent.
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.
- Click Next and provide the following information about the web server the agent will protect:
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.
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:
- When you have entered all the information correctly, click Next.
- Enter information about the web server that runs Sun ONE Identity Server. The policy agent will connect to this server.
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.
- When all the information is entered correctly, click Next.
- 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.
- In the Ready to Install panel, click Install Now.
- When the installation is complete, you can click Details to view details about the installation, or click Exit to end the installation program.
- 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.
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.
- Unpack the product binaries using the following command:
# gunzip -dc agent_SunOS_proxy.tar.gz | tar -xvof -
- Run the setup program. You will find the program in the directory where you untarred the binaries. At the command line, enter the following:
# ./setup
- In the Welcome page, click Next.
- Read the License Agreement. Click Yes to agree to the license terms.
- To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next.
- When prompted, provide the following information about the web proxy server where this agent will be installed:
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.
- When all the information is entered correctly, click Next.
- When prompted, provide the following information about the web server that runs Sun ONE Identity Server.
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.
- When all the information is entered correctly, click Next.
- 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.
- In the Ready to Install page, click Install Now.
- When the installation is complete, you can click Details to view details about the installation, or click Exit to end the Installation program.
- 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
- In the directory where you unpacked the binaries, at the command line, enter the following:
# setup -nodisplay
- 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:
Please enter JAVAHOME path to pick up java:
- Type the full path to the directory where JDK is located and press Enter.
- When prompted, provide the following information:
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.
- 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."
- 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:
- When prompted, What would you like to do?, enter 1 to start the installation.
The following text is displayed:
- To see log information, enter 1. To exit the installation program, enter 2.
Installing the Policy Agent for a Web Proxy Server
- In the directory where you unpacked the binaries, at the command line, enter the following:
# setup -nodisplay
- When prompted, provide the following information:
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.
- 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 "Installing the Policy Agent for a Web Server."
- 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:
- When prompted, What would you like to do?, enter 1 to start the installation.
The following text is displayed:
- To see log information, enter 1. To exit the installation program, enter 2.
- Restart the Proxy Server.
Post-installation TasksThe 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:
- In Lotus Domino Administrator, choose Administrator Tab > Server > All Server Documents.
- From the listed servers, select the required server.
- Click Internet Protocols > HTTP tab.
- At the DSAPI Filter File Names field, enter the file names as follows:
- Click the Save and Close button to save the changes.
- Open Domino console and restart the server by entering the following commands:
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:
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 InstancesTo 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
- To configure the agent for additional web server instances on a system, run the config script from the bin directory using the following command:
# ./config
- 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.
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 AgentDuring 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:
Configuring the IBM HTTP Server
Use the following instructions to configure the IBM HTTP Server to run in SSL mode.
- 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
- 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
- Start the Administration Server
# /opt/IBMHTTPD/bin/adminctl start
- 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
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:
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
- Set the following property to false:
com.sun.am.trustServerCerts=false
- Set the directory Cert DB in the file AMAgent.properties as shown in the following example:
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
- Set the Cert DB Prefix, if required.
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.
- In C shell, at the command line, enter the following commands (assuming /etc/apache is the directory where the apache configuration file is located):
# cd /etc/apache/cert
# setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/agents/apache/lib:/Agent_Install_Dir/SUNWam/agents/lib:/usr/lib/mps
- Create the necessary certificate database if you have not already done so.
# /Agent_Install_Dir/SUNWam/agents/apache/cert/certutil -N -d .
- Install root CA certificate.
# /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:
- To verify that the certificate is properly installed, at the command line, enter the following:
# ./certutil -L -d .
Trust database information will be displayed including the name of the root CA certificate you installed. For example:
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.
- In C shell, at the command line, enter the following commands:
# 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
- Create the necessary certificate database if you have not already done so.
- Install root CA certificate.
# /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:
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.
- In C shell, at the command line, enter the following commands:
# mkdir server_instance_dir/cert
# setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/agents/
ibmhttp/lib:/Agent_Install_Dir/SUNWam/agents/lib- Create the necessary certificate database if you have not already done so.
# /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:
Make sure that the UNIX user that the IBM HTTP server runs as (for example nobody), has read permissions on these three files.
- Install root CA certificate.
# /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:
- To verify that the certificate is properly installed, at the command line, enter the following:
# ./certutil -L -d .
Trust database information will be displayed including the name of the root CA certificate you installed. See the following example.
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.
- Go to the following directory:
Agent_Install_Dir/Agents/domino/utils
- 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:
certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file
- In the command above, the variables represent the following:
- Restart Domino Web Server.
Setting the REMOTE_USER Server VariableThe 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
Validating Client IP AddressesThis 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 PreservationPOST 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.
Shared Secret Encryption UtilityThe 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.
- Go to the following directory:
Agent_Install_Dir/bin
- Execute the following script from the command line:
# ./crypt_util shared_secret
- Cut and paste the output from Step 2 in the property:
com.sun.am.policy.am.password
- Restart the web server and try accessing any resource protected by the agent.
Uninstalling a Policy AgentThe following sections provide steps for uninstalling the agent. Note the following:
- Be sure to use the unconfig script to uninstall any agent that was installed using the config script.The uninstallation program must be executed only after unconfiguring all the existing agents using the command-line unconfig script.
- If you want to uninstall the web server for some reason, make sure that you uninstall the agent before you uninstall the web server.
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.
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.
- Launch Lotus Domino Administrator.
- Choose Administrator Tab > Server > All Server Documents.
- From the listed servers, select the server you want to uninstall.
- Click Internet Protocols > HTTP tab.
- Remove the DSAPI filter file name specified for the Lotus Domino agent.
- Click the Save and Close button to save the changes.
- Open the Domino console and restart the server by entering the following commands:
tell http quit
load http
Uninstalling Using the GUI
To uninstall an agent, you must run the uninstallation program. Follow the steps below:
- In the directory where the agent is installed, at the command line, enter the following command:
# ./uninstall_agent
On HP-UX 11.11, use the following command:
java uninstall_Sun_ONE_Identity_Server_Policy_Agent
- Click Next on Welcome panel.
- Click Uninstall Now on Ready to Uninstall panel.
- Click Close after uninstallation is complete.
- Restart the web server.
Uninstalling From the Command-Line
- From the directory where the agent is installed, enter the following command at the command line:
# ./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:
- When prompted, What next? enter 1 to begin uninstallation.
The following text is displayed:
- To see log information, enter 1. To exit the uninstallation program, enter 2.
- Restart the web server.
TroubleshootingCannot 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:
- Check that you have uninstalled any existing installation of the agent.
- The productregistry file may be corrupted if there is no existing installation of the agent. This file is used by the installation program to track installed products. It is found in /var/sadm/install directory.
Remove the agent entry in this file. This entry starts with the following lines:
<compid>SUNWamcom
<compversion>2.1
<uniquename>SUNWamcom</uniquename>
<vendor></vendor>
......
</compid>
<compid>Agent uninstall script
<compversion>2.1
<uniquename>Agent uninstall script</uniquename>
<vendor>Sun Microsystems, Inc.</vendor>
......
</compid>
<compid>Agent installer resource bundle
<compversion>2.1
<uniquename>Agent installer resource bundle</uniquename>
<vendor>Sun Microsystems, Inc.</vendor>
......
</compid>
<compid>Agent Common Core and SDK
<compversion>2.1
<uniquename>Agent Common Core and SDK</uniquename>
<vendor></vendor>
......
</compid>
<compid>SUNWames6
<compversion>2.1
<uniquename>SUNWames6</uniquename>
<vendor></vendor>
......
</compid>
<compid>Agent for ...
<compversion>2.1
<uniquename>Agent for ...</uniquename>
<vendor></vendor>
......
</compid>
<compid>Sun ONE Identity Server Policy Agent
<compversion>2.1
<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 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:
- Apply the latest Solaris 8 cluster patch (Patch Cluster Date Jan/24/03 or later).
- Download and install patch 111308-03 or later (showrev -p | grep 111308) from http://sunsolve.central.sun.com.
- Reboot the machine after applying the patches (this is recommended but not mandatory).
For agents running on Sun ONE Web Server 6.0:
- In your web server instance directory, open the start script.
- Before the first LD_LIBRARY_PATH line, add the following two lines
LD_PRELOAD=libmtmalloc.so.1
export LD_PRELOAD
- To make sure the patches are installed correctly, try this. It should produce a line of output.
showrev -p | grep 111308
- To verify that libmtmalloc is being used by the web server, do the following.
ps -ef |grep httpd | grep nobody
- Take the pid from the previous step and do
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 ProblemsAfter 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.