Untitled | Web Agents

Installation

Product names changed when ForgeRock became part of Ping Identity. Learn more about the name changes from New names for ForgeRock products.

This guide describes how to install Web Agent.

Example installation for this guide

Unless otherwise stated, the examples in this guide assume the following installation:

Web Agent installed on https://agent.example.com:443.
AM installed on https://am.example.com:8443/am.
Work in the top-level realm /.

If you use a different configuration, substitute in the procedures accordingly.

Prepare for installation

Before you install

Consider the following points before you install:

Install AM and Web Agent in different servers.
Make sure AM is running, so that you can contact AM from the agent web server.
Install the web server before you install the agent.
Install only one Web Agent for each web server, and configure as many agent instances as necessary.
For environments with load balancers or reverse proxies, consider the communication between the agent and AM servers, and between the agent and the client. Configure both AM and the environment before you install the agent. Learn more from Configure load balancers and reverse proxies.

Download and unzip Web Agent

Go to the BackStage download site and download an agent based on your architecture, and operating system requirements. Verify the checksum of the downloaded file against the checksum posted on the download page.

Unzip the file in the directory where you plan to store the agent configuration and log files. The following directories are extracted:

Directory Description

bin/

The installation and configuration program agentadmin.

config/

Configuration templates used by the agentadmin command during installation.

instances/

Configuration files, and audit and debug logs for individual instances of the agents. The directory is empty when first extracted.

Make sure the directory path, including the parent path, doesn’t exceed 260 characters.

legal/

Licensing information including third-party licenses.

lib/

Shared libraries used by the agent.

log/

Log files written during installation. The directory is empty when first extracted.

When the agent is running, the directory can contain the following files:

The system_n.log file, where the agent logs information related to agent tasks running in the background. Web Agent timestamps events in coordinated universal time (UTC).
(IIS and ISAPI agents only) The backup of the site and application configuration files created after running the agentadmin -g command.
(IIS and ISAPI agents only) Files related to the agent caches.

pdp-cache/

POST data preservation cache. The agent stores POST data preservation files temporarily. To change the directory, configure POST Data Storage Directory.

Pre-installation tasks

In AM, add an agent profile as described in Create agent profiles. The example in this guide uses an agent profile in the top-level realm, with the following values:
- Agent ID: web-agent
- Agent URL: http://www.example.com:80
- Server URL: https://am.example.com:8443/am
- Password: password

In AM, add a policy set and policy as described in Policies in AM’s Authorization guide. The example in this guide uses a policy set and policy in the top-level realm, with the following values:

Policy set:
- Name: PEP
- Resource Types: URL
Policy:
- Name: PEP-policy
- Resource Type: URL
- Resource pattern: *://*:*/*
- Resource value: *://*:*/*
- Actions tab: Allow HTTP GET and POST
- Subjects tab: All Authenticated Users.

When you use your own policy set instead of the default policy set, iPlanetAMWebAgentService, update the following properties in the agent profile:

Configure AM to protect the CDSSO cookie from hijacking. For more information, refer to Restrict tokens for CDSSO session cookies in AM’s Security guide.

Create a text file for the agent password, and protect it. For example, use commands similar to these, but use a strong password and store it in a secure place:

Unix
Windows

$ cat > /secure-directory/pwd.txt
password
CTRL+D

$ chmod 400 /secure-directory/pwd.txt

C:> type > pwd.txt
password
CTRL+Z

In Windows Explorer, right-click the password file, select Read-Only, and then click OK.

Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example, by using a password manager.

If either of the following is true, set up the required environment variables:
- AM is configured to perform client authentication
- The agent web server is configured to validate AM’s server certificate
Learn more from Environment variables.

Create agent profiles

Use Web Agent profiles to connect to and communicate with AM.

Create an agent profile for a single agent instance

This section describes how to create an agent profile in the AM admin UI. Alternatively, create agent profiles by using the /realm-config/agents/WebAgent/{id} endpoint in the REST API. Learn more from REST API explorer in AM’s Getting started with REST.

In the AM admin UI, select Realms > Realm Name > Applications > Agents > Web, and add an agent using the following hints:

Agent ID

The ID of the agent profile. This ID resembles a username in AM and is used during the agent installation. For example, MyAgent.

When AM is not available, the related error message contains the agent profile name. Consider this in your choice of agent profile name.

Agent URL

The URL where the agent resides. Learn more from Example installation for this guide.

In centralized configuration mode, the Agent URL populates the agent profile for services, such as notifications.

Server URL

The full URL to an authorization server, such as PingOne Advanced Identity Cloud or AM. Learn more from Example installation for this guide.

If the authorization server is deployed in a site configuration (behind a load balancer), enter the site URL.

In centralized configuration mode, the Server URL populates the agent profile for use with login, logout, naming, and cross-domain SSO.

Password

The password the agent uses to authenticate to an authorization server, such as PingOne Advanced Identity Cloud or AM. Use this password when installing an agent.

Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example, by using a password manager.

(Optional - From AM 7.5) Use AM’s secret service to manage the agent profile password. If AM finds a matching secret in a secret store, it uses that secret instead of the agent password configured in Step 1.
1. In the agent profile page, set a label for the agent password in Secret Label Identifier.
  
  AM uses the identifier to generate a secret label for the agent.
  
  The secret label has the format am.application.agents.identifier.secret, where identifier is the Secret Label Identifier.
  
  The Secret Label Identifier can contain only characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.
2. Select Secret Stores and configure a secret store.
3. Map the label to the secret. Learn more from AM’s Map and rotate secrets.
Note the following points for using AM’s secret service:
- Set a Secret Label Identifier that clearly identifies the agent.
- If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier provided no other agent shares the mapping.
- When you rotate a secret, update the corresponding mapping.

Create an agent profile for multiple agent instances when post data preservation is enabled

By default, the POST data preservation load balancer cookie name and value is set by the agent profile. Therefore, each agent instance behind a load balancer requires its own agent profile.

In scalable environments, such as deployments with load balancing, or environments that run Kubernetes, resources are dynamically created and destroyed.

To facilitate the rapid creation and destruction of agent instances when post data preservation is enabled, set the POST data preservation configuration in AgentConfiguration.properties to map one agent profile to multiple agent instances.

The configuration in AgentConfiguration.properties overrides the configuration in AM for the following properties:

For an example, refer to Map one agent profile to multiple agent instances when POST data preservation is enabled.

Create an agent profile group

Use agent profile groups when you set up multiple agents, and want to inherit settings from the group.

In the AM admin UI, go to Realms > Realm Name > Applications > Agents > Web.
Select the Groups tab, and add a group with the following settings:
- Group ID: A name for the profile group.
- Server URL: The URL of the AM server in which to store the profile.

Inherit properties from an agent profile group

Set up an agent profile and agent profile group, as described in Create an agent profile for a single agent instance and Create an agent profile group.
In the AM admin UI, select your agent profile.
On the Global tab, select Group, and select a group from the drop-down menu. The agent profile is added to the group.
For each setting in the Global tab, select or deselect the icon:
- : Inherit this setting from the group
- : Do not inherit this setting from the group

Authenticate agents to the identity provider

Authenticate agents to Advanced Identity Cloud

Web Agent is automatically authenticated to Advanced Identity Cloud by a non-configurable authentication module. Authentication chains and modules are deprecated in Advanced Identity Cloud and replaced by journeys.

You can now authenticate Web Agent to Advanced Identity Cloud with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release of Advanced Identity Cloud.

Learn more from Advanced Identity Cloud’s Journeys.

This section describes how to create a journey to authenticate Web Agent to Advanced Identity Cloud. The journey has the following requirements:

It must be called Agent
Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a journey in Advanced Identity Cloud, that same journey is used for all instances of PingGateway, Java Agent, and Web Agent. Consider this point if you change the journey configuration.

Log in to the Advanced Identity Cloud admin UI as an administrator.
Click Journeys > New Journey.
Add a journey with the following information and click Create journey:
- Name: Agent
- Identity Object: The user or device to authenticate.
- (Optional) Description: Authenticate an agent to Advanced Identity Cloud
The journey designer is displayed, with the Start entry point connected to the Failure exit point, and a Success node.
Using the Filter nodes bar, find and then drag the following nodes from the Components panel into the designer area:
- Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request and use their values in the following nodes.
  
  This node is required for compatibility with Java agent and Web agent.
- Page node to collect the agent credentials if they are not provided in the incoming authentication request and use their values in the following nodes.
- Agent Data Store Decision node to verify that the agent credentials match the registered Web Agent agent profile.
Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes and use only the default values.
Drag the following nodes from the Components panel into the Page node:
- Platform Username node
- Platform Password node
Connect the nodes as follows and save the journey:

Authenticate agents to AM

From AM 7.3: When AM 7.3 is installed with a default configuration, as described in Evaluation, Web Agent is automatically authenticated to AM by an authentication tree. Otherwise, Web Agent is authenticated to AM by an AM authentication module.

Authentication chains and modules were deprecated in AM 7. When they are removed in a future release of AM, it will be necessary to configure an appropriate authentication tree when you are not using the default configuration.

Learn more from AM’s Authentication Nodes and Trees.

This section describes how to create an authentication tree to authenticate Web Agent to AM. The tree has the following requirements:

It must be called Agent
Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a tree in AM, that same tree is used for all instances of PingGateway, Java Agent, and Web Agent. Consider this point if you change the tree configuration.

On the Realms page of the AM admin UI, choose the realm in which to create the authentication tree.
On the Realm Overview page, click Authentication > Trees > Create tree.

Create a tree named Agent.

The authentication tree designer is displayed, with the Start entry point connected to the Failure exit point, and a Success node.

The authentication tree designer provides the following features on the toolbar:

Button Usage

Button	Usage
	Lay out and align nodes according to the order they are connected.
	Toggle the designer window between normal and full-screen layout.
	Remove the selected node. Note that the `Start` entry point cannot be deleted.

Lay out and align nodes according to the order they are connected.

Toggle the designer window between normal and full-screen layout.

Remove the selected node. Note that the Start entry point cannot be deleted.

Using the Filter bar, find and then drag the following nodes from the Components panel into the designer area:
- Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request and use their values in the following nodes.
  
  This node is required for compatibility with Java agent and Web agent.
- Page node to collect the agent credentials if they are not provided in the incoming authentication request and use their values in the following nodes.
- Agent Data Store Decision node to verify that the agent credentials match the registered Web Agent profile.
Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes and use only the default values.
Drag the following nodes from the Components panel into the Page node:
- Username Collector node, to prompt the user to enter their username
- Password Collector node,to prompt the user to enter their password
Connect the nodes as follows and save the tree:

Apache and IBM HTTP Web Agent

Install Apache or IBM HTTP Web Agent

Consider the following points before installing Apache or IBM HTTP Web Agent:

SELinux can prevent the web server from accessing agent libraries, and the agent from being able to write to audit and debug logs. For more information, refer to Troubleshoot.
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.
(For Apache Web Agent) By default, the agent replaces authentication functionality provided by Apache, for example, the mod_auth_* modules. Configure Use Built-in Apache HTTPD Authentication Directives to use built-in Apache authentication directives such as AuthName, FilesMatch, and Require for specified not-enforced URLs.

Tune multi-processing modules

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

Before installation, configure and tune MPMs, as follows:

Configure one of the following modules:
- mpm-event for Unix-based servers
- mpm-worker for Unix-based servers
- mpm_winnt for Windows servers
The prefork-mpm module isn’t adapted to high-traffic deployments. It can cause performance issues to both the agent and AM.
Make sure that there are enough processes and threads available to service the expected number of client requests.

MPM-related performance is configured in the file conf/extra/http-mpm.conf:
```
<IfModule mpm_worker_module>
StartServers            2
MaxRequestWorkers     150
MinSpareThreads        25
MaxSpareThreads        75
ThreadsPerChild        25
MaxConnectionsPerChild  0
</IfModule>
```
MaxRequestWorkers and ThreadsPerChild control the maximum number of concurrent requests. The default configuration allows 150 concurrent clients across 6 processes of 25 threads each.

Configure MaxRequestWorkers and ServerLimit to get a high level of concurrent clients.

To prevent problems registering the notification queue listener, don’t change the default value of MaxSpareThreads, ThreadLimit, or ThreadsPerChild.

For information about Apache configuration properties, refer to Apache MPM worker.

Install interactively

Review the information in Before you install, and perform the steps in Preinstallation tasks.
(Optional) In environments where a user isn’t defined in the Apache or IBM HTTP server configuration file httpd.conf, set the following environment variables in your command line session to change ownership of created directories.

The following examples change ownership to the user user:
```
$ export APACHE_RUN_USER=user
$ export APACHE_RUN_GROUP=user
```
Learn more from Installation environment variables
Shut down the Apache or IBM HTTP server where you plan to install the agent.
Make sure AM is running.

Run agentadmin --i to install the agent:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

$ 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

$ cd /web_agents/httpservern_agent/bin/
$ ./agentadmin --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 or IBM HTTP server configuration file:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

Configuration file [/opt/apache/conf/httpd.conf]: /etc/httpd/conf/httpd.conf

