Chapter 9   URL Policy Agent for IBM HTTP Server 1.3.19


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 the Sun ONE Identity Server Policy Agent for IBM HTTP Server 1.3.19 running on Solaris 8 operating system.

Topics include:

• Before You Begin

• Using the Graphical User Interface (GUI) Version of the Installation Program

• Using the Command-Line Version of the Installation Program

• Using Secure Sockets Layer (SSL) with an Agent

• Setting the REMOTE_USER Server Variable

• Forwarding LDAP User Attributes via HTTP Headers

• Validating Client IP Addresses

• Known Issues

Before You Begin

---

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

• How Policy Agents Work

• Java Runtime Environment (JRE) 1.3.1_04 Requirement

• The Web Server that Runs Identity Server Services vs. Remote Web Servers

• Providing Failover Protection for Identity Server Agents

• The AMAgent.properties File

Using the Graphical User Interface (GUI) Version of the Installation Program

---

Use the GUI version of the Installation program to install agent.

Installing the Policy Agent Using GUI

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

1. Unpack the product binaries using the following command:

   # /bin/gzcat ibm_httpserver_1.3.19_agent_1.0_Solaris2.8.tar.gz | /bin/tar -xvf -
   

   ---

   Note	Use the tar that is shipped with Solaris. Don't use the GNU tar.

   ---

   
   

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

   # ./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:

   Please enter path to pick up java:

   Enter the full path where JDK is located to launch the installer.

4. In the Welcome page, click Next.

5. Read the License Agreement. Click Yes to agree to the license terms.

6. In the Select Installation Directory window, provide the following information:

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

7. By default, Sun(TM) ONE Identity Server Policy Agent 1.0 for IBM HTTP Server 1.3.19 is selected, click Next.

8. In the Agent Web Server Information window, provide the following information about the IBM HTTP server this agent will protect:

   Host Name: Enter the fully qualified domain name of the machine where the IBM HTTP server is installed. For example, mycomputer.siroe.com.

   IBM HTTP Server config file: Enter the full path to the directory where the httpd.conf file is located.

   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

   The URI prefix tells the web server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the web server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the web server Document Root.

   When all the information is entered correctly, click Next.

9. In the Identity Server Information window, provide information about the web server that runs Identity Server policy and management services. The URL Policy Agent will connect to this server.

   Identity Server Services Host: Enter the fully qualified domain name of the system where the primary web server that runs Identity Server services is installed. For example, myserver.siroe.com.

   Identity Server Services Port: Enter the port number for the web server that runs Identity Server services.

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

   Identity Server Services Deployment URI: Enter the location that was specified when Identity Server was installed. The default Universal Resource Identifier (URI) for Identity Server is /amserver.

   Failover Server Host: If you have configured a failover web server to run Identity Server services, enter the host name of the failover system. Examples: backup.siroe.com. If there is no failover server, then leave this field blank.

   Failover Server Port: If you have configured a failover web server to run Identity Server services, enter the web server port number. If there is no failover host server, then leave this field blank.

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. You must restart your IBM HTTP server for the installation to be complete. At the command line enter the following:

    /opt/IBMHTTPD/bin/apachectl stop

    /opt/IBMHTTPD/bin/apachectl start

Uninstalling and Disabling the Policy Agent

When you no longer require the URL policy agent, you can uninstall it or disable it.

Uninstalling a URL Policy Agent

Use the following steps to uninstall the Policy Agent.

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

   # ./uninstall_IBMHttp

   The uninstallation 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:

   Please enter path to pick up java:

   Enter the full path where JDK is located to launch the installer.

2. Click Next on Welcome panel.

3. In the Select Type of Uninstall panel, select Full and click Next.

4. Click Uninstall Now.

5. Click Exit after uninstallation is complete.

Disabling a URL Policy Agent

Use the following steps to disable a URL Policy Agents.

1. In the file httpd.conf remove or comment out the following line:

   # include /etc/opt/SUNwam/conf/IBMHTTP/_opt_IBMHTTPD_conf/dsame.conf

2. Restart the server:

   /opt/IBMHTTPD/bin/apachectl stop

   /opt/IBMHTTPD/bin/apachectl start

