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



Chapter 5   Policy Agent for Red Hat Linux 7.2

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

Configuring Apache Web Server with Posix Threads

Before installing the agent, you must complete the following tasks in the order they are listed below to make sure Apache Web Server is configured with Posix Threads library. Failing to perform these tasks may result in the application becoming unusable or may result in the entire system becoming unstable and unusable.

  1. Get the Apache source from http://httpd.apache.org/

  2. Edit the Configure file located in the directory:

    3. /Apache_root/src

  3. Search for linux22 in the Configure file.

  4. Append -lpthread after -lm to the LIBS variable.



    		5.
    *-linux22)
           # This handles linux 2.2 and above (2.4, ...)
           DEF_WANTHSREGEX=yes
           OS='Linux'
           CFLAGS="$CFLAGS -DLINUX=22"
           LIBS="$LIBS -lm -lpthread"

  5. Save and close the file.

  6. Run the configure script located in the directory:

    7. /Apache_root/

  7. Rebuild and install Apache Web Server.

  8. Install the Apache Agent.

Installation Using the GUI

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:

    2. # gunzip -dc agent_Linux_apache.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. 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.

  5. When prompted, provide the following information about the web server this agent will protect:

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

    Host Name: Enter the FQDN of the machine where the web server is installed. For example, mycomputer.siroe.com

    Apache Configuration Directory: Specify the Apache server configuration 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.

    SSL Ready: You should 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.

    When all the information is entered correctly, click Next.

  6. Enter information about the web server that runs Sun ONE Identity Server policy and management. The Policy Agent will connect to this server.

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

    CDSSO Component URL: Enter the CDSSO Component URL.

    When all the information is entered correctly, click Next.

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

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

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

  10. You must restart your Apache web server for the installation to be complete.

Uninstalling the 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:

    2. # ./uninstall_linux_apache_agent

  2. Click Next on Welcome panel.

  3. Click Uninstall Now.

  4. Click Close after uninstallation is complete.

Installation Using the Command-Line

The command-line version of the Installation program provides you an alternative to the 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:

    2. # gunzip -dc agent_Linux_apache.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 -nodisplay

  3. When prompted, provide the following information:

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

  4. Provide the following information about the Web Server this agent will protect:

    • Web Server Host Name

    • Apache Configuration Directory

    • Web Server Port

    • Web Server Protocol

    • Agent Deployment URI

    • SSL Ready

    For more information on each of these items, see "Installing the Policy Agent."

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

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

  6. The following text is displayed:


    7. 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 is displayed:

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

Uninstalling the Policy Agent

  1. In the Agent_Install_Dir directory, at the command line, enter the following command at the command line:

    2. # ./uninstall_linux_apache_agent -nodisplay

  2. The following text is displayed:

    3. The uninstaller has detected the following agents on this system:
    1. Agent 2.0 for Apache 1.3.26 [/usr/local]
    2. Exit
    Please select an installed agent from the following list:

    Enter 1, to remove the product.

  3. The following text is displayed:

    4. Ready to Uninstall

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

    When prompted, What next? enter 1 to begin uninstallation.

  4. The following text is displayed:

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

    To see log information on the agent, enter 1. To exit the uninstallation 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 the 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.

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

Once you have installed an agent on your system, you can install successive agents on that system using a script that is copied to the system during the agent installation. The two scripts, config_linux and unconfig_linux, located in the following directory:

Agent_Install_Dir/agents/apache/bin

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

# ./config_linux

Follow the prompts to install the additional agents. For information on each of the prompts, see "Installation Using the GUI." In general, information needs to be entered for both the protected Apache server instance and the Sun ONE Identity Server server(s). The following text shows an example run:

# ./config_linux
Enter the Apache Server Configuration Directory: [/etc/httpd/conf]
SSL Ready: [true] false
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 Apache Web Server ...
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_linux script can also be used to do silent and non-interactive agent installations. For details on its usage, use the config_linux -h command to display details:

# ./config_linux -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_linux -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_linux -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.apache.


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=/Agent_Install_Dir/apache26/conf
NOTIFICATION_ENABLE=true
AGENT_URL_CASE_IGNORE=true

Below is an example showing how the config_linux script is used in conjunction with the response.apache file to complete a silent installation.


# ./config_linux -r response.apache
Configuring Apache Web Server ...
done


Note

Be sure to use the unconfig_linux script to uninstall any agent that was installed using the config_linux 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 installed using 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_linux script, use the script unconfig_linux. The unconfig_linux script is located in the following directory:

Agent_Install_Dir/agents/apache/bin

Here is an example run of the unconfig_linux script.


# ./unconfig_linux /web_server_root/httpd/conf
Unconfiguring webserver ... \c
done.

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.

The Agent's Default Trust Behavior

By default, policy agent installed on a remote Apache Server 1.3.26 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.amcpa.trustServerCerts=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.sun.am.policy.amcpa.trustServerCerts=false

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 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/httpd/apache is the directory where the Apache config file is located):

    2. # cd /etc/apache/cert

    # setenv LD_LIBRARY_PATH /Agent_Install_Dir/agents/apache/lib:/Agent_Install_Dir/agents/lib

  2. Create the necessary certificate database if you have not already done.

    3. # /Agent_Install_Dir/agents/apache/cert/certutil -N -d .

  3. Install root CA certificate.

    4. # /Agent_Install_Dir/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 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

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

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

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 AMConfig.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. If the agent gets redirected to the Sun ONE Identity Server, this indicates the above steps were executed properly.

Troubleshooting Information

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

Solution: 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 to Apache server documentation at http://httpd.apache.org/

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