Configuration file [/opt/apache/conf/httpd.conf]: /etc/httpd/conf/httpd.conf

Configuration file [/opt/apache/conf/httpd.conf]: /opt/IBM/HTTPServer/conf/httpd.conf

(Optional) When installing the agent as the root user, consider changing directory ownership to the same user and group specified in the server configuration:
```
Change ownership of created directories using
User and Group settings in httpd.conf
[ q or 'ctrl+c' to exit ]
(yes/no): [no]: yes
```
This step appears only if environment variables are set as described in step 2, and User and Group are not defined in httpd.conf, such as in non Red Hat Enterprise Linux-based distributions.

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

The following errors can occur when the permissions are wrong:
- Server fails to start up
- Requests to a protected resource return a blank page
- Log rotation errors
Enter the full path to import an existing agent configuration file, or press Enter to skip the import.
```
Existing agent.conf file: path/to/config/agent.conf
```
The installer can import settings from an existing agent on the new installation and skip prompts for values present in the existing configuration file. You must re-enter the agent profile password.

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

AM server URL: http://am.example.com:8088/am

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 Apache as a reverse proxy.

Enter the full URL of the agent:
```
Agent URL: http://www.example.com:80
```
Enter the ID of the agent profile created in AM:
```
Agent ID: web-agent
```
Enter the agent profile realm:
```
Agent realm/organization name: [/]:  / 
```
Realms are case-sensitive.

Enter the full path to the file containing the agent password:

The path and name of the password file: /secure-directory/pwd.txt

Review the configuration:

Installation parameters:
   AM URL: https://am.example.com:8443/am
   Agent URL: http://www.example.com:80
   Agent ID: web-agent
   Agent realm/organization name: /
   Agent password source: /secure-directory/pwd.txt

Confirm configuration (yes/no): [no]:

Accept or update the configuration:
- To accept the configuration type yes.
- To change the configuration 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.
On successful completion, the installer adds the agent as a module to the server configuration file httpd.conf. The agent adds a backup configuration file with the installation datestamp: http.conf_amagent_yyyymmddhhmmss.

(Unix only) Make sure the user or group running the Apache or IBM HTTP server has appropriate permissions for the following directories:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Read permission:
* /web_agents/httpservern_agent/lib

Read and write permission:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

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

The following errors can occur when the permissions are wrong:

Server fails to start up
Requests to a protected resource return a blank page
Log rotation errors

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

Start the Apache or IBM HTTP server.
Check the installation, as described in Check the installation.

Install on a virtual host

Web Agent instances can operate with multiple virtual hosts. 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.

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

Install an agent in the default root configuration, as described in Install Apache or IBM HTTP Web Agent. This agent is referred to as the root agent.
Create a profile for the agent on the virtual host, as described in Create agent profiles. This agent is referred to as the virtual host agent.
Create at least one AM policy to protect resources on the virtual host, as described in Policies in AM’s Authorization guide.
Shut down the Apache or IBM HTTP server where you plan to install the agent.

Locate an agent configuration instance to duplicate, and make a copy. For example, copy agent_1 to agent_2:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

$ 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

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

Assign modify privileges to the new instance folder for the user that runs the virtual host. The following examples assign privileges for agent_2 to a user named user:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

$ cd /web_agents/apache24_agent/instances
$ chown -hR user agent_2

c:\> cd c:\web_agents\apache24_agent\instances
c:\path\to\web_agents\apache24_agent\instances> **icacls "agent_2" /grant user:M

$ cd /web_agents/httpservern_agent/instances
$ chown -hR user agent_2

In the new instance folder, edit the configuration as follows:
1. In AgentConfiguration.properties, set the value of Agent Profile Name to the name of the profile you created for the virtual host agent. For example, set the value to agent_2.
2. In agent-password.conf and agent-key.conf, configure the encryption key and password for the virtual host agent. Use a scenario that suits your environment:
  - Scenario 1: The password of the virtual host agent profile is the same as the password of the root agent profile^[1].
    
    The encryption key and encryption password of the root agent and virtual host agent must match. Because you copied the configuration file, you don’t need to do anything else.
  - Scenario 2: The password of the virtual host agent profile is different from the password of the root agent profile^[2].
    
    Follow these steps to generate a new encryption key, encrypt the new password, and configure them in the profile of the virtual host agent:
    
    Generate a new encryption key:
    
    $ agentadmin --k Encryption key value: YWM…5Nw==
    
    (Unix only) Store the agent profile password in a file, for example, newpassword.file .
    
    Encrypt the agent profile password:
    
    Apache on Linux
    
    Apache on Windows
    
    IBM HTTP Server on Linux
    
    $ ./agentadmin --p "YWM…5Nw==" “cat newpassword.file” Encrypted password value: 07b…dO4=
    
    $ agentadmin.exe --p "YWM…5Nw==" "newpassword" Encrypted password value: 07b…dO4=
    
    $ ./agentadmin --p "YWM…5Nw==" “cat newpassword.file” Encrypted password value: 07b…dO4=
    
    Set the following property in agent-key.conf:
  - Agent Profile Password Encryption Key with the value of the generated encryption key:
    
    com.sun.identity.agents.config.key = YWM...5Nw==
    
    Set the following property in agent-password.conf:
  - Agent Profile Password with the value of the encrypted password:
    
    com.sun.identity.agents.config.password = 07b...dO4=
3. Throughout the configuration, replace references to the original instance directory with the new instance directory. For example, replace agent_1 with agent_2 in the following properties:
  - Local Agent Debug File Name
  - Local Agent Audit File Name
4. Throughout the configuration, replace 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 in the following properties:
  - Agent Deployment URI Prefix
  - FQDN Default
Edit the Apache or IBM HTTP server configuration file, httpd.conf:
1. Find the following lines at the end of the file. The following example is for Apache agent on Linux, but you can adapt it to your configuration:
  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
2. 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>
3. 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 configuration file.

(Unix only) Make sure the user or group running the Apache or IBM HTTP server has appropriate permissions for the following directories:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Read permission:
* /web_agents/httpservern_agent/lib

Read and write permission:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

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

The following errors can occur when the permissions are wrong:

Server fails to start up
Requests to a protected resource return a blank page
Log rotation errors

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

Start the Apache or IBM HTTP server.
Check the installation, as described in Check the installation.

Install 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 or IBM HTTP server where you plan to install the agent.
Make sure AM is running.

Run the agentadmin --s command with the required arguments. The following example is for Apache agent on Linux, but you can adapt it to your configuration:

$ ./agentadmin --s \
  "/etc/httpd/conf/httpd.conf" \
  "https://am.example.com:8443/am" \
  "http://www.example.com:80" \
  "/" \
  "webagent" \
  "/secure-directory/pwd.txt" \
  --changeOwner
AM Web Agent for Apache Server installation.
…
Installation complete.

(Unix only) Make sure the user or group running the Apache or IBM HTTP server has appropriate permissions for the following directories:

Apache on Linux
Apache on Windows
IBM HTTP Server on Linux

Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Read permission:
* /web_agents/httpservern_agent/lib

Read and write permission:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

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

The following errors can occur when the permissions are wrong:

Server fails to start up
Requests to a protected resource return a blank page
Log rotation errors

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

Start the Apache or IBM HTTP server.
Check the installation, as described in Check the installation.

Check the installation

After you start Apache or IBM HTTP server, check the error log to make sure startup was successful:

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

