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



Chapter 5   Policy Agent for Apache 1.3.22 From Red Hat


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 Apache 1.3.22 server running on the Red Hat Linux 7.2 operating system.

Topics include:



Before You Begin

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



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

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

  1. Unpack the product binaries using the following command:

    # gunzip -dc agents-1.1-domestic-us.i686-intel-linux.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:

    # ./setup_linux

  3. In the Welcome page, click Next.

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

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

  6. By default, Sun ONE Identity Server Policy Agent for Apache 1.3.22 is selected, click Next.

  7. In the Agent Web Server Information window, provide the following information about the Apache web server this agent will protect:

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

    Apache config File Location: 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.

  8. In the Identity Server Information window, provide information about the web server that runs Identity Server policy and management services.

    Identity Server 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 Port: Enter the port number for the web server that runs Identity Server services.

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

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

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

  10. In the Ready to Install page, click Install Now.

  11. When the installation is complete, you can click Details to view details about the installation, or click Exit to end the Installation program.

  12. You must restart your Apache web server for the installation to be complete. At the command line enter the following:

    /etc/init.d/httpd restart


Uninstalling and Disabling Policy Agent

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


Uninstalling the Policy Agent

Follow the steps below:

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

    # java uninstall_Identity_Server_Policy_Agent

  2. Click Next on Welcome panel.

  3. On Type of Install panel, select Full.


    Note

    Since there is only one component, it is recommended that you select Full uninstallation.The Partial uninstallation is not supported.


  4. Click Uninstall Now.

  5. Click Exit after uninstallation is complete.


Disabling a Policy Agent

Follow the steps below:

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

    # include /Agent_Install_Dir/apagent/conf/dsame.conf

  2. Restart the server.

    /etc/init.d/httpd restart



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 the Policy Agent

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

  1. Unzip the Solaris tar file using the following command:

    # gunzip -dc agents-1.1-domestic-us.i686-intel-linux.tar.gz | tar -xvof -

  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_linux -nodisplay

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

    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 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 for Apache 1.3.22

    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 for Apache 1.3.22

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

  4. Provide the following information about the Apache web server this agent will protect.

    • Host Name

    • Apache config File Location

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

  5. 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 Host Name

    • Identity Server Port Number

    • Identity Server Protocol

    • Identity Server 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 84.

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

  7. 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 the Policy Agent

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

    # java uninstall_Identity_Server_Policy_Agent -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.


    Note

    Since there is only one component, it is recommended that you enter 1 for Full uninstallation.The Partial uninstallation is not supported.


  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 Sun ONE Identity Server services, the agent is automatically configured to communicate over SSL with Sun ONE Identity Server services.


The Agent's Default Trust Behavior

By default, a policy agent is installed on a web 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 Certificate Authority (CA) certificate. If the web server that runs Identity Server services 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 CA certificate on the Apache web server (where the agent is installed). The CA certificate must be the 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.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 Apache web server must be the same one that is installed on the web server that runs Identity Server services.


To Install the CA Certificate on Apache Web Server

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

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

    # cd /Agent_Install_Dir/SUNWam/apagent/cert

    # setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/apagent/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

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



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 and Apache 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 Apache web 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).


Note

Each Apache web server has its own peculiarities about HTTP header name conventions. For more information on this feature, refer to the comments listed before each 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.



Troubleshooting Information


If you are experiencing problems with your installation try the following:

  • Check the httpd.conf file in the config directory in the Apache Server has a fully qualified domain name for the ServerName variable.

  • Ensure that you have set your machine with a fully qualified domain name.

  • Check the debug.directory in the AMAgent.properties file. The log file directory is specified by the property: com.iplanet.services.debug.directory in the AMAgent.properties file located in the directory /Agent_Install_Dir/apagent/conf. Verify whether this directory is created with proper permissions.

  • Verify the following in /Agent_Install_Dir/apagent/conf/dsame.conf:

    • The first line should be:

      LoadModule dsame_module /Agent_Install_Dir/apagent/lib/mod_dsame.so

    • Agent_Config_file should point to the location of AMAgent.properties

    • Shared_Lib_Dir should be Agent_Install_Dir/apagent/lib

  • Check the following Identity Server variables are set properly in the AMAgent.properties file.

    com.iplanet.am.server.protocol

    com.iplanet.am.server.port

    com.iplanet.am.server.host

    com.iplanet.am.naming.url

    com.iplanet.am.policy.agents.url.authLoginUrl

  • Check the following properties are set with correct values when failover server is enabled.

    com.iplanet.am.policy.agents.url.failover.server.host

    com.iplanet.am.policy.agents.url.failover.server.port

    com.iplanet.am.policy.agents.url.failoverAuthLoginUrl


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

Last Updated November 20, 2002