Using the Command-Line Version of the Installation Program

---

The command-line version of the Installation program provides you an alternative to the graphical user interface (GUI) version.

Installing an Agent Using the Command Line

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

1. Unpack the product binaries file using the following command:

   # /bin/gzcat ibm_httpserver_1.3.19_agent_1.0_Solaris2.8.tar.gz | /bin/tar -xvf -

   
   

   ---

   Note	Use the tar that is shipped with Solaris. Don't use the GNU tar.

   ---

   
   

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

   # ./setup -nodisplay

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:

   Please enter path to pick up java:

   Enter the full path where JDK is located to launch the installer.

4. 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 Policy Agent in this directory: Enter the full path to the directory in which you want to install the policy agent.

   The following text displays:

   Sun ONE Identity Server Policy Agent for IBM HTTP Server components showing a checked box will be installed. Only one agent may be installed at a time. [ ]  1 Sun(TM) ONE Identity Server Policy Agent 1.0 for IBM HTTP Server 1.3.19

   To check a particular component, enter its number, or 0 when you are finished: Enter the number that corresponds to the policy agent you want to install. The following message displays, with a cross mark beside the server you specified.

   [X]  1 Sun(TM) ONE Identity Server Policy Agent 1.0 for IBM HTTP Server 1.3.19

   To check a particular component, enter its number, or 0 when you are finished: Enter 0 to continue.

5. Provide the following information about the IBM HTTP server this agent will protect.
   • Host Name

   • IBM HTTP Server config file

   • Web Server Port

   • Web Server Protocol

   • Agent Deployment URI

   For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 140.

6. Provide the following information about the web server that runs Identity Server services. The following fields refer to the system where Identity Server is installed.
   • Identity Server Services Host Name

   • Identity Server Services Port Number

   • Identity Server Services Protocol

   • Identity Server Services Deployment URI

   • Failover Server Host

   • Failover Server Port

   For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 140.

7. The following text displays:

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

   Product                                 Result     More Info 1.Sun ONE Identity Server Policy Agent  Installed  Available 2.Done

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

Uninstalling an Agent Using the Command Line

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

   #./uninstall_IBMHttp -nodisplay

2. The following text displays:

   Please select the type of uninstall to perform from the following choices: 1. Full 2. Partial

   To remove the product and all of the components from your system, enter 1 for Full. To remove some, but not all, product components, enter 2 for Partial.

3. The following text displays:

   Ready to Uninstall 1. Uninstall Now 2. Start Over 3. Exit Uninstallation

   When prompted, What would you like to do? enter 1 to begin uninstallation.

4. The following text displays:

   Product                                 Result  More Info 1.Sun ONE Identity Server Policy Agent  Full    Available 2.Done

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

Using Secure Sockets Layer (SSL) with an Agent

---

During installation, if you specify the HTTPS protocol for the web server that runs Identity Server services, the agent is automatically configured to communicate over SSL with Identity Server services.

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

   # /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

The Agent's Default Trust Behavior

By default, a URL policy agent is installed on a IBM HTTP server that will trust any server certificate presented over SSL by the web server that runs Identity Server services; the agent does not check the root Certificate Authority (CA) certificate. If the web server that runs Identity Server services is SSL-enabled, and you want the URL 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 IBM HTTP Server (where the agent is installed). The CA certificate must the be same one that is installed on the web server that runs 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.iplanet.am.policy.agents.trust_server_certs=true

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

To Disable the Default Behavior

The following property must be set to false:

com.iplanet.am.policy.agents.trust_server_certs=false

Installing the CA Certificate

The CA certificate that you install on the IBM HTTP Server must be the same one that is installed on the web server that runs Identity Server services.

To Install the CA Certificate on IBM HTTP Server

You can use the certutil program to install the CA Certificate on IBM HTTP Server.

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

   # cd /Agent_Install_Dir/SUNWam/IBMHttp/cert

   # setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/IBMHttp/lib

   # export LD_LIBRARY_PATH

   # ./certutil -A -n cert-name -t "C,C,C" -d . -i cert-file

   In the commands 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.

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

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

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

   # ./certutil -L -d .

   Trust database information will display including the name of the CA certificate you installed. Example:

   Certificate Name Trust Attrubutes rootCAcert p Valid peer P Trusted peer (implies p) c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to certs(only server certs for ssl) (implies c) u User cert w Send warning