Make an HTTP request to a resource protected by the agent, then check the /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: 2024.6
Revision: ab12cde, Container: Apache 2.4 Linux 64bit (Centos6),
Build date: Mar …
```
(Optional) If an AM policy is configured, test that the agent enforces a policy decision. For example, make an HTTP request to a protected resource and check that you are redirected to AM 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 server configuration file httpd.conf to log errors.

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

Configure Apache or IBM HTTP Web Agent

The examples in this section are for Apache agent on Linux, but you can adapt them to your configuration.

IBM HTTP server 9 supports Apache directives; IBM HTTP server 8,5 does not.

`AmAgent` directive to switch the agent on or off

Switch the agent on or off globally or independently for different server locations. Server locations include the global environment, a virtual host, a specific location, or a set of directory blocks. Use the following settings:

AmAgent On: The agent protects server locations. It allows or denies requests based on AM policy configuration and not-enforced rules.
AmAgent Off: Apache or IBM HTTP server protects server locations; the agent plays no part in protecting the server locations.

Default: AmAgent is set to On at a global level in the httpd.conf configuration file as follows:

AmAgent On
AmAgentConf /opt/web_agents/apache24_agent/instances/agent_1/config/agent.conf
AmAuthProvider Off

The AmAgent configuration is hierarchical; when it is On or Off globally it is set for all server locations except those explicitly specified otherwise.

Consider setting AmAgent to Off for the following situations:

For server locations that need no AM authentication or policy, such as the public face of a website, or /css or /images directories.
When Apache or IBM HTTP server is acting as a reverse proxy to AM or Advanced Identity Cloud, and you don’t want the agent to take part in protecting AM or Advanced Identity Cloud.

Example where `AmAgent` is `On` globally and `Off` for specific directories

In the following example httpd.conf, the agent is On globally and Off for the /var/www/transaction directory:

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

<Directory /var/www/transaction>
    AmAgent Off
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

AmAgent On
AmAgentConf /opt/web_agents/apache24_agent/instances/agent_1/config/agent.conf
AmAuthProvider Off

Accessing a resource in /var/www/: The agent protects the resource, and overrides the Require all granted directive.

To access the resource, the request must match a not-enforced rule in the agent configuration or be allowed by an AM policy evaluation.
Accessing a resource in /var/www/transaction: Apache or IBM HTTP server manages the access and applies the Require all granted directive. The agent plays no part in protecting the resource.

`AmAgent` is `Off` globally and `On` for specific server locations

When AmAgent configuration is Off, configure the server location /agent as On. This allows AM to redirect requests to the /agent endpoint after authentication.

In the following example httpd.conf, the agent is Off globally but On for the /var/www/transaction and /agent locations:

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

<Directory /var/www/transaction>
    AmAgent On
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

<Location /agent>
    AmAgent On
</Location>

AmAgent Off
AmAgentConf /opt/web_agents/apache24_agent/instances/agent_1/config/agent.conf
AmAuthProvider Off

Accessing a resource in /var/www/: Apache or IBM HTTP server manages the access and applies the Require all granted directive.The agent plays no part in protecting the resource.
Accessing a resource in /var/www/transaction: The agent protects the resource, and overrides the Require all granted directive.

To access the resource, the request must match a not-enforced rule in the agent configuration or be allowed by an AM policy evaluation.

`AmAuthProvider` directive to use Apache as the enforcement point

When AmAgent is On, combine AM policy with Apache Require directives to control access globally or independently for different server locations. Server locations include the global environment, a virtual host, a specific location, or a set of directory blocks.

Using multiple authorization sources increases complexity. To reduce the risk of an invalid security configuration, test and validate the directives.

Use the following settings:

AmAuthProvider Off: The agent acts as the enforcement point, allowing or denying requests based on not-enforced rules and AM policies.
AmAuthProvider On: Apache or IBM HTTP server acts as the enforcement point, allowing or denying requests based on AM policy and Apache Require directives

For information about Require directives, refer to Require Directive on the Apache website. Require AmAuth is a directive specifically for Web Agent. When the directive is specified, users must be authenticated with AM. Otherwise, the agent redirects them to AM for authentication.

Default: AmAuthProvider is Off

The AmAuthProvider configuration is hierarchical; when it is On or Off globally it is set for all server locations except those explicitly specified otherwise.

For simplicity, it is recommended to leave AmAuthProvider as Off globally and set it to On for specific locations where you want Apache to act as the enforcement point.

When `AmAuthProvider` is `On` and the request doesn’t match a not-enforced rule

When a request doesn’t match a not-enforced rule, the agent does the following:

Checks that the user is authenticated with AM, and redirects the user for authentication if not.
Requests policy information from AM for the request.
Relays the policy information to the Apache Require AmAuth directive.

Apache or IBM HTTP server uses the Require AmAuth directive and other Require directives to allow or deny access to resources.

The following image shows the flow of requests:

When `AmAuthProvider` is `On` and the request matches a not-enforced rule

When a request matches a not-enforced rule, the agent does not require the user to be authenticated with AM or request policy information from AM. The Require AmAuth directive returns a neutral value.

Apache or IBM HTTP server uses the other Require directives to allow or deny access to resources.

The following image shows the flow of requests:

Consider the following points for using not-enforced rules when AmAuthProvider is On:

Instead of using not-enforced rules to provide caveats to AM policy enforcement, use Apache Require directives.
In server locations where the agent is configured with not-enforced rules, set AmAuthProvider to Off to let the agent do the enforcement.
If you use not-enforced rules when AmAuthProvider is On, remember that the agent drops out of authorisation decisions for requests that match a rule. Apache Require directives are used to allow or deny requests.

When `AmAuthProvider` is `On` and `Require AmAuth` is not specified

When AmAuthProvider is On, the Require AmAuth directive should always be specified. If AmAuthProvider is On but the Require AmAuth directive is not specified, users are still required to authenticate with AM but Apache does not use policy information from AM in its decision.

The following image shows the flow of requests:

The following example has this configuration:

The request doesn’t match a not-enforced rule.
AmAuthProvider is On for the /var/www/transaction directory.
Require AmAuth is not specified

//Not a recommended configuration

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

<Directory /var/www/transaction>
    AmAuthProvider On
    Options Indexes FollowSymLinks
    AllowOverride None
    <RequireAll>
        Require ip 19.168.2
    </RequireAll>
</Directory>

AmAgent On
AmAgentConf /opt/web_agents/apache24_agent/instances/agent_1/config/agent.conf
AmAuthProvider Off

Accessing a resource in /var/www/transaction: Apache or IBM HTTP server uses the Require ip directive to allow or deny the request. The user must be authenticated with AM and a valid user must be set, but AM policy information is ignored.

Example where `AmAuthProvider` is `Off` globally and `On` for specific directories

The example is configured as follows:

The request doesn’t match a not-enforced rule
AmAuthProvider is Off globally
AmAuthProvider is On for the /var/www/transaction directory:
Require AmAuth is specified

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

<Directory /var/www/transaction>
    AmAuthProvider On
    Options Indexes FollowSymLinks
    AllowOverride None
    <RequireAll>
        Require AmAuth
        Require ip 19.168.2
    </RequireAll>
</Directory>

AmAgent On
AmAgentConf /opt/web_agents/apache24_agent/instances/agent_1/config/agent.conf
AmAuthProvider Off

Accessing a resource in /var/www/: The agent acts as the enforcement point, allowing or denying requests based on not-enforced rules and AM policies.
Accessing a resource in /var/www/transaction: The agent provides AM policy information to the Require AmAuth directive. Apache uses that and the Require ip directive to allow or deny the request.

To access the resource, the user must be authenticated with AM, and the request must meet AM policy requirements and come from the specified IP address.

Apache as a reverse proxy

This section has an example configuration of Apache HTTP Server as a reverse proxy between AM and Web Agent. You can use any reverse proxy that supports the WebSocket protocol.

For information about how to configure Apache for load balancing, and other requirements for your environment, refer to the Apache documentation.

Simplified diagram showing an Apache HTTP Server configured as a reverse proxy between AM and the agent.

Figure 1. Apache HTTP Server reverse proxy configured between the agent and AM

Locate the httpd.conf file in your deployed reverse proxy instance.

Add the modules required for a proxy configuration, as follows:

# Modules required for proxy
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

The mod_proxy_wstunnel.so module is required to support the WebSocket protocol used for communication between AM and the agents.

Add the proxy configuration inside the VirtualHost context. Consider the following directives:
```
<VirtualHost 192.168.1.1>
...
# Proxy Config
RequestHeader set X-Forwarded-Proto "https" (1)
ProxyPass "/am/notifications" "ws://am.example.com:8080/am/notifications" Upgrade=websocket (2)
ProxyPass "/am" "http://am.example.com:8080/am" (3)
ProxyPassReverseCookieDomain "am.internal.example.com" "proxy.example.com" (4)
ProxyPassReverse "/am" "http://am.example.com:8080/am" (5)
...
</VirtualHost>
```
⁽¹⁾ RequestHeader: Set to https or http, depending on the proxy configuration. If the proxy is configured for https, as in the above example, set to https. Otherwise, set http. In a later step, you configure AM to recognize the forwarded header and use it in the goto parameter for redirecting back to the agent after authentication.

⁽²⁾ ProxyPass: Set to allow WebSocket traffic between AM and the agent. If HTTPS is configured between the proxy and AM, set to use the wss protocol instead of ws.

⁽³⁾ ProxyPass: Set to allow HTTP traffic between AM and the agent.

⁽⁴⁾ ProxyPassReverseCookieDomain: Set to rewrite the domain string in `Set-Cookie`headers in the format internal domain (AM’s domain) public domain (proxy’s domain).

⁽⁵⁾ ProxyPassReverse: Set to the same value configured for the ProxyPass directive.

For more information about configuring Apache HTTP Server as a reverse proxy, refer to the Apache documentation.
Restart the reverse proxy instance.
Configure AM to recover the forwarded header you configured in the reverse proxy. Also, review other configurations that may be required in an environment that uses reverse proxies. Learn more from Agent connection to AM through a load balancer/reverse proxy

IIS and ISAPI Web Agent

IIS and ISAPI Web Agent instances can be configured to operate with multiple websites. 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.

Consider the following points for IIS and ISAPI Web Agent:

IIS agents must run in Integrated mode.
IIS and ISAPI agents can’t run in the same Windows Server instance.
ISAPI agent handles the POST method for form data but not for other data types.
An agent configured for a site or parent application protects any application configured in the site or parent application.
A protected application configured for a site or parent application protects any application configured in the site or parent application.
Agents configured in a site or parent application protect only the child applications that inherit their parent IIS or ISAPI configuration.
Because of architectural differences, agents configured for a site or parent application running in a 64-bit pool don’t protect child applications running in a 32-bit pool. 32-bit applications can’t load 64-bit web agent libraries.

Similarly, agents configured for a site or parent application running in a 32-bit pool don’t protect child applications running in a 64-bit pool.

In this case, child applications require their own agent installation, as explained in the next item of this list. Both 32-bit and 64-bit agent libraries are supplied with the IIS and ISAPI Web Agent binaries.
If an application requires a specific agent configuration or, for example, the application is a 32-bit application configured within a 64-bit site, follow the procedures in this section to create a new agent instance for it. Configuring an agent on an application overrides the application’s parent web agent configuration, if any.

Install Web Agent on the child application before installing it in the parent. Trying to install an agent on a child that is already protected causes an error.
(For IIS agent) You can disable the agent protection at any level of the IIS hierarchy, with the following constraints:
- Disabling the agent in a parent application disables protection on all child applications that don’t have a specific agent instance installed on them.
- Disabling the agent in a child application doesn’t disable protection on its parent application.
(For ISAPI agent) You can’t disable the agent protection. ISAPI agent is either installed and running or not installed.
Agents require that the Application Development component is installed alongside the core IIS or ISAPI services. Application Development is an optional component of the IIS and ISAPI web server. The component provides required infrastructure for hosting web applications.

Figure 2. Adding the application development component to IIS and ISAPI
The following properties don’t work with ISAPI agent:
- Ignore Path Info in Request URLs
- Authorization flow for applications using Javascript

Install IIS or ISAPI Web Agent interactively

The IIS Web Agent installer does not support custom namespace elements in the web.config file. If any exist, they are removed from the web.config file during the installation process.

If you require custom namespace elements, back up the web.config file before installing the agent and manually restore them once the agent is installed.

Review the information in Before you install, and perform the steps in Preinstallation tasks.
Log on to Windows as a user with administrator privileges.
Make sure AM is running.

Run the agentadmin --i command to install the agent.

c:\> cd web_agents\iis_agent\bin
c:\web_agents\iis_agent\bin> agentadmin.exe --i

When prompted, enter information for your deployment.

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

Choose the site and application in which to install the web agent.

The agentadmin command reads the IIS or ISAPI server configuration and converts hierarchy as follows:
- (For ISAPI agent) Into a single value ID.
- (For IIS agent) Into an ID composed of three values separated by the dot (.) character:
  
  The first value specifies an IIS site. The number 1 specifies the first site in the server.
  
  The second value specifies an application configured in an IIS site. The number 1 specifies the first application in the site.
  
  The third value specifies an internal value for the web agent.
  
  The following is an example IIS server configuration read by the agentadmin command:
  IIS Server Site configuration: ==================================== id details ==================================== Default Web Site application path:/, pool DefaultAppPool 1.1.1 virtualDirectory path:/, configuration: C:\inetpub\wwwroot\web.config MySite application path:/, pool: MySite 2.1.1 virtualDirectory path:/, configuration C:\inetpub\MySite\web.config application path:/MyApp1, pool: MySite 2.2.1 virtualDirectory path:/ configuration C:\inetpub\MySite\MyApp1\web.config application path:/MyApp1/MyApp2, pool: MySite 2.3.1 virtualDirectory path:/ configuration C:\inetpub\MySite\MyApp1\MyApp2\web.config Enter IIS Server Site identification number. [ q or 'ctrl+c' to exit ] Site id: 2.1.1
  - ID 2.1.1 corresponds to the first application, / configured in a second IIS site, MySite. You would choose this ID to install the web agent at the root of the site.
  - ID 2.2.1 corresponds to a second application, MyApp1, configured in a second IIS site, MySite. You would choose this ID to install the web agent in the MyApp1 application.
  - ID 2.3.1 corresponds to a child application, MyApp1/MyApp2, configured in the second application, MyApp1, configured in a second IIS site, MySite. You would choose this ID to install the web agent in the sub-application, MyApp1/MyApp2.
The installer can import settings from an existing web agent on the new installation and skips prompts for any values present in the existing configuration file. You will be required to re-enter the agent profile password.

Enter the full path to an existing agent configuration file to import the settings, or press Enter to skip the import.
```
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 of the AM instance the agent will use. Ensure the deployment URI is specified.

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: https://am.example.com:8443/am

Enter the full URL of the site the agent will run in.

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

Enter the name given to the agent profile created in AM.

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

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: c:\pwd.txt

The installer displays a summary of the configuration settings you specified.

If a setting is incorrect, type no, or press Enter. The installer loops through the configuration prompts 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: https://am.example.com:8443/am
   Agent URL: https://customers.example.com:443
   Agent Profile name: iisagent
   Agent realm/organization name: /
   Agent Profile password source: c:\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 IIS or ISAPI site configuration.

To ease logging, the installer grants full user access permissions on the IIS or ISAPI instance folder.

Each agent instance has a numbered configuration and logs directory.
- For IIS, the first agent configuration and logs are located in web_agents\iis_agent\instances\agent_1\.
- For ISAPI, the agent ID corresponds to the site ID. If site 5 is used, the agent configuration and logs are located in web_agents\iis_agent\instances\agent_5\.

Ensure the application pool identity related to the IIS site has the appropriate permissions on the following agent installation folders:
- \web_agents\iis_agent\lib
- \web_agents\iis_agent\log
- \web_agents\iis_agent\instances\agent_nnn
  
  To change the ACLs for files and folders related to the agent instance, run the agentadmin --o command. For example:
  C:\web_agents\iis_agent\bin>agentadmin.exe --o "ApplicationPoolIdentity1" "C:\web_agents\iis_agent\lib"
  Learn more from agentadmin command.
  
  When permissions are not set correctly, errors such as getting a blank page when accessing a protected resource can occur.
If you installed Web Agent in an application, set CDSSO Redirect URI to the application path, as follows:
1. Go to Realms > Realm Name > Agents > Web > Agent Name > SSO > Cross Domain SSO.
2. Add the application path to the default value of CDSSO Redirect URI. For example, if you installed Web Agent in an application such as MyApp1/MyApp2, set the property to MyApp1/MyApp2/agent/cdsso-oauth2.
3. Save your changes.

Install IIS or ISAPI Web Agent silently

The IIS Web Agent installer does not support custom namespace elements in the web.config file. If any exist, they are removed from the web.config file during the installation process.

If you require custom namespace elements, back up the web.config file before installing the agent and manually restore them once the agent is installed.

Review the information in Before you install, and perform the steps in Preinstallation tasks.
Make sure AM is running.

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

c:\web_agents\iis_agent\bin> agentadmin.exe --s ^
  "2.1.1" ^
  "https://am.example.com:8443/am" ^
  "http://iis.example.com:80" ^
  "/" ^
  "iisagent" ^
  "c:\pwd.txt" ^

AM Web Agent for IIS Server installation.

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

Ensure the application pool identity related to the IIS site has the appropriate permissions on the following agent installation folders:
- \web_agents\iis_agent\lib
- \web_agents\iis_agent\log
- \web_agents\iis_agent\instances\agent_nnn
  
  To change the ACLs for files and folders related to the agent instance, run the agentadmin --o command. For example:
  C:\web_agents\iis_agent\bin>agentadmin.exe --o "ApplicationPoolIdentity1" "C:\web_agents\iis_agent\lib"
  Learn more from agentadmin command.
  
  When permissions are not set correctly, errors such as getting a blank page when accessing a protected resource can occur.
(Optional) If you installed the agent in a parent application, enable it for its child applications, as described in Disable and enable agent protection for child applications.

Enable and disable IIS Web Agent

ISAPI Web Agent can’t be enabled or disabled; it is either installed and running or not installed.

Disable and enable Web Agent on an IIS site or application

The agentadmin command shows only instances of the agent. Learn about how to enable or disable the protection of child applications in Disable and enable agent protection for child applications.

Log on to Windows as a user with administrator privileges.

Run the agentadmin --l command to list the installed agent configuration instances.

c:\web_agents\iis_agent\bin> agentadmin.exe --l

AM Web Agent configuration instances:

   id:            agent_1
   configuration: c:\web_agents\iis_agent\bin\..\instances\agent_1
   server/site:   2.2.1

Make a note of the ID value of the configuration instance you want to disable or enable.

