Install Apache Web Agent

Examples in this section use Apache and the Apache HTTP Server agent path. For IBM HTTP Servers, replace the Apache HTTP Server agent path, apache24_agent, with the IBM HTTP agent path, httpserver7_agent.

Consider the following points before you install:

By default, the agent replaces authentication functionality provided by Apache, for example, the mod_auth_* modules. To use built-in Apache authentication directives, such as AuthName, FilesMatch, and Require, for specified not-enforced URLs, configure Use Built-in Apache HTTPD Authentication Directives.
SELinux can prevent the web server from accessing agent libraries, and the agent from being able to write to audit and debug logs. See Troubleshooting.
By default, 32 agent instances can run at the same time in a single installation. For information about changing the limit, refer to AM_MAX_AGENTS in Environment variables.

Tune Apache multi-processing modules

The Apache HTTP Server and the IBM HTTP Server include Multi-Processing Modules (MPMs) that extend the basic functionality of a web server to support the wide variety of operating systems and customizations for a particular site.

Before installing the Apache Web Agent, configure and tune the MPMs, as follows:

Configure either the mpm-event or the mpm-worker modules for Unix-based servers, or the mpm_winnt module for Windows servers.

The prefork-mpm module may cause performance issues to both the agent and AM.
Ensure that there are enough processes and threads available to service the expected number of client requests.

MPM-related performance is configured in the conf/extra/http-mpm.conf file. The key properties in this file are ThreadsPerChild and MaxRequestWorkers. Together, these the properties control the maximum number of concurrent requests that can be processed by Apache. The default configuration allows for 150 concurrent clients spread across 6 processes of 25 threads each.
```
<IfModule mpm_worker_module>
StartServers            2
MaxRequestWorkers     150
MinSpareThreads        25
MaxSpareThreads        75
ThreadsPerChild        25
MaxConnectionsPerChild  0
</IfModule>
```
For agent notifications, MaxSpareThreads, ThreadLimit and ThreadsPerChild default values must not be altered; otherwise the notification queue listener thread cannot be registered.

Any other values apart from these three in the worker MPM can be customized. For example, it is possible to use a combination of MaxRequestWorkers and ServerLimit to achieve a high level of concurrent clients.

Install Apache Web Agent interactively

Review the information in Before you install, and perform the steps in Preinstallation tasks.
(Optional) In non-Centos or virtual host environments, where an Apache user is not defined in httpd.conf, add the option to change ownership of created directories. Set the following environment variables in your command line session:
- Linux
- Windows
$ export APACHE_RUN_USER=apache $ export APACHE_RUN_GROUP=apache
C:\>set APACHE RUN_USER=apache C:\>set APACHE RUN_GROUP=apache
For more information, refer to Installation environment variables
Shut down the server where you plan to install the agent.
Make sure AM is running.

Run agentadmin --i to install the agent:

Linux
Windows

$ cd /web_agents/apache24_agent/bin/
$ ./agentadmin --i

C:\> cd web_agents\apache24_agent\bin
C:\path\to\web_agents\apache24_agent\bin> agentadmin.exe --i

When prompted, enter information for your deployment.

To cancel the installation at any time, press CTRL-C.

Enter the complete path to the Apache configuration file. The installer modifies this file to include the agent configuration and module.

Enter the complete path to the httpd.conf file which is used by Apache HTTP
Server to store its configuration.
[ q or 'ctrl+c' to exit ]
Configuration file [/opt/apache/conf/httpd.conf]:/etc/httpd/conf/httpd.conf

When installing the agent as the root user, the agentadmin command can change the directory ownership to the same user and group specified in the Apache configuration.

If User and Group are not defined in httpd.conf, such as in non Red Hat Enterprise Linux-based distributions, this step appears only if environment variables are set as described in step 2.

Determine which user or group is running the Apache server by viewing the Group and User directives in httpd.conf.

Enter yes to change directory ownership; press Enter to accept the default, no.
```
Change ownership of created directories using
User and Group settings in httpd.conf
[ q or 'ctrl+c' to exit ]
(yes/no): [no]:yes
```
Failure to set permissions causes issues, such as the Apache HTTP Server not starting up, getting a blank page when accessing a protected resource, or the web agent generating errors during log file rotation.
Enter the full path to an existing agent configuration file to import the settings, or press Enter to skip the import.

