test

Sun Java System Access Manager Policy Agent 2.2 Guide for Apache HTTP Server 2.2

Chapter 4 Installing the Apache HTTP Server 2.2 Policy Agent

This chapter describes how to install the Apache HTTP Server 2.2 agent, including:

Note –

Because the Apache HTTP Server 2.2 agent was developed as part of the OpenSSO project, the distribution files are available only in .zip file format. Also, the installation is similar for all platforms, so this chapter is not divided into platform-specific sections

After you have successfully installed the agent, as described in this chapter, complete the post-installation tasks described in Chapter 6, Post-Installation Tasks for the Apache HTTP Server 2.2 Agent.

Preparing to Install the Apache HTTP Server 2.2 Agent

Follow the specific steps in this section before you install the web agent to reduce the chance of complications occurring during and after the installation.

ProcedureTo Prepare to Install the Apache HTTP Server 2.2 Agent

  1. Ensure that the Apache HTTP Server 2.2 agent is supported on the desired platform, as listed in Supported Platforms and Compatibility for the Apache HTTP Server 2.2 Policy Agent.

  2. If necessary, install and configure the Apache HTTP Server 2.2 web container.

    Also, check that the Apache HTTP Server 2.2 has the latest patches.

    For more information, refer to the Apache HTTP Server 2.2 documentation: http://httpd.apache.org/docs/2.2/

  3. Set your JAVA_HOME environment variable to a JDK version 1.5.0 or higher.

    The installation program requires that your JAVA_HOME variable be set correctly. If you have incorrectly set the JAVA_HOME variable, the setup script will prompt you to supply the correct path:

    Please enter JAVA_HOME path to pick up java:

  4. (Conditional) Create a valid agent profile in the Access Manager Console, if one has not already been created.

    Web agents can function using the default agent profile (UrlAccessAgent), but creating a different agent profile provides greater security. You must also create a different agent profile if Access manager is configured for cross domain single sign-on (CDSSO).

    For information about how to create an agent profile, see Chapter 5, Relationship Between the Agent Profile and Web Agents.

    To avoid configuration problems for the agent, you must know the agent profile ID and password used to create the agent profile. You must specify the agent profile password in the next step, and you must enter the agent profile ID when you install the agent.

  5. Create an agent profile password word file.

    An agent profile password file is a text file with one line that contains the agent profile password. You will need to provide the path to this file during the agent installation process. By using an agent profile password file, you do not need to enter the password during the agent installation. Set the security permissions for this file as required for your specific deployment.

  6. Unzip the web agent .zip file. For example:

    # unzip apache_v22_platform_agent.zip

    where platform identities the specific platform where you are installing the agent:

    SunOS — Solaris SPARC systems

    SunOS_x86 — Solaris x86 systems

    Linux — Linux systems

    WINNT — Windows systems

  7. On UNIX-based systems, ensure that the following programs have executable permissions:

    • agentadmin

    • crypt_util

    • certutil

    These programs are located in the PolicyAgent-base/bin directory. For example, to secure these programs on Solaris systems:

    # chmod +x agentadmin crypt_util certutil

Installing the Apache HTTP Server 2.2 Agent

The agent installation program (agentadmin) performs the following operations:

ProcedureTo Install the Apache HTTP Server 2.2 Agent

  1. Change to the PolicyAgent-base/bin directory.


    PolicyAgent-base/bin

    For information about the PolicyAgent-base directory, seeLocation of the Web Agent Base Directory in Policy Agent 2.2.

  2. Issue the following command:


    ./agentadmin --install

  3. If you receive license agreement information, accept or reject the agreement. If you reject any portion of the agreement, the installation program will end.

    The license agreement is displayed only during the first run of the agentadmin program.

  4. After you accept the license agreement (if necessary), provide the following information when requested by the installation program (or accept the default values):

    • Path to the Apache HTTP Server 2.2 configuration directory

    • Access Manager services host name, port, and protocol

    • Access Manager services deployment URI

    • Agent host name, port, and protocol

    • Agent profile name and password file

    The prompts are shown in Example of the Installation Program Interaction for the Apache HTTP Server 2.2 Agent.

    Key points about the installation program to consider include:

    • Each step in the installation program includes an explanation that is followed by a more succinct prompt.

    • For most of the steps you can type any of the following characters to get the results described:

      ?

      Type the question mark to display Help information for that specific step.

      <

      Type the left arrow symbol to go back to the previous interaction.

      !

      Type the exclamation point to exit the program.

    • Most of the steps provide a default value that can be accepted or replaced. If a default value is correct for your site, accept it. If it is not correct, enter the correct value.

  5. After you entered all values, the installation program displays a summary of your responses.

    Note the agent instance name, such as Agent_001. You might be prompted for this name during the configuration process.

    • If you are satisfied with the summary, choose 1 (the default).

    • If you want to edit input from the last interaction, choose 2.

    • If you want to edit input starting at the beginning of the installation program, choose 3.

    • If you want to exit the installation program without installing, choose 4.

    Edit your responses if needed. When you are satisfied with your responses, choose option 1 to continue with the installation.

About the Installation Prompts for the Apache HTTP Server 2.2 Agent

The following list provides information about specific prompts in the installation.

Apache HTTP Server 2.2 configuration directory path

Enter the path to the Apache HTTP Server 2.2 configuration directory. The default is /usr/local/apache2/conf.

Access Manager services host name, port, and protocol

Enter the fully qualified host name, port, and protocol for the server where Access Manager is installed. The default port is 80, and the default protocol is http.

Access Manager services deployment URI

Enter the URI that will be used to for Access Manager. The default value is /amserver.

Agent profile name

To use an agent profile, you must create the profile as a pre-installation step, as described in Preparing to Install the Apache HTTP Server 2.2 Agent. For more information about creating an agent profile, see also Chapter 5, Relationship Between the Agent Profile and Web Agents. The default is UrlAccessAgent.

Web agents can function using the default agent profile (UrlAccessAgent), but creating a different agent profile provides greater security. You must also create a different agent profile if Access manager is configured for cross domain single sign-on (CDSSO).

Agent profile password file

You should create the agent profile password file as a pre-installation step as described in Preparing to Install the Apache HTTP Server 2.2 Agent.

When the installation program prompts you for the password for the agent, enter the fully qualified path to this password file.

Example of the Installation Program Interaction for the Apache HTTP Server 2.2 Agent

The following example shows a sample installation for the Apache HTTP Server 2.2 agent.

************************************************************************
Welcome to the Access Manager Policy Agent for Apache Server If the Policy
Agent is used with Federation Manager services, User needs to enter
information relevant to Federation Manager.

************************************************************************


Do you completely agree with all the terms and conditions of this License 
Agreement (yes/no): [no]: yes


Enter the complete path to the directory which is used by Apache Server to
store its configuration Files. This directory uniquely identifies the
Apache Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Apache Server Config Directory Path [/usr/local/opt/apache2/conf]:
/usr/local/opt/apache2/conf


Enter the fully qualified host name of the server where Access Manager
Services are installed.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Host: amhost.example.com


Enter the port number of the Server that runs Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services port [80]: 8080


Enter http/https to specify the protocol used by the Server that runs Access
Manager services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Protocol [http]:


Enter the Deployment URI for Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Deployment URI [/amserver]:


Enter the fully qualified host name on which the Web Server protected by the
agent is installed.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Host name: agenthost.example.com


Enter the preferred port number on which the Web Server provides its
services.
[ ? : Help, < : Back, ! : Exit ]
Enter the port number for Web Server instance [80]: 7000


Select http or https to specify the protocol used by the Web server instance
that will be protected by Access Manager Policy Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the Preferred Protocol for Web Server instance [http]:


Enter a valid Agent profile name. Before proceeding with the agent
installation, please ensure that a valid Agent profile exists in Access
Manager.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name [UrlAccessAgent]:


Enter the path to a file that contains the password to be used for identifying
the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /opt/agent-profile-password-file