Perform one of the following steps:
- To disable the agent in a site, run the agentadmin --d command and specify the ID of the agent configuration instance to disable.
  c:\web_agents\iis_agent\bin> agentadmin.exe --d agent_1 Disabling agent_1 configuration… Disabling agent_1 configuration… Done.
- To enable the agent in a site, run the agentadmin --e command and specify the ID of the agent configuration instance to enable.
  c:\web_agents\iis_agent\bin> agentadmin.exe --e agent_1 Enabling agent_1 configuration… Enabling agent_1 configuration… Done.

Disable and enable agent protection for child applications

Edit the child application’s web.config configuration.
Decide whether to enable or disable agent protection:
- To disable agent protection, add the following lines to the child application’s web.config file:
  <OpenAmModule enabled="false" configFile="C:\web_agents\iis_agent\instances\agent_1\config\agent.conf" /> <modules> <add name="OpenAmModule64" preCondition="bitness64" /> </modules>
  Note that the path specified in configFile may be different for your environment.
- To enable agent protection, understand that agents configured in a site or parent application also protect any applications that inherit the IIS configuration from that site or parent.
  
  If you have disabled the agent’s protection for a child application by following the steps in this procedure, remove the lines added to the web.config file to enable protection again.

Enable support for basic authentication and password replay

ISAPI Web Agent doesn’t support password replay.

The IIS Web Agent supports basic authentication and password replay. Use the appropriate software versions.

Given the proper configuration and with Active Directory as a user data store for AM, the IIS agent can provide access to IIS server variables. The instructions for configuring the capability follow in this section, though you should read the section in full, also paying attention to the required workarounds for Microsoft issues.

When configured as described, the agent requests IIS server variable values from AM, which gets them from Active Directory. The agent then sets the values in HTTP headers so that they can be accessed by your application.

The following IIS server variables all take the same value when set: REMOTE_USER, AUTH_USER, and login_USER. The agent either sets all three, or doesn’t set any of them.

When Logon and Impersonation is enabled, the agent performs Windows login and sets the user impersonation token in the agent session context.

When Show Password in HTTP Header is enabled, the agent adds the password in the USER_PASSWORD header.

The agent doesn’t modify any other IIS server variables related to the authenticated user’s session.

The agent requires that IIS runs in Integrated mode. Consider the following points for integration with additional Microsoft products:

For Microsoft Office integration, use Microsoft Office 2007 SP2 or later.
For Microsoft SharePoint integration, use Microsoft SharePoint Server 2007 SP2 or later.

Microsoft issues

Apply workarounds for the following Microsoft issues:

Microsoft support issue: 841215: Link: http://support.microsoft.com/kb/841215

Description: Error message when you try to connect to a Windows SharePoint document library: "System error 5 has occurred".

Summary: Enable Basic Authentication on the client computer.
Microsoft support issue: 870853: Link: http://support.microsoft.com/kb/870853

Description: Office 2003 and 2007 Office documents open read-only in Internet Explorer.

Summary: Add registry keys as described in Microsoft’s support document.
Microsoft support issue: 928692: Link: http://support.microsoft.com/kb/928692

Description: Error message when you open a Web site by using Basic authentication in Expression Web on a computer that is running Windows Vista: "The folder name isn’t valid".

Summary: Edit the registry as described in Microsoft’s support document.
Microsoft support issue: 932118: Link: http://support.microsoft.com/kb/932118

Description: Persistent cookies are not shared between Internet Explorer and Office applications.

Summary: Add the website the list of trusted sites.
Microsoft support issue: 943280: Link: http://support.microsoft.com/kb/943280

Description: Prompt for Credentials When Accessing FQDN Sites From a Windows Vista or Windows 7 Computer.

Summary: Edit the registry as described in Microsoft’s support document.
Microsoft support issue: 968851: Link: http://support.microsoft.com/kb/968851

Description: SharePoint Server 2007 Cumulative Update Server Hotfix Package (MOSS server-package): April 30, 2009.

Summary: Apply the fix from Microsoft if you use SharePoint.
Microsoft support issue: 2123563: Link: http://support.microsoft.com/kb/2123563

Description: You cannot open Office file types directly from a server that supports only Basic authentication over a non-TLS connection.

Summary: Enable TLS communications on the web server.

Configure basic authentication and password replay support

Use the openssl tool to generate a suitable encryption key:
```
$ openssl rand -base64 32
e63…sw=
```
In the AM admin UI, go to Deployment > Servers > Server Name > Advanced, and then add a property com.sun.am.replaypasswd.key with the encryption key you generated in a previous step as the value.
Go to Realms > Realm Name > Authentication > Settings > Post Authentication Processing, and in Authentication Post Processing Classes, add the class `com.sun.identity.authentication.spi.JwtReplayPassword `.
Restart AM.

In the AM admin UI go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Advanced

(AM 7.4.x and earlier versions) In Replay Password Key, enter the encryption key generated in a previous step. The field corresponds to Replay Password Key.

From AM 7.5, setting this property in the AM admin UI is deprecated. Values set in this field of the AM admin UI are ignored. The value of the DES key is inherited from the secret mapped to the AM secret label am.authentication.replaypassword.key.

For Windows login for user token impersonation, enable Logon and Impersonation.
Save your changes.

(Optional) To set the encrypted password in the IIS AUTH_PASSWORD server variable, go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Advanced, and enable Show Password in HTTP Header.
(Optional) If you require Windows login, or you need to use basic authentication with SharePoint or OWA, then you must do the following so that the agent requests AM to provide the appropriate account information from Active Directory in its policy response:
- Configure Active Directory as a user data store
- Configure the IIS or ISAPI agent profile User ID Parameter and User ID Parameter Type.
  
  Skip this step if you don’t use SharePoint or OWA and no Windows login is required.
  
  Make sure the AM data store is configured to use Active Directory as the user data store.
  
  In the AM admin UI under Realms > Realm Name > Applications > Agents > Web > Agent Name > AM Services, set User ID Parameter and User ID Parameter Type.
  
  For example, if the real username for Windows domain login in Active Directory is stored on the sAMAccountName attribute, then set the User ID Parameter to sAMAccountName, and the User ID Parameter Type to LDAP.
  
  Setting User ID Parameter Type to LDAP causes the web agent to request that AM get the value of the User ID Parameter attribute from the data store, in this case, Active Directory. Given that information, the agent can set the HTTP headers REMOTE_USER, AUTH_USER, or login_USER and USER_PASSWORD with Active Directory attribute values suitable for Windows login, setting the remote user, and so forth.
(Optional) To access Microsoft Office from SharePoint pages, configure AM to persist the authentication cookie. For information, refer to "Persistent cookie module" or "Persistent cookie decision node in AM’s Authentication and SSO guide.

Install in a subrealm

For example, instead of:

Agent realm/organization name: [/]: /

specify:

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

NGINX Plus Web Agent

Install NGINX Plus Web Agent

Examples use the NGINX Plus R31 agent path. For other supported versions, replace the R31 agent path with the required version. For information about supported versions of NGINX, refer to Other requirements.

Note that SELinux can prevent the web server from accessing agent libraries and the agent from being able to write to audit and debug logs. See Troubleshoot.

Install NGINX Plus Web Agent interactively

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

Run the agentadmin --i command to install the agent:

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

When prompted, enter information for your deployment.

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

Enter the full path to the NGINX Plus server configuration file, nginx.conf :

Enter the complete path to your NGINX server configuration file
 [ q or 'ctrl+c' to exit ]
 [nginx.conf]:/etc/nginx/nginx.conf

The installer can import settings from an existing web agent to the new installation and skips prompts for any values present in the existing configuration file. You will be required to re-enter the agent profile p assword.

Enter the full path to an existing agent configuration file to import the settings, or press Enter to skip the import:
```
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 of the AM instance that the agent should connect to:

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: https://am.example.com:8443/am

Enter the full URL of the server the agent is running on.

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:nginx_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 in the prerequisites:

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 configuration settings you specified.

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 setting is correct, type yes to proceed with installation:

Installation parameters:
 AM URL: https://am.example.com:8443/am
 Agent URL: http://www.example.com:80
 Agent Profile name: nginx_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…

 In order to complete the installation of the agent, update the configuration file /etc/nginx/nginx.conf

 if this is the first agent in the installation, please insert the following directives into the top section of the NGINX configuration
 load_module /web_agents/nginx31_agent/lib/openam_ngx_auth_module.so;

 then insert the following directives into the server or location NGINX configuration sections that you wish this agent to protect:
 openam_agent on;
 openam_agent_configuration /web_agents/nginx31_agent/instances/agent_1/config/agent.conf;

 Please ensure that the agent installation files have read/write permissions for the NGINX server’s user

 Please press any key to continue.

 Installation complete.

Each agent instance has a numbered configuration and logs directory. The first agent configuration and logs are located in /web_agents/nginx31_agent/instances/agent_1/.

Finish installation as described in Complete the NGINX Plus Web Agent Installation.

Install NGINX Plus 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 server where you plan to install the agent.
Make sure AM is running.

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

$ agentadmin --s \
 "/etc/nginx/nginx.conf" \
 "https://am.example.com:8443/am" \
 "http://www.example.com:80" \
 "/" \
 "nginx_agent" \
 "/secure-directory/pwd.txt" 
Web Agent for NGINX Server installation.

Validating…

Validating… Success.

Cleaning up validation data…

Creating configuration…

In order to complete the installation of the agent, update the configuration file /etc/nginx/nginx.conf

if this is the first agent in the installation, please insert the following directives into the top section of the NGINX configuration
load_module /web_agents/nginx31_agent/lib/openam_ngx_auth_module.so;

then insert the following directives into the server or location NGINX configuration sections that you wish this agent to protect:
openam_agent on;
openam_agent_configuration /web_agents/nginx31_agent/instances/agent_3/config/agent.conf;

Please ensure that the agent installation files have read/write permissions for the NGINX server’s user

Please press any key to continue.

Finish the installation as described in Complete the NGINX Plus Web Agent Installation.

Complete the NGINX Plus Web Agent installation

After interactive or silent installation, follow these steps to complete the installation.

Edit the NGINX Plus server configuration file nginx.conf to load the agent module openam_ngx_auth_module.so:

$ vi nginx.conf
user  nginx;
worker_processes  auto;

error_log     /var/log/nginx/error.log notice;
pid           /var/run/nginx.pid;
load_module   /web_agents/nginx31_agent/lib/openam_ngx_auth_module.so;
…

Add and openam_agent directive at the global level of nginx.conf to set the agent as on. Learn more from openam_agent.
Give the user or group running the NGINX Plus server appropriate permissions for the following directories:
- Read permission: /web_agents/nginx31_agent/lib
- Read and write permission:
  - /web_agents/nginx31_agent/instances/agent_nnn
  - /web_agents/nginx31_agent/log
Apply execute permissions on the folders listed above, recursively, for the user that runs the NGINX Plus server.

To determine which user or group is running the NGINX Plus server, check the User directive in the NGINX Plus server configuration file.

Failure to set permissions causes issues, such as the NGINX Plus server not starting up, getting a blank page when accessing a protected resource, or the web agent generating errors during log file rotation.

You may see the same issues if SELinux is enabled in enforcing mode and it is not configured to allow access to agent directories. For more information, refer to Troubleshoot.

Start the server.

The NGINX Plus server only sets the REMOTE_USER variable if the request contains an HTTP Authorization header, but the NGINX agent does not set an an HTTP Authorization header after the user has authenticated. Therefore, if you need to set the variable so CGI scripts can use it, configure the agent to create a custom header with the required attribute and then configure the NGINX Plus server to capture that header and convert it into the REMOTE_USER variable.

Check the NGINX Web Agent installation

After you start the server, check the server error log to make sure startup completed successfully:
```
2021… [info] 31#31: agent worker startup complete
```
Make an HTTP request to a resource protected by the agent, then check the /web_agents/nginx23_agent/log/system_0.log file to verify that no startup errors occurred:
```
Web Agent Version: 2024.6
Revision: ab12cde, Container: NGINX Plus 23 Linux 64bit (Ubuntu20),
Build date: …
```
(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

For example, instead of:

Agent realm/organization name: [/]: /

specify:

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

Configure NGINX Plus Web Agent

NGINX directives

Add NGINX directives to the /etc/nginx/nginx.conf configuration file to configure the global environment or individual HTTP servers and HTTP locations.

Directives are applied hierarchically. When set at the global level in nginx.conf, they apply to all HTTP servers and HTTP locations except those explicitly specified otherwise. Similarly, when set for an HTTP server or HTTP location, they are set for all child locations except those explicitly specified otherwise.

`openam_agent`

A flag to set the agent on or off:

openam_agent on: The agent protects the resource. It allows or denies requests based on AM policy configuration and not-enforced rules.
openam_agent off: NGINX protects the resource. The agent plays no part in protecting the server locations.

Default: None.

After installation, add openam_agent on to /etc/nginx/nginx.conf at the global level.

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
openam_agent on

Consider setting openam_agent to off for the following situations:

For HTTP servers or HTTP locations that need no AM authentication or policy, such as the public face of a website, /css directories, or /images directories.
When an NGINX HTTP Server is acting as a reverse proxy to AM or Advanced Identity Cloud, if you don’t want the agent to take part in protecting URLs in AM or Advanced Identity Cloud.

`openam_configuration`

The path to the local bootstrap file for the agent:

openam_configuration <path to nginx.conf>

Default: None, but during agent installation you must provide the path to /etc/nginx/nginx.conf.

`openam_threadpool`

The name of the AM threadpool:

openam_threadpool <name>

Default: The NGINX default threadpool

Before setting this directive, consider the consequence of changing the threadpool name.

openam_agent_instance

A number to identify an instance of NGINX Plus:

openam_agent_instance <number>

Default: 1

In deployments with multiple instances of NGINX Plus, use a unique number for each instance.

Examples

openam_agent is on globally but off` for one HTTP location