The installer can import settings from an existing Web Agent on the new installation and skip prompts for values present in the existing configuration file. You are required to re-enter the agent profile password.
```
To set properties from an existing configuration enter path to file
[ q or 'ctrl+c' to exit, return to ignore ]
Existing agent.conf file:
```

Enter the full URL for the AM instance that the agent will use, including the deployment URI.

If a reverse proxy is configured between AM and the agent, set the AM URL to the proxy URL, for example, https://proxy.example.com:443/am. For information about setting up an environment for reverse proxies, refer to Configure Apache HTTP Server as a reverse proxy.

Enter the URL where the AM server is running. Please include the
deployment URI also as shown below:
(http://am.sample.com:58080/am)
[ q or 'ctrl+c' to exit ]
AM server URL:http://am.example.com:8080/am

Enter the full URL for the Agent.

Enter the Agent URL as shown below:
(http://agent.sample.com:1234)
[ q or 'ctrl+c' to exit ]
Agent URL:http://www.example.com:80

Enter the name of the agent profile created in AM.

Enter the Agent profile name
[ q or 'ctrl+c' to exit ]
Agent Profile name: web-agent

Enter the agent profile realm. Realms are case-sensitive.

Enter the Agent realm/organization
[ q or 'ctrl+c' to exit ]
Agent realm/organization name: [/]:/

Enter the full path to the file containing the agent profile password created earlier.

Enter the path to a file that contains the password to be used
for identifying the Agent
[ q or 'ctrl+c' to exit ]
The path to the password file:/secure-directory/pwd.txt

The installer displays a summary of the specified configuration settings.

If a setting is incorrect, type no, or press Enter. The installer loops through the configuration prompts again, using your provided settings as the default. Press Enter to accept each one, or enter a replacement setting.

If the settings are correct, type yes to proceed with installation.
```
Installation parameters:
   AM URL: http://am.example.com:8080/am
   Agent URL: http://www.example.com:80
   Agent Profile name: web-agent
   Agent realm/organization name: /
   Agent Profile password source: /secure-directory/pwd.txt

Confirm configuration (yes/no): [no]:yes
Validating…
Validating… Success.
Cleaning up validation data…
Creating configuration…
Installation complete.
```
On successful completion, the installer adds the agent as a module to the Apache configuration file, in this example, /etc/httpd/conf/httpd.conf.

The backup configuration file is in the configuration file with the installation datestamp: http.conf_amagent_yyyymmddhhmmss.

(Unix only) Ensure the user or group running the Apache HTTP server has the appropriate permissions on the following directories:
- Read permission: /web_agents/apache24_agent/lib
- Read and write permission:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
- Execute permission to validate an installation by using the agentadmin --V[i] command:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
To determine which user or group is running the Apache HTTP server, check the Group and User directives in the Apache HTTP server configuration file, httpd.conf. When permission are incorrect, the following errors can occur:
- Apache HTTP doesn’t start up
- Access to a protected resource returns a blank page
- The agent generates errors during log file rotation
  
  The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.
Start the Apache HTTP Server.
Check the installation, as described in Check the Apache Web Agent installation.

Install Apache Web Agent on a virtual host

Web Agent instances can be configured to operate with multiple virtual hosts in Apache. Each configuration instance is independent and has its own configuration file, debug logs, and audit logs. Each instance can connect to a different AM realm, or even different AM servers.

Complete the following procedures to install Web Agent 2023.6 on Apache virtual hosts.

Installing on an Apache virtual host is a manual process, which involves copying an instance directory created by the agentadmin installer and adding to the Apache configuration file of the virtual host.

Prepare for Web Agent installation on an Apache virtual host

Perform the following steps to create the configuration required to install a web agent on an Apache virtual host:

Install a web agent in the default root configuration of the Apache installation. For more information, refer to Install Apache Web Agent
Create an agent profile in AM. For more information, refer to Creating Agent Profiles.
Create at least one policy in AM to protect resources on the virtual host, as described in Policies in AM’s Authorization guide.

Install the Apache Web Agent on Apache virtual hosts

This procedure assumes you have installed a web agent on the default root configuration of your Apache installation, with configuration in /web_agents/apache24_agent/instances/agent_1.

To install on a virtual host, copy this configuration folder, modify required settings, and enable the web agent in the virtual host configuration file.

Review the information in Before you install, and perform the steps in Preinstallation tasks.
Shut down the Apache HTTP Server where you plan to install the agent.

Locate the web agent configuration instance to duplicate, and make a copy, for example agent_2:

Linux
Windows

$ cd /web_agents/apache24_agent/instances
$ cp -r agent_1 agent_2

c:\> cd c:\web_agents\apache24_agent\instances
c:\path\to\web_agents\apache24_agent\instances> xcopy /E /I agent_1 agent_2

Give the user that runs the virtual host modify privileges to the new instance folder. The following examples demonstrate giving privileges to the agent_2 configuration instance to a user named apache:
- Linux
- Windows example
$ cd /web_agents/apache24_agent/instances $ chown -hR apache agent_2
c:\> cd c:\web_agents\apache24_agent\instances c:\path\to\web_agents\apache24_agent\instances> **icacls "agent_2" /grant apache:M
In the new instance folder, edit the /config/agent.conf configuration file as follows:
1. Set the value of com.sun.identity.agents.config.username to name of the agent profile you created in AM for the virtual host.
2. Configure the virtual host’s web agent encryption key and password. Consider the following scenarios and choose the one that suits your environment best:
  - Scenario 1: The password of the virtual host’s agent profile is the same as the password of the Apache root’s agent profilefootnote:[
    
    The Apache root’s profile refers to the web agent installation you performed as part of the prerequisites to install web agents on virtual hosts.].
    
    The encryption key and encryption password of the Apache root’s agent and the virtual host’s agent must match. Because you copied the configuration file, you do not need to perform any additional action.
  - Scenario 2: The password of the virtual host’s agent profile is different from the password of the Apache root’s agent profile.(The Apache root’s profile refers to the web agent installation you performed as part of the prerequisites to install web agents on virtual hosts.)
    
    You need to generate a new encryption key and encrypt the new password before configuring them in the virtual host’s agent profile. Perform the following steps:
    
    Generate a new encryption key by running the agentadmin command with the --k option. For example:
    
    $ agentadmin --k Encryption key value: YWM…5Nw==
    
    Unix users only: Store the agent profile password in a file, for example, newpassword.file .
    
    Encrypt the agent’s profile password with the encryption key by running the agentadmin command with the --p option.
    
    Linux
    
    Windows
    
    $ ./agentadmin --p "YWM…5Nw==" “cat newpassword.file” Encrypted password value: 07b…dO4=
    
    $ agentadmin.exe --p "YWM…5Nw==" "newpassword" Encrypted password value: 07b…dO4=
    
    In the virtual host’s agent.conf file, set the following properties:
    
    com.sun.identity.agents.config.key. Its value is the generated encryption key. For example:
    
    com.sun.identity.agents.config.key = YWM...5Nw==
    
    com.sun.identity.agents.config.password. Its value is the encrypted password. For example:
    
    com.sun.identity.agents.config.password = 07b...dO4=
3. Replace any references to the original instance directory with the new instance directory. For example, replace the string agent_1 with agent_2 wherever it occurs in the configuration file.
  
  Configuration options that are likely to require changes include:
  - Local Agent Debug File Name
  - Local Agent Audit File Name
4. Replace any references to the original website being protected with the new website being protected. For example, replace http://www.example.com:80/amagent with http://customers.example.com:80/amagent.
  
  Configuration options that are likely to require changes include:
  - Agent Deployment URI Prefix
  - FQDN Default
5. Save and close the configuration file.
Edit the Apache configuration file. This is the same file specified when installing the web agent on the default Apache website. For example, /etc/httpd/conf/httpd.conf.
1. At the end of the file the installer will have added three new lines of settings, for example:
  LoadModule amagent_module /web_agents/apache24_agent/lib/mod_openam.so AmAgent On AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_1/config/agent.conf
  Leave the first line, LoadModule …, and move the other two lines on the virtual host configuration element of the default site, for example:
  <VirtualHost *:80> # This first-listed virtual host is also the default for *:80 ServerName www.example.com ServerAlias example.com DocumentRoot "/var/www/html" AmAgent On AmAgentConf /web_agents/apache24_agent/instances/agent_1/config/agent.conf </VirtualHost>
2. Copy the same two lines on the new virtual host, and replace agent_1 with the new agent configuration instance folder, for example agent_2:
  <VirtualHost *:80> ServerName customers.example.com DocumentRoot "/var/www/customers" AmAgent On AmAgentConf /web_agents/apache24_agent/instances/agent_2/config/agent.conf </VirtualHost>
  If the new virtual host configuration is in a separate file, copy the two configuration lines on the VirtualHost element within that file.
Save and close the Apache configuration file.
(Unix only) Ensure the user or group running the Apache HTTP server has the appropriate permissions on the following directories:
- Read permission: /web_agents/apache24_agent/lib
- Read and write permission:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
- Execute permission to validate an installation by using the agentadmin --V[i] command:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
To determine which user or group is running the Apache HTTP server, check the Group and User directives in the Apache HTTP server configuration file, httpd.conf. When permission are incorrect, the following errors can occur:
- Apache HTTP doesn’t start up
- Access to a protected resource returns a blank page
- The agent generates errors during log file rotation
  
  The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.
Start the Apache HTTP Server.
Check the installation, as described in Check the Apache Web Agent Installation.

Install Apache Web Agent silently

Use the agentadmin --s command for silent installation. For information about the options, refer to agentadmin command.

Review the information in Before you install, and perform the steps in Preinstallation tasks.
Shut down the Apache HTTP Server where you plan to install the agent.
Make sure AM is running.

Run the agentadmin --s command with the required arguments. For example:

$ sudo agentadmin --s \
  "/etc/httpd/conf/httpd.conf" \
  "http://am.example.com:8080/am" \
  "http://www.example.com:80" \
  "/" \
  "webagent4" \
  "/secure-directory/pwd.txt" \
  --changeOwner \
  --acceptLicence
Web Agent for Apache Server installation.

Validating…
Validating… Success.
Cleaning up validation data…
Creating configuration…
Installation complete.

(Unix only) Ensure the user or group running the Apache HTTP server has the appropriate permissions on the following directories:
- Read permission: /web_agents/apache24_agent/lib
- Read and write permission:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
- Execute permission to validate an installation by using the agentadmin --V[i] command:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
To determine which user or group is running the Apache HTTP server, check the Group and User directives in the Apache HTTP server configuration file, httpd.conf. When permission are incorrect, the following errors can occur:
- Apache HTTP doesn’t start up
- Access to a protected resource returns a blank page
- The agent generates errors during log file rotation
  
  The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.
Start the Apache HTTP Server.
Check the installation, as described in Check the Apache Web Agent Installation.

Check the Apache Web Agent installation

After you start Apache HTTP Server, check the error log to make sure startup completed successfully:

[Tue Sep …] AH00163:
Apache/2.4.6 (CentOS) Web Agent/2023.6 configured — resuming normal operations

Make an HTTP request to a resource protected by the agent, then check the /web_agents/apache24_agent/log/system_0.log file to verify that no errors occurred on startup. The log should contain a message similar to this:
```
[0x7fb89e7a6700:22]: Web Agent Version: 2023.6
Revision: ab12cde, Container: Apache 2.4 Linux 64bit (Centos6),
Build date: Mar …
```
(Optional) If you have a policy configured, test that the agent is processing requests. For example, make an HTTP request to a resource protected by the agent, and check that you are redirected to {am.abbr} to authenticate. After authentication, AM redirects you back to the resource you tried to access.

Install in a subrealm

Examples in this document install the agent in the top-level realm. To install the agent in a subrealm during interactive or silent installation, use the subrealm during the installation or in the response file.

For example, instead of:

Agent realm/organization name: [/]: /

specify:

Agent realm/organization name: [/]: /myrealm

Even though the agent is installed in a subrealm, the default login redirect requires the user realm to be the top-level realm. For information about how to change the user realm, refer to Login redirect.

Configure error logs

Edit the Apache HTTP server configuration file httpd.conf to cause the agent error logs to appear in the Apache log system.

The following line, present by default in httpd.conf, logs warning conditions for the container:

LogLevel warn

The following example line includes the agent error logs at debug-level:

LogLevel warn amagent:debug

Web Policy Agents 2023.6

Install Apache Web Agent

Tune Apache multi-processing modules

Install Apache Web Agent interactively

Install Apache Web Agent on a virtual host

Install Apache Web Agent silently

Check the Apache Web Agent installation

Install in a subrealm

Configure error logs