Setting the REMOTE_USER Server Variable

---

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

REMOTE_USER will be set while accessing allowed URLs.

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.iplanet.am.policy.agents.anonRemoteUser.enable=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.iplanet.am.policy.agents.unauthenticatedUser=anonymous

Forwarding LDAP User Attributes via HTTP Headers

---

Identity Server agent has the ability to forward LDAP user attribute values via HTTP headers to end web applications. The LDAP user attribute values come from the server side of Identity Server. An Identity Server agent behaves like a broker to obtain and relay user attribute values to the destination servlets, CGI scripts, or ASP pages. These applications can in turn use the attribute values to personalize page content.

This feature is configurable through two properties in AMAgent.properties file. To turn this feature on and off, use the following AMAgent.properties file property:

com.iplanet.am.policy.agents.foward_ldapattr_in_http_headers.enable

By default, this property is set to false, and the feature off. To turn on attribute forwarding, set this property to true. To configure the attributes that are to be forwarded in the HTTP headers, use the AMAgent.properties file property com.iplanet.am.policy.agents.ldapattr.

Below is an example section in the AMAgent.properties file which shows how this feature is used:

# Ldap User Attributes

# format: ldap_attribute_name|http_header_name

#

# below are a few notes based on different behaviours of web servers

#

# NOTE: for iWS agents, "http_header_name" must be in lower-case letters,

# and any _ will become _

# NOTE: for IIS, Apache and IBM HTTP Server agents"http_header_name" will be prefixed

# by HTTP_, and all lower case letters will become upper case,

# and any - will become _

#

com.iplanet.am.policy.agents.ldapattr=cn|common-name,ou|organization-unit ,o|organization,c|country,mail|email,employeenumber|employee-number

By default, some LDAP user attribute names and HTTP header names are set to sample values.

To find the appropriate LDAP user attribute names, check the following XML file on the machine where the Identity Server is installed:

DSAME_Install_Dir/SUNWam/config/xml/amUser.xml

The attributes in this file could be either Identity Server User attributes or Identity Server Dynamic attributes (for explanation of these two types of user attributes, refer to the Sun ONE Identity Server Administration Guide).

The attribute and HTTP header names that need to be forwarded must be determined by the end-user applications on the IBM HTTP server that the agent is protecting—after all, these applications are the consumers of the forwarded header values (the forwarded information is used for the customization and personalization of web pages).

Each IBM HTTP server has its own peculiarities about HTTP header name conventions. For more information on this feature, refer to the comments listed before each respective property in the AMAgents.properties file.

Validating Client IP Addresses

---

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

The AMAgent.properties file contains a property titled com.iplanet.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.

com.iplanet.am.policy.agents.client_ip_validation.enable=true

Cookie Reset Feature

---

This feature enables the Identity Server Policy Agent to reset some cookies in the browser session while redirecting to Identity Server for authentication. Currently, this feature is available only for IBM HTTP Server Agent.

This feature is configurable through two properties in AMAgent.properties file.

• Enable Cookie Reset

  com.iplanet.am.policy.agents.cookie.reset.enable=true

  This property must be set to true, if this agent needs to reset cookies in the response while redirecting to Identity Server for Authentication. By default, this is set to false.

• Cookie List

  This property gives the comma separated list of cookies, that needs to be reset in the response while redirecting to Identity Server for authentication.

  This property is used only if the Cookie Reset feature is enabled.

  com.iplanet.am.policy.agents.cookie.reset.list=LtpaToken, otherToken

Known Issues

---

• First value not displayed for objectclass attribute

  Occasionally, the first value is not displayed for objectclass attribute that is added to HTTP LDAP header.

• Error message not dispalyed when null or space value is entered for installation directory.

  During agent installation, if space or null value is entered for installation directory, the installation program proceeds without displaying any error message and the agent is installed in the default directory (/opt).