When openam_agent configuration is off, configure the server location /agent as on. This allows AM to redirect requests to the /agent endpoint after authentication.

In the following example nginx.conf:

agent_1 in the server context protects the / and /marketplace`location contexts
No agent instance protects the /customers`location context.

server {
  listen       80 default_server;
  server_name  localhost;
  openam_agent on;
  openam_agent_configuration /web_agents/nginx31_agent/instances/agent_1/config/agent.conf;
  #charset koi8-r;
  #access_log  /var/log/nginx/log/host.access.log  main;

    location / {
      root   /www/;
      index  index.html index.htm;
    }

    location /customers {
      openam_agent  off
      root   /www/customers
      index  index.html
    }

    location /market {
    root   /www/marketplace
    index  index.html
  }
}

Different agent instances protect different parts of the deployment

In the following example nginx.conf:

agent_1 at the server context protects the / and /marketplace`location contexts
agent_2 protects the /customers`location context

server {
  listen       80 default_server;
  server_name  localhost;
  openam_agent on;
  openam_agent_configuration /web_agents/nginx31_agent/instances/agent_1/config/agent.conf;
  #charset koi8-r;
  #access_log  /var/log/nginx/log/host.access.log  main;

    location / {
      root   /www/;
      index  index.html index.htm;
    }

    location /customers {
      openam_agent on;
      openam_agent_configuration /web_agents/nginx31_agent/instances/agent_2/config/agent.conf;
      root   /www/customers
      index  index.html
    }

    location /market {
      root   /www/marketplace
      index  index.html
  }
}

NGINX as a reverse proxy

This section contains an example configuration of NGINX as a reverse proxy between AM and Web Agent. You can use any reverse proxy that supports the WebSocket protocol.

Simplified diagram showing an NGINX configured as a reverse proxy between AM and the agent.

Figure 3. NGINX reverse proxy configured between the agent and AM

For information about how to configure NGINX for load balancing, and for other environment requirements, refer to the NGINX documentation at NGINX as a WebSocket Proxy.

After interactive or silent installation, follow these steps to configure NGINX as a reverse proxy.

Locate the NGINX Plus server configuration file /etc/nginx/nginx.conf.

Edit nginx.conf to add directives to the context you want to protect:

server {
  ...
  location /am
    {
      proxy_set_header Host $host proxy_pass http://hostname:port/am;
      proxy_http_version 1.1;
      proxy_set_header Connection ""; # to allow keep alives to work #
    }
  location /am/notifications/
    {
      proxy_pass http://hostname:port/am/notifications;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "Upgrade";
      proxy_set_header Host $host;
    }
  ...
}

Ensure the user or group running the NGINX Plus server has the appropriate permissions over the following directories:
- Read Permission: /web_agents/nginx31_agent/lib
- Read and Write Permission:
  - /web_agents/nginx31_agent/instances/agent_nnn
  - /web_agents/nginx31_agent/log
Restart the reverse proxy instance.
Configure AM to recover the forwarded header configured in the reverse proxy.
Review other configuration that a reverse proxy environment can require. Learn more from Agent connection to AM through a load balancer/reverse proxy

Post-installation

Review directories for configuration and logs

Each agent instance has a numbered configuration and logs directory, starting with agent_1. The first agent configuration and logs are located at web_agents/agent_type/instances/agent_1/.

The following configuration files and logs are created:

web_agents/agent_type/instances/agent_1/config/: Bootstrap properties to connect to AM and download the configuration. This directory contains properties that are used only in local configuration mode.
web_agents/agent_type/instances/agent_1/logs/audit/: Audit log directory. Used only if Audit Log Location is LOCAL or ALL.
web_agents/agent_type/instances/agent_1/logs/debug/: The directory where the agent writes debug log files after startup.

During agent startup, the location of the logs can be based on the agent web server, or defined in the site configuration file for the server. For example, bootstrap logs for NGINX Plus Web Agent can be written to /var/log/nginx/error.log.

Validate the agent instance

Validate the agent instance by using the agentadmin --V[i] command. For information about the options and requirements for this command, refer to agentadmin.

Linux
Windows

$ sudo -u web-server-user
$ cd /web_agents/agent_type/bin/
$ ./agentadmin --Vi agent_name am_identity_name /path/to/am_identity_password

C:\web_agents\agent-type\bin> agentadmin --Vi ^
agent_name am_identity_name C:/path/to/am_identity_password /

A result similar to this is displayed:

Running configuration validation for agent_1:

  Agent instance is configured with 1 naming.url value(s):
  1. https://am.example.com:8443/am is valid
  selected https://am.example.com:8443/am as naming.url value
  validate_bootstrap_configuration: ok
  validate_ssl_libraries: ok
  validate_agent_login: ok
  get_allocator_blockspace_sz(): trying for configured cache size 16777216 bytes
  validate_system_resources: ok
  validate_session_profile: ok
  validate_websocket_connection: ok
  validate_worker_init_shutdown: ok

Result: 7 out of 7 tests passed, 0 skipped.

If validate_websocket_connection is not ok, make sure the web server and the network infrastructure between the web server and the AM servers support WebSockets.

Configure shared runtime resources and memory

Consider using agent resource groups in atypical deployments, where multiple independent web servers are deployed on the same machine. Agent resource groups apply only to Apache HTTP server or NGNIX, because IIS and ISAPI runs only as a single instance.

Agent resource groups allow server processes to share resources and memory, such as background tasks, log files, runtime resources including pipes, caches, and notification channels to AM.

An agent resource group is determined by the AmAgentID directive in a web server configuration. The value is numeric and defaults to 0 for a typical, single-server deployment. By default, up to 32 agent instances can be in a single installation. For information about changing this limit, refer to AM_MAX_AGENTS in Environment variables.

Choose whether to share resources

Consider the information in the following table before configuring your agent resource groups:

Impact Advantage Caution

Impact	Advantage	Caution
Shared agent policy and session cache	Potentially reduces overhead of requests to AM for authentication and authorization.	Cache may fill with irrelevant entries.
Reduced memory consumption.	Sharing the cache among different locations or virtual hosts may not be desirable.
-	Agent instances that are members of the same agent group must be configured in the same Apache or NGINX Plus installation.
Reduced number of background threads. (Single WebSocket connection to AM for notifications)	Reduced system resource usage.	Ensure that the `AM_MAX_AGENTS` environment variable is set to, at least, the total number of agent instances in the installation.
Agent instances share runtime files and semaphores	Reduced system resource usage.	Ensure that files and resources can be accessed by all agent instances. For example, add the users running the instances to the same group and configure the resources to have `660` permissions. Learn more from AM_RESOURCE_PERMISSIONS in Environment variables.

Shared agent policy and session cache

Potentially reduces overhead of requests to AM for authentication and authorization.

Cache may fill with irrelevant entries.

Reduced memory consumption.

Sharing the cache among different locations or virtual hosts may not be desirable.

Agent instances that are members of the same agent group must be configured in the same Apache or NGINX Plus installation.

Reduced number of background threads. (Single WebSocket connection to AM for notifications)

Reduced system resource usage.

Ensure that the AM_MAX_AGENTS environment variable is set to, at least, the total number of agent instances in the installation.

Agent instances share runtime files and semaphores

Reduced system resource usage.

Ensure that files and resources can be accessed by all agent instances.

For example, add the users running the instances to the same group and configure the resources to have 660 permissions. Learn more from AM_RESOURCE_PERMISSIONS in Environment variables.

Configure Apache agent groups

To create a group in an Apache agent installation, add an AmAgentId directive to the Apache configuration file, httpd.conf.

To create multiple agent groups in an installation, set AmAgentId to a different value in each Apache configuration file. Set only one AmAgentId directive in each httpd.conf. If more than one value is set, the agent uses the last set value.

When AmAgentId isn’t specified in httpd.conf, it takes the default value of 0.

The following example httpd.conf file configures a group with AmAgentId 1. The group includes two virtual hosts, each protected by a different instance of the agent. Both agent instances belong to the agent group 1.

The AmAgentId configuration must be outside the VirtualHost section.

AmAgentId 1
<VirtualHost *:80>
ServerName www.site1.com
DocumentRoot /home/www/site1.com
AssignUserID site1 www-data
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_1/config/agent.conf
…
</VirtualHost>

<VirtualHost *:8080>
ServerName www.site2.com
DocumentRoot /home/www/site3.com
AssignUserID site2 www-data
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_2/config/agent.conf
…
</VirtualHost>

The following table shows an example of six Apache agent instances split into three agent groups:

Agent instances Directive configuration Description

Agent instances	Directive configuration	Description
`Agent_1` and `Agent_2`	Not set (default 0)	`Agent_1` and `Agent_2` instances share runtime resources and the policy cache with each other.
`Agent_3`, `Agent_4`, and `Agent_5`	1	`Agent_3`, `Agent_4`, and `Agent_5` instances share runtime resources and the policy cache with each other.
`Agent_6`	2	`Agent_6` instance doesn’t share runtime resources or the policy cache with any other instance.

Agent_1 and Agent_2

Not set (default 0)

Agent_1 and Agent_2 instances share runtime resources and the policy cache with each other.

Agent_3, Agent_4, and Agent_5

Agent_3, Agent_4, and Agent_5 instances share runtime resources and the policy cache with each other.

Agent_6

Agent_6 instance doesn’t share runtime resources or the policy cache with any other instance.

Configure NGINX Plus agent groups

To add NGINX Plus agent instances to a group, add the openam_agent_instance directive to each instance in the NGINX Plus server configuration file /etc/nginx/nginx.conf.

The following example nginx.conf file configures one agent group, openam_agent_instance 2, containing agent_3 and agent_4:

server {
  listen       80 default_server;
  server_name  localhost;
  openam_agent on;
  openam_agent_configuration /web_agents/nginx31_agent/bin/../instances/agent_3/config/agent.conf; openam_agent_instance 2
  …
  location /customers {
    openam_agent on;
    openam_agent_configuration /web_agents/nginx31_agent/bin/../instances/agent_4/config/agent.conf; openam_agent_instance 2
    root   /www/customers
    index  index.html
  }
…

When openam_agent_instance is not specified for an agent instance, the instance uses the default value of 1.

To create multiple agent groups in an NGINX Plus agent installation, use different values for openam_agent_instance. In the previous example, you could specify two groups by using openam_agent_instance 2 and openam_agent_instance 3.

Secure communication between the agent and AM

Be mindful of security breaches and vulnerabilities. Ensure your environment isn’t using outdated, insecure protocols, such as SSL 3.0, TLS 1.0, and others.

To secure communications, configure the agent to validate server certificates installed in the server where AM runs and/or to present a client certificate to AM. Learn more in AM’s Secure HTTP and LDAP connections.

To facilitate integration and test, Web Agent is configured by default to trust any server certificate. Test client certificates aren’t provided or configured.

To send cookies only when the communication channel is secure, set Enable Cookie Security to true.

Secure internal communication with OpenSSL

Unix-based agents support only OpenSSL libraries. Windows-based agents can use OpenSSL or Secure communication with the Windows Secure Channel API.

You can find details about supported versions of OpenSSL, and where to locate related libraries in Secure communication between Web Agent and AM.

Configure server-side and client-side validation using OpenSSL

Perform the following steps to configure the agent to validate AM’s server certificate chain and to present client certificates if requested:

Open the /web_agents/agent_type/instances/agent_nnn/config/agent.conf configuration file.
(For IIS, ISAPI, and Apache agent) Configure the agent to use OpenSSL.
1. Set the property Enable OpenSSL to Secure Internal Communications to true.
2. Ensure that the OpenSSL libraries are in the appropriate place, as specified in OpenSSL library location by operating system.
(Optional) Configure the agent to validate AM’s server certificate:
1. Create a Privacy-Enhanced Mail (PEM) file that contains the certificates required to validate AM’s server certificate. For example, ca.pem .
2. Set the property Server Certificate Trust to false.
3. Set the property CA Certificate File Name to the PEM file previously created. For example:
  Unix
  
  Windows
  
  com.forgerock.agents.config.cert.ca.file = /opt/certificates/ca.pem
  
  com.forgerock.agents.config.cert.ca.file = C:\Certificates\ca.pem
4. Set the property OpenSSL Certificate Verification Depth to the level of certificate validation required in your environment.
(Optional) To configure the agent to present its client certificate when AM is configured to perform client authentication, perform the following steps:
1. Create a PEM file that contains the certificate chain for the agent. For example, client-cert.pem .
2. Create a PEM file that contains the private key corresponding to the certificate. For example, client-private-key.pem .
3. Set the property Public Client Certificate File Name to the file containing the certificate chain. For example:
  Unix
  
  Windows
  
  com.forgerock.agents.config.cert.file = /opt/certificates/client-cert.pem
  
  com.forgerock.agents.config.cert.file = C:\Certificates\client-cert.pem
4. Set the property Private Client Certificate File Name to the file containing the client certificate private key. For example:
  Unix
  
  Windows
  
  com.forgerock.agents.config.cert.key = /opt/certificates/client-private-key.pem
  
  com.forgerock.agents.config.cert.key = C:\Certificates\client-private-key.pem
5. If the private key is password-protected, obfuscate the password by using the agentadmin --p command and configure it in the property Private Key Password. For example:
  Unix
  
  Windows
  
  $ /path/to/web_agents/agent_type/bin/> agentadmin --p "Encryption Key" “cat certificate_password.file” Encrypted password value: zck...jtc=com.forgerock.agents.config.cert.key.password = zck...tc=
  
  C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p "Encryption_Key" "Certificate_File_Password" Encrypted password value: zck...jtc=com.forgerock.agents.config.cert.key.password = zck...tc=
  Encryption Key is the value of the property Agent Profile Password Encryption Key.

Review your configuration. It should look similar to the following:

Unix
Windows

//Server-side
com.sun.identity.agents.config.trust.server.certs = false
com.forgerock.agents.config.cert.ca.file = /opt/certificates/ca.pem
//Client-side
com.forgerock.agents.config.cert.file = /opt/certificates/client-cert.pem
com.forgerock.agents.config.cert.key = /opt/certificates/client-private-key.pem
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

//General
org.forgerock.agents.config.secure.channel.disable=true
//Server-side
com.sun.identity.agents.config.trust.server.certs = false
com.forgerock.agents.config.cert.ca.file = C:\Certificates\ca.pem
//Client-side
com.forgerock.agents.config.cert.file = C:\Certificates\client-cert.pem
com.forgerock.agents.config.cert.key = C:\Certificates\client-private-key.pem
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

Restart the agent.

Secure communication with the Windows Secure Channel API

By default, IIS, ISAPI, and Apache for Windows agents use the Windows built-in Secure Channel API. You can find details about using OpenSSL in Securing internal communication with OpenSSL.

Configure server-side and client-side validation using the Windows built-in Secure Channel API

Perform the following steps to configure the agent to validate AM’s certificate chain and to present client certificates if requested:

Open the /web_agents/agent_type/instances/agent_nnn/config/agent.conf configuration file.
Configure the agent to use the Windows built-in Secure Channel API:
1. If this is a new installation, continue to the next step. Windows-based agents use the Windows built-in Secure Channel API by default.
2. If you configured the IIS, ISAPI, or Apache agent to use OpenSSL libraries, set the property Enable OpenSSL to Secure Internal Communications to false.
(Optional) To configure the agent to validate AM certificate chain, perform the following steps:
1. Add the certificates required to validate AM’s server certificate to the Windows certificate store. For example, to use PowerShell, add root certificates to the Cert:\LocalMachine\Root location, and CA certificates to the Cert:\LocalMachine\Ca location.
2. Set the property Server Certificate Trust to false.

(Optional) When AM is configured to perform client authentication, configure the agent to present client certificates:

Import the client certificate chain and private key into the Windows certificate store. For example, for PowerShell, import them to Cert:\LocalMachine\My.

Set the property Public Client Certificate File Name to the friendly name of the client certificate chain. For example:

com.forgerock.agents.config.cert.file = agent.example.com

Friendly name of the client certificate imported into the Windows certificate store.

For compatibility, the agent supports an alternative configuration that does not use the Windows certificate store.

Create a Personal Information Exchange (PFX) file containing the certificate chain for the agent and its private key. For example, client.pfx .
Set the property Public Client Certificate File Name to the previously created PFX file. For example:
```
com.forgerock.agents.config.cert.file = C:\Certificates\client.pfx
```
Obfuscate the certificate password by using the agentadmin --p command. For example:
```
C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p "Encryption_Key" "Certificate_File_Password"
Encrypted password value: zck+6RKqjtc=
```
Encryption_Key is the value of the Agent Profile Password Encryption Key property.
Set the property Private Key Password to the value of the encrypted password. For example:
```
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=
```
Restart the agent.

Review your configuration. It should look similar to the following:

Windows Cert Store
Windows PFX / PCKS12 File

//Server-side
com.sun.identity.agents.config.trust.server.certs = false
//Client-side
com.forgerock.agents.config.cert.file = agent.example.com

//Server-side
com.sun.identity.agents.config.trust.server.certs = false
//Client-side
com.forgerock.agents.config.cert.file = C:\Certificates\client.pfx
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

Restart the agent.

Support load balancers and reverse proxies between clients and agents

When your environment has reverse proxies or load balancers configured between agents and clients, you must perform additional configuration in the agents to account for the anonymization of both the clients and the agents.

Failure to do so may cause policy evaluation and other agent features to fail.

Configure audit logging

Web Agent supports the logging of audit events for security, troubleshooting, and regulatory compliance. Store agent audit event logs in the following ways:

Remotely

Log audit events to the audit event handler configured in the AM realm. In a site comprised of several AM servers, agents write audit logs to the AM server that satisfies the agent request for client authentication or resource authorization.

Agents cannot log audit events remotely if:

AM’s audit logging service is disabled.
No audit event handler is configured in the agent profile realm.
All audit event handlers configured in the agent profile realm are disabled.

For more information about audit logging in AM, refer to Audit logging in AM’s Security guide.

Locally

Log audit events in JSON format to a file in the agent installation directory, /web_agents/agent_type/logs/audit/.

Locally and remotely

Log audit events:

To a file in the agent installation directory.
To the audit event handler configured in the agent profile realm.

The example is an agent log record:

{
   "timestamp":"2017-10-30T11:56:57Z",
   "eventName":"AM-ACCESS-OUTCOME",
   "transactionId":"608831c4-7351-4277-8a5f-b1a83fe2277e",
   "userId":"id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
   "trackingIds":[
      "fd5c8ccf-7d97-49ba-a775-76c3c06eb933-82095",
      "fd5c8ccf-7d97-49ba-a775-76c3c06eb933-82177"
   ],
   "component":"Web Policy Agent",
   "realm":"/",
   "server":{
      "ip":"127.0.0.1",
      "port":8020
   },
   "request":{
      "protocol":"HTTP/1.1",
      "operation":"GET"
   },
   "http":{
      "request":{
         "secure":false,
         "method":"GET",
         "path":"http://my.example.com:8020/examples/",
         "cookies":{
            "am-auth-jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOi[...]"
            "i18next":"en",
            "amlbcookie":"01",
            "iPlanetDirectoryPro":"Ts2zDkGUqgtkoxR[...]"
         }
      }
   },
   "response":{
      "status":"DENIED"
   },
   "_id":"fd5c8ccf-7d97-49ba-a775-76c3c06eb933-81703"
}

Local audit logs do not have an _id attribute, which is an internal AM id.

The audit log format adheres to the log structure shared across the Ping Identity Platform. For more information about the audit log format, refer to Audit log format in AM’s Security guide.

Web Agent supports propagation of the transaction ID across the Ping Identity Platform using the HTTP header X-ForgeRock-TransactionId. For more information about configuring the header, refer to Trust transaction headers in AM’s Security guide.

By default, the Web Agent does not write audit log records. To configure audit logging, perform the following procedure:

Configure audit logging for the agent

This procedure assumes the Web Agent is in centralized configuration mode. Property names are provided for local configuration mode.

In the AM admin UI, go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Global > Audit.
In Audit Access Types, select the type of messages to log. For example, select LOG_ALL to log access allowed and access denied events.
In Audit Log Location, select whether to write the audit logs locally to the agent installation (LOCAL), remotely to AM (REMOTE), or to both places (ALL). For example, keep REMOTE to log audit events to the AM instances.
In Local Audit Log Rotation Size, specify the maximum size, in bytes, of the audit log files.

This is a bootstrap property. After changing this property, restart the web server where the agent runs.

Configure AM to sign authentication information

AM communicates all authentication and authorization information to Web Agent, using OpenID Connect ID tokens. For security, configure AM and the agent to use signed tokens. Learn more from RFC 7518: JSON Web Algorithms (JWA).

AM also uses an HMAC signing key to protect requested ACR claims values between sending the user to the authentication endpoint, and returning from successful authentication.

By default, AM uses a demo key and an autogenerated secret for these purposes. For production environments, perform one of the following procedures to create new key aliases and configure them in AM.

Configure AM secret labels for the agents' OAuth 2.0 provider

By default, AM 6.5 and later versions are configured to:

Sign the session ID tokens with the secret mapped to the am.global.services.oauth2.oidc.agent.idtoken.signing secret label. The label defaults to the rsajwtsigningkey key alias provided in AM’s JCEKS keystore.
Sign the claims with the secret mapped to the am.services.oauth2.jwt.authenticity.signing secret label. The label defaults to the hmacsigningtest key alias available in AM’s JCEKS keystore.
1. Create the following aliases in one of the secret stores configured in AM, for example, the default JCEKS keystore:
  1. Create an RSA key pair.
  2. Create an HMAC secret.
2. In the AM admin UI, go to Configure > Secret Stores > Keystore Secret Store Name > Mappings.
3. Configure the following secret labels:
  1. Configure the new RSA key alias in the am.global.services.oauth2.oidc.agent.idtoken.signing secret label.
  2. Configure the new HMAC secret in the am.services.oauth2.jwt.authenticity.signing secret label.
    
    Note that you may already have a secret configured for this secret label, because it is also used for signing certain OpenID Connect ID tokens and remote consent requests. Learn more from Secret label default mappings in AM’s Security guide.
  3. Save your changes.
  For more information about secret stores, refer to Secret stores in AM’s Security guide.
No further configuration is required in the agents.

Secure communication between Web Agent and AM

Web Agent requires OpenSSL or the Windows built-in Secure Channel API to be available at install time. Unix agents support only OpenSSL. Windows agents support OpenSSL and the Windows Secure Channel API.

For information about supported OpenSSL versions, refer to OpenSSL requirements.

Before installing, make sure the OpenSSL libraries are located or referenced as shown in the following table:

Operating System OpenSSL Library Location or Variable

Operating System	OpenSSL Library	Location or Variable
Windows 32-bit	`libeay32.dll` `ssleay32.dll` `libcrypto-1_1.dll`⁽¹⁾ `libssl-1_1.dll`⁽¹⁾	`\windows\syswow64`
Windows 64-bit	`libeay64.dll` `ssleay64.dll` `libcrypto-1_1-x64.dll`⁽¹⁾ `libssl-1_1.dll`⁽¹⁾	`\windows\system32`
Linux	`libcrypto.so` `libssl.so`	`$LD_LIBRARY_PATH` `$LD_LIBRARY_PATH_64`
AIX	`libcrypto.so` `libssl.so`	`$LIBPATH`

Windows 32-bit

libeay32.dll
ssleay32.dll
libcrypto-1_1.dll⁽¹⁾
libssl-1_1.dll⁽¹⁾

\windows\syswow64

Windows 64-bit

libeay64.dll
ssleay64.dll
libcrypto-1_1-x64.dll⁽¹⁾
libssl-1_1.dll⁽¹⁾

\windows\system32

Linux

libcrypto.so
libssl.so

$LD_LIBRARY_PATH $LD_LIBRARY_PATH_64

AIX

libcrypto.so
libssl.so

$LIBPATH

⁽¹⁾OpenSSL 1.1.0+ only

Windows 64-bit servers require both 32-bit and 64-bit OpenSSL libraries.

Remove Web Agent

Remove Apache Web Agent

Shut down Apache HTTP Server where the agent is installed.
Run agentadmin --l to output a list of the installed web agent configuration instances.

Note the ID of the Web Agent instance to remove.

Run agentadmin --r, and specify the ID of the web agent configuration instance to remove. A warning is displayed. Type yes to proceed with removing the configuration instance.

$ ./agentadmin --r agent_1

Warning! This procedure will remove all Web Agent references from
a Web server configuration. In case you are running Web Agent in a
multi-virtualhost mode, an uninstallation must be carried out manually.

Continue (yes/no): [no]: yes

Removing agent_1 configuration…
Removing agent_1 configuration… Done.

To silently remove the agent, you can echo the answer and pipe it to the agentadmin --r command. For example:

$ echo yes | ./agentadmin --r agent_1

Start the Apache HTTP Server.

Remove IIS or ISAPI Web Agent

Remove a single instance of IIS or ISAPI Web Agent

Perform the steps in this procedure to remove :

Log on to Windows as a user with administrator privileges.

Run agentadmin.exe --l to output a list of the installed agent configuration instances.

c:\web_agents\iis_agent\bin> agentadmin.exe --l
agentadmin.exe --l
Web Agent configuration instances:

id:            agent_1
configuration: c:\web_agents\iis_agent\bin\..\instances\agent_1
server/site:   2.2.1

Note the ID of the Web Agent instance to remove.

Run agentadmin.exe --r, specifying the ID of the Web Agent instance to remove.
```
c:\web_agents\iis_agent\bin> agentadmin.exe --r agent_1
Removing agent_1 configuration…
Removing agent_1 configuration… Done.
```
The --r option does not remove the agent libraries. To remove all agent instances and libraries, refer to Remove all instances of IIS or ISAPI Web Agent.
To silently remove the agent, you can echo the answer and pipe it to the agentadmin --r command. For example:

c:\web_agents\iis_agent\bin> echo yes | agentadmin.exe --r agent_1

Remove all instances of IIS or ISAPI Web Agent

Log on to Windows as a user with administrator privileges.

Run agentadmin --g. A warning is displayed. Type yes to proceed with removing the configuration instance.

c:\web_agents\iis_agent\bin> agentadmin.exe --g

Warning! This procedure will remove all Web Agent references from
IIS Server configuration.

Continue (yes/no): [no]: yes
Removing agent module from IIS Server configuration…
Removing agent module from IIS Server configuration… Done.

Remove NGINX Plus Web Agent

Shut down the NGINX Plus server where the agent is installed.

Run the agentadmin --l command to output a list of installed agent instances. For example:

$ ./agentadmin --l
OpenAM Web Agent configuration instances:

id:            agent_1
configuration: /web_agents/nginx31_agent/instances/agent_1
server/site:   /etc/nginx/nginx.conf

id:            agent_2
configuration: /web_agents/nginx31_agent/instances/agent_2
server/site:   /etc/nginx/nginx.conf

id:            agent_3
configuration: /web_agents/nginx31_agent/instances/agent_3
server/site:   /etc/nginx/nginx.conf

Note the ID of the Web Agent instance to remove.

Run the agentadmin --r command, specifying the ID of the agent instance to remove. A warning is displayed. Type yes to remove the instance.

$ ./agentadmin --r agent_1
Warning! This procedure will remove the Web Agent configuration for agent_1
but not references to it your NGINX server configuration file: /etc/nginx/nginx.conf.

Continue (yes/no): [no]: yes

In order to complete the removal of the agent from your NGINX installation,
remove the openam_agent_ directives for this agent
from your NGINX configuration file: /etc/nginx/nginx.conf
and, if this is the only agent in the installation,
remove the load_module directive for the openam_agent_auth_module
in the NGINX configuration file.

Please press any key to continue.


Removing agent_1 configuration… Done.

To silently remove the agent, you can echo the answer and pipe it to the agentadmin --r command. For example:

$ echo yes | ./agentadmin --r agent_1

Edit the NGINX Plus configuration file that contains the context protected by the removed web agent instance.
Delete the openam_agent_ directives from the context.

If this is the last agent in the NGINX Plus server, remove the directive that loads the openam_ngx_auth_module.so library.
Restart the NGINX Plus server.

agentadmin command

The agentadmin command manages Web Agent installation and keys. It returns EXIT_SUCCESS (or 0) when it completes successfully, and EXIT_FAILURE (or a code greater than zero) when it fails.

The following options are supported:

`--i`

Install a new agent instance.

Usage: agentadmin --i

`--s`

Install a new agent instance non-interactively.

Usage: agentadmin --s web-server-config-file openam-url agent-url realm agent-profile-name agent-profile-password [--changeOwner] [--forceInstall]

web-server-config-file

(Apache HTTP Server) The full path to the server configuration file. The installer modifies this file to include the agent configuration and module.

(IIS and ISAPI agent only) The ID number of the IIS or ISAPI site in which to install the agent. To list the available sites in an IIS server and the relevant ID numbers, run agentadmin.exe --n.

am-url

The full URL of the AM instance that the agent will use. Ensure the deployment URI is specified.

Example: https://am.example.com:8443/am

agent-url

The full URL of the server on which the agent is running.

Example: http://www.example.com:80

realm

The AM realm containing the agent profile.

agent-profile-name

The name of the agent profile in AM.

agent-profile-password

The full path to the agent profile password file.

--changeOwner

Apache web agent for Unix only: Change the ownership of created directories to the user and group as specified in the Apache configuration file.

To use this option, you must run the agentadmin command as the root user or with the sudo command. If you can’t run the agentadmin command as the root user or with the sudo command, you must change the ownership manually.

--forceInstall

If the agent can’t connect to the specified AM server during installation, proceed with a non-interactive installation instead of exiting.

`--n`

(IIS and ISAPI agent only) List the sites available in an IIS server.

Example:

c:\web_agents\iis_agent\bin> agentadmin.exe --nIIS Server Site configuration:
     ====================================
     id       details
     ====================================

     Default Web Site
     application path:/, pool DefaultAppPool
     1.1.1    virtualDirectory path:/, configuration: C:\inetpub\wwwroot\web.config

     MySite
     application path:/, pool: MySite
     2.1.1    virtualDirectory path:/, configuration C:\inetpub\MySite\web.config
     application path:/MyApp1, pool: MySite

`--l`

List configured agent instances.

Usage: agentadmin --l

Example:

$ ./agentadmin --l
AM Web Agent configuration instances:

      id:            agent_1
      configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_1
      server/site:   /etc/httpd/conf/httpd.conf

      id:            agent_2
      configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_2
      server/site:   /etc/httpd/conf/httpd.conf

      id:            agent_3
      configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_3
      server/site:   /etc/httpd/conf/httpd.conf

`--g`

(IIS and ISAPI agent only) Remove all agent instances and libraries from an installation.

Usage: agentadmin.exe --g

Learn more from Remove IIS or ISAPI Web Agent.

`--e`

(IIS agent only) Enable an existing agent instance.

Usage: agentadmin.exe --e agent-instance

`--d`

(IIS agent only) Disable an existing agent instance.

Usage: agentadmin.exe --d agent-instance

`--o`

(IIS and ISAPI agent only) Modify Access Control Lists (ACLs) for files and folders related to a web agent instance.

Usage: agentadmin.exe --o "identity_or_siteID" "directory" [--siteId]

Usage: agentadmin.exe --o "directory" --addAll --removeAll

"identity_or_siteID"

Specify the identity to be added to the directory’s ACLs. When used with the --siteId option, this option specifies a site ID.

"directory"

Specify the directory that would be modified.

[--siteId]

Specify that the agentadmin should use identity_or_siteID as a site ID.

--addAll

Add all agent application pool identities to the directory’s ACLs. This option is not compatible with the --removeAll option.

--removeAll

Remove all agent application pool identities from the directory’s ACLs. This option isn’t compatible with the --addAll option.

Example:

C:\web_agents\iis_agent\bin> agentadmin.exe --o "IIS_user1" "C:\web_agents\iis_agent\lib"

C:\web_agents\iis_agent\bin> agentadmin.exe --o "2" "C:\web_agents\iis_agent\lib" --siteId

C:\web_agents\iis_agent\bin> agentadmin.exe --o  "C:\web_agents\iis_agent\lib" --addAll

`--r`

Remove an existing agent instance.

Usage: agentadmin --r agent-instance

agent-instance: The ID of the agent configuration instance to remove.

Respond yes when prompted to confirm removal.

On IIS and ISAPI web agents, the --r option doesn’t remove the web agent libraries because they can be in use by other agent instances configured on the same site. To remove all agent instances and libraries, use the --g option.

`--k`

Generate a base64-encoded 256-bit random key.

Usage: agentadmin --k [--rotate agent-instance]

Learn more in Rotate keys.

--rotate

Rotate the key for the specified agent instance. Learn more in Rotate keys.

agent-instance

The ID of the agent instance for which to rotate keys.

Unix
Windows

$ cd /web_agents/apache24_agent/bin/
$ ./agentadmin --k
Encryption key value: ztw…hM=

C:\> cd web_agents{apache_agent_version}\bin
C:\web_agents{apache_agent_version}\bin> agentadmin --k
Encryption key value: ztw…hM=

Unix
Windows

$ cd /web_agents/apache24_agent/bin/
$ ./agentadmin --k --rotate agent_n
…
Key rotation was successful for instance: agent_n

C:\> cd web_agents{apache_agent_version}\bin
C:\web_agents{apache_agent_version}\bin> agentadmin --k --rotate agent_n
…
Key rotation was successful for instance: agent_n

`--p`

Use a generated encryption key to encrypt a new password.

Use a given key to encrypt a given password. The output is an AES-256-GCM encrypted password.

Usage: agentadmin --p key password

key

A key generated by the agentadmin --k command.

password

The password to encrypt.

The following example creates an agent-password.conf file containing the encrypted password, where:

key is the key generated by the agentadmin --k command
/var/tmp/pwd.txt is a text file containing the unencrypted password

Unix
Windows

$ ./agentadmin --p key $(cat /var/tmp/pwd.txt)
Encrypted password value: 07b…dO4=

$ agentadmin.exe --p key "newpassword"
Encrypted password value: 07b…dO4=

`--V[i]`

Validate the installation. Use this command in conjunction with sustaining to troubleshoot installations.

The command validates the following points:

The agent can reach the AM server(s) configured in AM Connection URL.
Critical bootstrap properties are set. Learn more from Agent configuration.
For SSL communication, TLS/SSL libraries are available and SSL configuration properties are set.
The system has enough RAM and shared memory.
The agent can log in to AM with the provided credentials and fetch the agent profile.
The agent can decrypt the agent profile password by using the Agent Profile Password Encryption Key provided in agent-key.conf.
WebSocket connections are available between the agent and AM.
The core init and shutdown agent sequences are working as expected. This validation requires the --Vi flag.
(IIS and ISAPI agent only) The agent is configured to run application pools in Integrated mode.
When Server Certificate Trust is set to true to trust all certificates, the validator issues a warning to set the property to false in production environments.

To prevent service outage or an unresponsive agent, run the command only when the agent instance isn’t actively protecting a website.
On Unix, run the command as the same user or group that runs the web server. For example, to use the Apache HTTP Server daemon user:
```
$ sudo -u daemon ./bin/agentadmin --V agent_1
```
Running the command as a different user can cause the log/system_0.log and log/monitor_0.pipe files to be created with permissions that prevent the agent from writing to them, causing an error such as:
```
… GMT ERROR   [0x7f0c9cf05700:22420]: unable to open event channel
```
Make sure the user running the command has execute permission on the following directories:
- /web_agents/apache24_agent/instances/agent_nnn
- /web_agents/apache24_agent/log

Usage:

agentadmin --V[i] agent_instance [user name] [password file] [realm]

[i]: (Optional) Ensure that the core init and shutdown agent sequences are working as expected.
agent_instance: (Required) The agent instance where to run the validation tests. For example, agent_1.
user name: (Optional) A user ID that exists in the AM server. Required only for the validate_session_profile test. For example, demo.
password file: (Optional) A file containing the password of the user ID used for the validate_session_profile test. For example, /secure-directory/passwd.txt
realm: (Optional) The realm of the user ID used for the validate_session_profile test. For example, /customers.

Example:

$ ./agentadmin --Vi agent_1 demo passwd.txt /
Saving output to /web_agents/apache24_agent/bin/../log/validate_xxx.log

Running configuration validation for agent_1:

Agent instance is configured with 1 naming.url value(s):
1. https://am.example.com:8443/am is valid
selected https://am.example.com:8443/am as naming.url value
validate_bootstrap_configuration: ok
validate_ssl_libraries: ok
validate_agent_login: ok
get_allocator_blockspace_sz(): trying for configured cache size 16777216 bytes
validate_system_resources: ok
validate_session_profile: ok
validate_websocket_connection: ok
validate_worker_init_shutdown: ok

Result: 7 out of 7 tests passed, 0 skipped.

`--v`

Display information about agentadmin build and version numbers, and available system resources.

Example:

AM Web Agent for IIS Server
     Version: 2024.6
     Revision: xxx
     Build machine: xxx
     Build date: xxx

     System Resources:
     total memory size: 7.7GB
     pre-allocated session/policy cache size: 1.0GB
     log buffer size: 128.5MB
     min audit log buffer size: 2MB, max 2.0GB
     total disk size: 162.4GB
     free disk space size: 89.6GB

     System contains sufficient resources (with remote audit log feature enabled).

Installation environment variables

This section lists Web Agent properties that are configured by environment variables, and set during installation.

Use installation environment variables with the agentadmin -V[i] command to validate the installation with different parameters:

Linux
Windows

$ AM_PROXY_HOST=proxy.host.net AM_PROXY_PORT=8080 AM_PROXY_USER=user AM_PROXY_PASSWORD=pass ./agentadmin --Vi.

C:\>set AM_PROXY_HOST=proxy.host.net
C:\>set AM_PROXY_PORT=8080
C:\>set AM_PROXY_USER=user
C:\>set AM_PROXY_PASSWORD=pass
C:\>agentadmin.exe --Vi agent_1

For information about other environment variables, refer to Environment variables.

AM_PROXY_HOST

The proxy FQDN, when AM and the agent communicate through a proxy configured in forward proxy mode.

AM_PROXY_PASSWORD

The agent password, when AM and the agent communicate through a proxy configured in forward proxy mode, and the proxy requires that the agent authenticates using Basic Authentication.

AM_PROXY_USER

The agent username, when AM and the agent communicate through a proxy configured in forward proxy mode, and the proxy requires that the agent authenticates using Basic Authentication.

AM_PROXY_PORT

The proxy port number, when AM and the agent communicate through a proxy configured in forward proxy mode.

APACHE_RUN_USER

The user running the Apache HTTP or IBM HTTP Server. Set this variable before installation when an Apache user is not defined in httpd.conf. This can be the case in non Red Hat Enterprise Linux-based distributions.

APACHE_RUN_GROUP

The group to which the user running the Apache HTTP Server or IBM HTTP Server belongs. Set this variable before installation when an Apache group is not defined in httpd.conf. This can be the case in non Red Hat Enterprise Linux-based distributions.

AM_SSL_SCHANNEL

Use for Windows only, when TLS/SSL is configured in AM or the agent web server.

A flag for whether the agent installation process should use the Windows Secure Channel API:

0. Disable Windows Secure Channel API support. The agent uses OpenSSL libraries instead.

Ensure that the OpenSSL libraries are in the appropriate place, as specified in the OpenSSL library location by operating system table.
1. Enable Windows Secure Channel API support.

AM_SSL_KEY

Use for OpenSSL only, when TLS/SSL is configured in AM or the agent web server.

When AM is configured to perform client authentication, this environment variable specifies a PEM file that contains the private key corresponding to the certificate specified in the AM_SSL_CERT environment variable.

For example:

Unix
Windows

/opt/certificates/client-private-key.pem

C:\Certificates\client-private-key.pem

AM_SSL_PASSWORD

Use for OpenSSL only, when TLS/SSL is configured in AM or the agent web server.

When AM is configured to perform client authentication, this environment variable specifies the obfuscated password of the private key configured in the AM_SSL_KEY variable. Configure this variable only if the private key is password-protected.

To obfuscate the password, use the agentadmin --p command:

Unix
Windows

$ /path/to/web_agents/agent_type/bin/> agentadmin --p "Encryption Key" “cat certificate_password.file”

Encrypted password value: zck...jtc=com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p "Encryption_Key" "Certificate_File_Password"
Encrypted password value: zck+6RKqjtc=

AM_SSL_CIPHERS

Use for OpenSSL only, when TLS/SSL is configured in AM or the agent web server.

The list of ciphers to support. The list consists of one or more cipher strings separated by colons, as defined in the man page for ciphers at http://www.openssl.org.

For example, HIGH:MEDIUM.

AM_SSL_CERT

Use when TLS/SSL is configured in AM or the agent web server.

When AM is configured to perform client authentication, this environment variable specifies a PEM file that contains the certificate chain for the agent.

For example, /opt/certificates/client-cert.pem, C:\Certificates\client-cert.pem (Windows with OpenSSL), or Cert:\LocalMachine\My location (Windows with the Windows Secure Channel API).

AM_SSL_CA

When configuring the agent to validate AM’s certificate, this environment variable specifies a PEM file that contains the certificates required to validate AM’s server certificate. For example, /opt/certificates/ca.pem, C:\Certificates\ca.pem (Windows with OpenSSL), or Cert:\LocalMachine\Ca (Windows with the Windows Secure Channel API).

Deploy Web Agent with Docker

The example in this section provides a Dockerfile and instructions to deploy Apache Web Agent to extend and protect an application. Adapt the information for other agent containers.

Consider the following limitations:

The Dockerfile doesn’t manage logs, so agent logs are lost when the Docker container is killed. Manage logs independently of the Dockerfile in the following ways, according to your environment:
- Store logs persistently to a volume
- Store logs to a host machine
- Tail logs into STDOUT or STDERR so that Docker can collect the data
The Dockerfile isn’t suitable for local configuration mode and doesn’t update bootstrap properties. The agent must be configured to operate in the default Centralized configuration mode. Learn more from Location of Agent Configuration Repository.

Deploy Apache Web Agent example

Build a Docker image of your application. This example uses a sample application called fr-sample-app:1.0.
In Advanced Identity Cloud or AM, set up an agent profile and policy. For more information, refer to Advanced Identity Cloud’s Prepare for installation or AM’s Prepare for installation.

This example uses the following configuration:
- AM URL: https://am.example.com:8443/am
- AM realm: top-level
- Agent URL: https://agent.example.com:443
- Agent profile name: web-agent
- Agent profile password: password
- Policy set and policy: Allow HTTP GET and POST for all authenticated users.
Create a local folder for the agent .zip file, the Dockerfile, and the agent profile password—they must be in the same folder. This example uses /path/to/docker.
Download the agent .zip file to the local folder.

Create a file containing the agent profile password. The filename in this example is agent_secret and the password is password.

/path/to/docker$ cat > agent_secret
password
CTRL+D

Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example, by using a password manager.

Create the following Dockerfile in /path/to/docker/Dockerfile. Arguments are provided by the build command.

# Application Docker image
ARG BASE_DOCKER_IMAGE
FROM ${BASE_DOCKER_IMAGE}

# Install and unzip the application, required for unpacking the agent build.
# Not required if the base image is already unzipped.
# For non-Debian Linux distributions, use the appropriate package manager.
RUN apt-get update && \
	apt-get install unzip --no-install-recommends -y && \
	apt-get clean

# Define the build arguments.
# Arguments without default values must be specified in the build command.
ARG AGENT_VERSION
ARG AGENT_ZIP_FILE=web-agent-${AGENT_VERSION}-Apache_v24_Linux_64bit.zip
ARG AGENT_HOME=/opt
ARG AM_URL
ARG APACHE_CONF=/usr/local/apache2/conf/httpd.conf
ARG AGENT_URL=http://agent.dummy.url:80
ARG AGENT_REALM=/
ARG AGENT_PROFILE

# Copy the agent .zip file to the Docker directory where the agent is installed.
COPY ${AGENT_ZIP_FILE} ${AGENT_HOME}/${AGENT_ZIP_FILE}

# Unzip the agent and delete the .zip file
RUN cd ${AGENT_HOME} && \
	unzip ./${AGENT_ZIP_FILE} && \
	rm -rf ./${AGENT_ZIP_FILE}

# Install the agent and mount the file containing the agent password
RUN --mount=type=secret,id=agent_secret,required=true \
	"${AGENT_HOME}"/web_agents/apache24_agent/bin/agentadmin --s \
	"${APACHE_CONF}" \
	"${AM_URL}" \
	"${AGENT_URL}" \
	"${AGENT_REALM}" \
	"${AGENT_PROFILE}" \
	"/run/secrets/agent_secret" \
	--changeOwner \
	--forceInstall

Find values for the following arguments that correspond to your application and environment:
- agent_secret: The name of the file containing the agent profile password.
- BASE_DOCKER_IMAGE: The name and path to the base image of your application.
- AGENT_VERSION: The agent version in the Docker image.
- AGENT_ZIP_FILE: Name of the agent .zip file. Default: Derived from AGENT_VERSION.
- AGENT_HOME: Docker directory where the agent is installed. Default: /opt.
- AM_URL: Advanced Identity Cloud or AM server URL including port number.
- AGENT_URL: Agent URL. Default: `http://agent.dummy.url:80`.
- APACHE_CONF: Path to the Apache server configuration. Default: /usr/local/apache2/conf/httpd.conf.
- AGENT_REALM: Advanced Identity Cloud or AM realm containing the agent profile.
- AGENT_PROFILE: Agent profile name. Default /.

With a Docker daemon running, build the Docker image with the following command, replacing the example values with your own values:

/path/to/docker$ docker build --secret id=agent_secret \
  --build-arg BASE_DOCKER_IMAGE=fr-sample-app:1.0 \
  --build-arg AGENT_VERSION=2024.6 \
  --build-arg AGENT_ZIP_FILE=web-agent-2024.6-Apache_v24_Linux_64bit.zip \
  --build-arg AGENT_HOME=/opt \
  --build-arg AM_URL=https://am.example.com:8443/am \
  --build-arg AGENT_URL=https://agent.example.com:443 \
  --build-arg APACHE_CONF=/etc/httpd/conf/httpd.conf \
  --build-arg AGENT_REALM=/ \
  --build-arg AGENT_PROFILE=web-agent \
  --tag agent-image:2024.6 .

...
 => => writing image sha256:803...ada  0.0s
 => => naming to docker.io/library/web-agent:2023.11

Run the container:

/path/to/docker$ docker run -it --name apache24-agent -p 80:80 web-agent:2024.6

... Apache/2.4.58 (Unix) AM Web Agent/2024.6 configured -- resuming normal operations
... Command line: 'httpd -D FOREGROUND'

Access your application through the agent at https://agent.example.com:443. Access is managed by Advanced Identity Cloud or AM according to the policy configured for the agent profile.

This example displays the Advanced Identity Cloud or AM login in page. When you log in as a user, you access the sample application.

Upgrade and rollback

To upgrade or roll back an agent Docker container to a different agent version:

Build a new Docker container with the different agent version, using a tag name that corresponds to the version.
Replace the Docker image tag in your environment.

1. The root agent profile refers to the agent installation performed in Install Apache or IBM HTTP Web Agent and required for installation on virtual hosts.

2. The root agent profile refers to the agent installation performed in Install Apache or IBM HTTP Web Agent and required for installation on virtual hosts.

Web Agents 2024.6

Installation

Example installation for this guide

Prepare for installation

Before you install

Download and unzip Web Agent

Pre-installation tasks

Create agent profiles

Create an agent profile for a single agent instance

Create an agent profile for multiple agent instances when post data preservation is enabled

Create an agent profile group

Inherit properties from an agent profile group

Authenticate agents to the identity provider

Authenticate agents to Advanced Identity Cloud

Authenticate agents to AM

Apache and IBM HTTP Web Agent

Install Apache or IBM HTTP Web Agent

Tune multi-processing modules

Install interactively

Install on a virtual host

Install silently

Check the installation

Install in a subrealm

Configure error logs

Configure Apache or IBM HTTP Web Agent

AmAgent directive to switch the agent on or off

Example where AmAgent is On globally and Off for specific directories

AmAgent is Off globally and On for specific server locations

AmAuthProvider directive to use Apache as the enforcement point

When AmAuthProvider is On and the request doesn’t match a not-enforced rule

When AmAuthProvider is On and the request matches a not-enforced rule

When AmAuthProvider is On and Require AmAuth is not specified

Example where AmAuthProvider is Off globally and On for specific directories

Apache as a reverse proxy

IIS and ISAPI Web Agent

Install IIS or ISAPI Web Agent interactively

Install IIS or ISAPI Web Agent silently

Enable and disable IIS Web Agent

Disable and enable Web Agent on an IIS site or application

Disable and enable agent protection for child applications

Enable support for basic authentication and password replay

Microsoft issues

Configure basic authentication and password replay support

Install in a subrealm

NGINX Plus Web Agent

Install NGINX Plus Web Agent

Install NGINX Plus Web Agent interactively

Install NGINX Plus Web Agent silently

Complete the NGINX Plus Web Agent installation

Check the NGINX Web Agent installation

Install in a subrealm

Configure NGINX Plus Web Agent

NGINX directives

openam_agent

openam_configuration

openam_threadpool

openam_agent_instance

Examples

NGINX as a reverse proxy

Post-installation

Review directories for configuration and logs

Validate the agent instance

Configure shared runtime resources and memory

Choose whether to share resources

Configure Apache agent groups

Configure NGINX Plus agent groups

Secure communication between the agent and AM

Secure internal communication with OpenSSL

Configure server-side and client-side validation using OpenSSL

Secure communication with the Windows Secure Channel API

Configure server-side and client-side validation using the Windows built-in Secure Channel API

Support load balancers and reverse proxies between clients and agents

Configure audit logging

Configure audit logging for the agent

Configure AM to sign authentication information

Configure AM secret labels for the agents' OAuth 2.0 provider

Secure communication between Web Agent and AM

Remove Web Agent

Remove Apache Web Agent

Remove IIS or ISAPI Web Agent

`AmAgent` directive to switch the agent on or off

Example where `AmAgent` is `On` globally and `Off` for specific directories

`AmAgent` is `Off` globally and `On` for specific server locations

`AmAuthProvider` directive to use Apache as the enforcement point

When `AmAuthProvider` is `On` and the request doesn’t match a not-enforced rule

When `AmAuthProvider` is `On` and the request matches a not-enforced rule

When `AmAuthProvider` is `On` and `Require AmAuth` is not specified

Example where `AmAuthProvider` is `Off` globally and `On` for specific directories

`openam_agent`

`openam_configuration`

`openam_threadpool`

`--i`

`--s`

`--n`

`--l`

`--g`

`--e`

`--d`

`--o`

`--r`

`--k`

`--p`

`--V[i]`

`--v`