-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Apache Server Config Directory : /usr/local/opt/apache2/conf
Access Manager Services Host : amhost.example.com
Access Manager Services Port : 8080
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : agenthost.example.com
Web Server Instance Port number : 7000
Protocol for Web Server instance : http
Agent Profile name : UrlAccessAgent
Agent Profile Password file name : /opt/agent-profile-password-file

Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:

Summary of an Agent Installation

At the end of the installation process, the installation program prints the status of the installation along with the installed agent information. The information that the program displays can be very useful. The program also displays the location of specific files, which can be of great importance.

You might want to view the installation log file after the installation is complete, before performing the post-installation steps as described in Chapter 6, Post-Installation Tasks for the Apache HTTP Server 2.2 Agent.

The location of directories displayed by the installer are specific. However, throughout this guide and specifically in the summary of the agent installation shown in this section, PolicyAgent-base represents the directory where the distribution files are stored for a specific web agent:


Agent-HomeDirectory/web_agents/apache22_agent

where Agent-HomeDirectory is the directory where you unzipped the web agent distribution file.

Information regarding the location of the web agent base directory is also described in Location of the Web Agent Base Directory in Policy Agent 2.2.

The installation program prints the following information:

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Configuration file location:
PolicyAgent-base/Agent_001/config/AMAgent.properties
Agent Audit directory location:
PolicyAgent-base/Agent_001/logs/audit
Agent Debug directory location:
PolicyAgent-base/Agent_001/logs/debug

Install log file location:
PolicyAgent-base/logs/audit/install.log

Thank you for using Access Manager Policy Agent

After the agent is installed, the directories shown in the previous example are created in the Agent_00x directory, which for this example is Agent_001. Those directories and files are described in the following paragraphs.

PolicyAgent-base/Agent_001/config/AMAgent.properties

Location of the web agent AMAgent.properties configuration file for the agent instance. Every instance of a web agent has a unique copy of this file. You can configure this file to meet your site's requirements. For more information, see the following sections:

PolicyAgent-base/Agent_001/logs/audit

Location of the web agent local audit trail.

PolicyAgent-base/Agent_001/logs/debug

Location of all debug files required to debug an agent installation or configuration issue.

PolicyAgent-base/logs/audit/install.log

Location of the file that has the agent install file location. If the installation failed for any reason, you can look at this file to diagnose the issue.

Implications of Specific Deployment Scenarios for the Apache HTTP Server 2.2 Agent

The following sections refer to specific deployment scenarios involving the Apache HTTP Server 2.2 agent. These scenarios can affect how you respond to prompts during the installation process. You might also need to perform additional configuration operations.

Configuring the Apache HTTP Server 2.2 Agent for Multiple Apache HTTP Server Virtual Hosts

Consider the scenario where the Apache HTTP Server 2.2 has two virtual hosts: http://site1.example.com/ and http://site2.example.com/.

ProcedureTo Enforce Access to the Individual Virtual Hosts

  1. Define the FQDN map property in the AMAgent.properties file as:

    com.sun.am.policy.agents.config.fqdn.map =
     valid1|site1.example.com,valid2|site2.example.com

  2. Define policies in Access Manager with virtual host names in the policy rules.

ProcedureTo Protect Only http://site1.example.com/ and Not http://site2.example.com/

  1. Define the FQDN map property in the AMAgent.properties file as:

    com.sun.am.policy.agents.config.fqdn.map =
   valid1|site1.example.com,valid2|site2.example.com

  2. Define the site2 URLs in the not-enforced URL list.

Installing the Apache HTTP Server 2.2 Agent on the Access Manager Host

Note –

Installing the Apache HTTP Server 2.2 agent on the Access Manager host is not recommended for production deployments because performance can be degraded.

However, if you want to install the agent on the Access Manager host on the same Apache HTTP Server 2.2 instance, add all of the URLs related to Access Manager to the not enforced URL list. Configuring the not-enforced URL list is described in Configuring the Not-Enforced URL List. If you are installing the agent on a different Apache HTTP Server 2.2 instance, configuration of the not-enforced URL list is not required.

Verifying a Successful Installation for the Apache HTTP Server 2.2 Agent

After installing the Apache HTTP Server 2.2 agent, ensure that it is installed successfully by using either or both of these methods: