Untitled | Web Agents

Installation

This guide describes how to install ForgeRock Access Management Web Agent.

About ForgeRock Identity Platform™ Software

ForgeRock Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. For more information, visit https://www.pingidentity.com.

Example installation for this guide

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

Web Agent installed on http://agent.example.com:80.
Access Management installed on http://am.example.com:8088/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 the AM servers, and between the agent and the client. Configure both AM and the environment before you install the agent. For more information, refer to Configure load balancers and reverse proxies.

Download and unzip Web Agent

Go to the ForgeRock 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.

Agent configuration files are created in /path/to/web_agents/agent_type/instances/agent_n/config/agent.conf. Make sure the path, including the parent path, does not 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 Web Agent only) The backup of the site and application configuration files created after running the agentadmin -g command.
(IIS Web Agent 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 an agent profile in AM using the console:

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: http://am.example.com:8080/am
- Password: password

In AM, add a policy set and policy, to protect resources with the agent, 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 Enabling restricted 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

'password' | Out-File -Encoding ascii pwd.txt

In Windows Explorer, right-click the password file, for example pwd.txt, 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 are true, set up the required environment variables :
- AM is configured to perform client authentication
- The agent web server is to configured to validate AM’s server certificate
For more information, refer to Environment variables.

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. For more information, refer to 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 IDs 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 ID. This secret ID 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 ID. This secret ID 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 IDs:
  1. Configure the new RSA key alias in the am.global.services.oauth2.oidc.agent.idtoken.signing secret ID.
  2. Configure the new HMAC secret in the am.services.oauth2.jwt.authenticity.signing secret ID.
    
    Note that you may already have a secret configured for this secret ID, because it is also used for signing certain OpenID Connect ID tokens and remote consent requests. For more information, refer to Secret ID 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.

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. For more information, refer to 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. For more information, refer to 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 Identity Cloud or AM. For more information, refer to 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 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.

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 agent.conf to map one agent profile to multiple agent instances.

The configuration in agent.conf 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 Identity Cloud

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

You can now authenticate Web Agent to 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 Identity Cloud.

For more information, refer to Identity Cloud’s Journeys.

This section describes how to create a journey to authenticate Web Agent to 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 Identity Cloud, that same journey is used for all instances of Identity Gateway, Java Agent, and Web Agent. Consider this point if you change the journey configuration.

Log in to the 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 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.

For more information, refer to 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 Identity Gateway, 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:

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.

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 Troubleshooting.
By default, 32 agent instances can run at the same time in a single installation. For information about changing the limit, refer to AM_MAX_AGENTS in Environment variables.
(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
```
For more information, refer to 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 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: /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:8080/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 name of the agent profile created in AM:
```
Agent Profile name: 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 profile password:
```
The path to the password file: /secure-directory/pwd.txt
```

Review the configuration:

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

Confirm configuration (yes/no): [no]:
Validating...
Validating... Success.
Cleaning up validation data...
Creating configuration...
Installation complete.

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

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 Creating 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 agent.conf file as follows:
1. 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. Configure the encryption key and password for the virtual host agent, using 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 properties in agent.conf:
    
    Agent Profile Password Encryption Key with the value of the generated encryption key:
    
    com.sun.identity.agents.config.key = YWM...5Nw==
    
    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 Troubleshooting.

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:

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

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

(Unix only) 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 Troubleshooting.

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/2023.11 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: 2023.11
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 Identity Cloud, and you don’t want the agent to take part in protecting AM or 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 "/openam/notifications" "ws://am.example.com:8080/am/notifications" Upgrade=websocket (2)
ProxyPass "/openam" "http://am.example.com:8080/am" (3)
ProxyPassReverseCookieDomain "openam.internal.example.com" "proxy.example.com" (4)
ProxyPassReverse "/openam" "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. For more information, refer to Agent connection to AM through a load balancer/reverse proxy

Install IIS Web Agent

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

Web Agent requires IIS to be run in Integrated mode.
A Web Agent configured for a site or parent application protects any application configured within. The same is true for protected applications containing applications within.

Consider the following restrictions:

Agents configured in a site or parent application do not protect children applications that do not inherit the parent’s IIS configuration.
Agents configured for a site or parent application running under a 64-bit pool do not protect child applications running under 32-bit pools due to architectural differences; 32-bit applications cannot load 64-bit web agent libraries and, therefore, will not be protected.

The same is true for the opposite scenario.

In this case, the child applications require their own web agent installation, as explained in the next item of this list. Both 32-bit and 64-bit agent libraries are supplied with the IIS Web Agent binaries.
If an application requires a specific web 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 web agent instance for it. Configuring a web 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 results in error.
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 the protection on all children applications that do not have a specific agent instance installed on them.
- Disabling the agent in a child application does not disable protection on its parent application.
Agents require that the Application Development component is installed alongside the core IIS services. Application Development is an optional component of the IIS web server. The component provides required infrastructure for hosting web applications.

Figure 2. Adding the application development component to IIS

Install IIS Web Agent interactively

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 agentadmin.exe with the --i switch 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 server configuration and converts the IIS hierarchy 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 web agents will be using. 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 be running 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: http://customers.example.com:80
   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 site configuration.

The installer grants full access permissions on the created instance folder to the user that the selected IIS site is running under, so that log files can be written correctly.

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

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"
  For more information, refer to 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 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.
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" ^
  --acceptLicence

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"
  For more information, refer to 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 by following the steps in Disable and enable agent protection for child applications.

Enable and disable IIS Web Agent

Disable and enable Web Agent on an IIS site or application

The agentadmin command shows only instances of the web agent; to enable or disable the protection of children applications, refer to Disable and enable agent protection for child applications.

Log on to Windows as a user with administrator privileges.

Run agentadmin.exe --l to output a list of the installed web 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 web agent in a site, run agentadmin.exe --d, and specify the ID of the web web 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 web agent in a site, run agentadmin.exe --e, and specify the ID of the web 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 web 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 web agents configured in a site or parent application also protect any applications that are inheriting 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 IIS basic authentication and password replay

The IIS web agent now supports IIS basic authentication and password replay. You must use the appropriate software versions.

Given the proper configuration and with Active Directory as a user data store for AM, the IIS web agent can provide access to the 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 web agent requests IIS server variable values from AM, which gets them from Active Directory. The web 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 does not set any of them.

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

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

The agent does not 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, you must use Microsoft Office 2007 SP2 or later.
For Microsoft SharePoint integration, you must 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 is not 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.

To Configure IIS 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.ReplayPasswd.
Restart AM.
In the AM admin UI go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Advanced
1. In Replay Password Key, enter the encryption key generated in a previous step.
2. For Windows login for user token impersonation, enable Logon and Impersonation.
3. 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 web agent profile User ID Parameter and User ID Parameter Type.
  
  Skip this step if you do not 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

Install NGINX Plus Web Agent

Examples use the NGINX Plus R29 agent path. For other supported versions, replace the R29 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 Troubleshooting.

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/nginx29_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 OpenSSOAgentBootstrap.properties 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/nginx29_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/nginx29_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/nginx29_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" \
 --acceptLicence
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/nginx29_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/nginx29_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/nginx29_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. For more information, refer to openam_agent.
Give the user or group running the NGINX Plus server appropriate permissions for the following directories:
- Read permission: /web_agents/nginx29_agent/lib
- Read and write permission:
  - /web_agents/nginx29_agent/instances/agent_nnn
  - /web_agents/nginx29_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.

+ NOTE: 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 Troubleshooting.

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: 2023.11
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 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 Identity Cloud, if you don’t want the agent to take part in protecting URLs in AM or 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/nginx29_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/nginx29_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/nginx29_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/nginx29_agent/lib
- Read and Write Permission:
  - /web_agents/nginx29_agent/instances/agent_nnn
  - /web_agents/nginx29_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. For more information, refer to Agent connection to AM through a load balancer/reverse proxy

Post-installation tasks

Note the location of configuration files 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 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. For more information, refer to 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. For more information, refer to AM_RESOURCE_PERMISSIONS in Environment variables.

Configure Apache agent groups

To create an Apache agent group, edit the Apache configuration file, /etc/httpd/conf/httpd.conf, to add an AmAgentId directive.

To isolate agents in different web servers hosted on the same machine, set AmAgentId to a different value in each server configuration.

The following example httpd.conf file configures one group with AmAgentId 1, including two virtual hosts. Each virtual host is protected by a different instance of the agent, but 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>

When AmAgentId is not specified for an agent instance, it uses the default value of 0.

To create multiple agent groups in an Apache agent installation, use different values for AmAgentId. In the previous example, you could specify two groups by using AmAgentId 1 and AmAgentId 2.

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

Agent instances Directive configuration Description

Agent instances	Directive configuration	Description
`Agent_1` and `Agent_2`	Not set (defaults to 0)	The instances share runtime resources and policy cache.
`Agent_3`, `Agent_4`, and `Agent_5`	1	The instances share runtime resources and policy cache.
`Agent_6`	2	The instance does not share runtime resources and policy cache with any other instance.

Agent_1 and Agent_2

Not set (defaults to 0)

The instances share runtime resources and policy cache.

Agent_3, Agent_4, and Agent_5

The instances share runtime resources and policy cache.

Agent_6

The instance does not share runtime resources and 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/nginx29_agent/bin/../instances/agent_3/config/agent.conf; openam_agent_instance 2
  …
  location /customers {
    openam_agent on;
    openam_agent_configuration /web_agents/nginx29_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 from 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 or the Apache for Windows Web Agent) Configure the agent to use OpenSSL.
1. Set the bootstrap 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 bootstrap property Server Certificate Trust to false.
3. Set the bootstrap 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 bootstrap 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 bootstrap 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 bootstrap 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 bootstrap 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 bootstrap 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, the IIS and Apache for Windows Web Agent uses 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 ever configured the IIS or Apache for Windows web agent to use OpenSSL libraries, set the bootstrap 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 bootstrap 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 bootstrap 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 bootstrap 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 bootstrap property.
Set the bootstrap 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.

For more information, refer to Configure load balancers and reverse proxies.

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 Setting up 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 ForgeRock 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 ForgeRock Identity Platform using the HTTP header X-ForgeRock-TransactionId. For more information about configuring the header, refer to Configuring the trust transaction header system property in AM’s Security guide.

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

To configure audit logging

This procedure assumes that 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.

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.

Start the Apache HTTP Server.

Remove a single instance of IIS 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 Web Agent.

Remove all instances of IIS 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/nginx29_agent/instances/agent_1
server/site:   /etc/nginx/nginx.conf

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

id:            agent_3
configuration: /web_agents/nginx29_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.

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

Silently, non-interactively, install a new agent instance.

Usage: agentadmin --s web-server-config-file openam-url agent-url realm agent-profile-name agent-profile-password [--changeOwner] [--acceptLicense] [--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.

(Microsoft IIS) The ID number of the IIS site in which to install the web 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 cannot run the agentadmin command as the root user or with the sudo command, you must change the ownership manually.

--acceptLicense

Do not display the license during installation.

--forceInstall

If the agent cannot connect to the specified AM server during installation, proceed with a silent installation instead of exiting.

`--n`

(IIS web 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 existing 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 web agent only) Remove all web agent instances and libraries from an IIS installation.

Usage: agentadmin.exe --g

For more information, refer to To remove Web Agents from IIS.

`--e`

(IIS web agent only) Enable an existing agent instance.

Usage: agentadmin.exe --e agent-instance

For more information, refer to To disable and enable Web Agents.

`--d`

(IIS web agent only) Disable an existing agent instance.

Usage: agentadmin.exe --d agent-instance

For more information, refer to To disable and enable Web Agents.

`--o`

(IIS web 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 an IIS site ID.

"directory"

Specify the directory that would be modified.

[--siteId]

Specify that the agentadmin should use identity_or_siteID as an IIS site ID.

--addAll

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

--removeAll

Remove all IIS application pool identities from the directory’s ACLs. This option is not 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 web agents, the --r option does not remove the web agent libraries since they can be in use by other web agent instances configured on the same site. To remove all web agent instances and libraries, use the --g option instead.

`--k`

Generate a new signing key.

Usage: agentadmin --k

Example:

Unix
Windows

$ cd /web_agents/apache24_agent/bin/
$ ./agentadmin --k
Encryption key value: YWM…5Nw==

C:\> cd web_agents{apache_agent_version}\bin
C:\web_agents{apache_agent_version}\bin> agentadmin --k
Encryption key value: YWM…5Nw==

`--p`

Use a generated encryption key to encrypt a new password.

Usage: agentadmin --p encryption-key password

encryption-key

An encryption key, generated by the agentadmin --k command.

password

The password to encrypt.

Examples:

Unix
Windows

$ ./agentadmin --p "YWM0OThlMTQtMzMxOS05Nw==" "cat newpassword.file"
Encrypted password value: 07b…dO4=

C:\path\to\web_agents{apache_agent_version}\bin> agentadmin.exe --p "YWM0OThlMTQtMzMxOS05Nw==" "newpassword"
Encrypted password value: 07b…dO4=

`--V[i]`

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

This command validates the following points:

The agent can reach the AM server(s) configured in AM Connection URL.
Critical bootstrap properties are set. For more information, see Configuration location.
TLS/SSL libraries are available and that SSL configuration properties are set, if the agent is configured for SSL communication.
The agent can log in to AM to fetch the agent profile.
The system has enough RAM and shared memory.
The agent can log in to AM with the provided user and password credentials.
The agent can decrypt the agent profile password using the encryption key in the agent.conf file.
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 agent only) IIS is configured for running application pools in Integrated mode.

To prevent service outage or an unresponsive agent, run the command only when the agent instance is not 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: 2023.11
     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. For more information, refer to Location of Agent Configuration Repository.

Build a Docker image of your application. This example uses a sample application called fr-sample-app:1.0.
In Identity Cloud or AM, set up an agent profile and policy. For more information, refer to 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: http://agent.example.com:80
- 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: 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: 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=2023.11 \
  --build-arg AGENT_ZIP_FILE=web-agent-2023.11-Apache_v24_Linux_64bit.zip \
  --build-arg AGENT_HOME=/opt \
  --build-arg AM_URL=https://am.example.com:8443/am \
  --build-arg AGENT_URL=http://agent.example.com:80 \
  --build-arg APACHE_CONF=/etc/httpd/conf/httpd.conf \
  --build-arg AGENT_REALM=/ \
  --build-arg AGENT_PROFILE=web-agent \
  --tag agent-image:2023.11 .

...
 => => 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:2023.11

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

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

This example displays the 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 2023.11.2

Installation

About ForgeRock Identity Platform™ Software

Example installation for this guide

Prepare for installation

Before you install

Download and unzip Web Agent

Pre-installation tasks

Configure AM to sign authentication information

Configure AM secret IDs for the agents' OAuth 2.0 provider

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 Identity Cloud

Authenticate agents to AM

Secure communication between Web Agent and AM

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

Install IIS Web Agent

Install IIS Web Agent interactively

Install IIS 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 IIS basic authentication and password replay

Microsoft issues

To Configure IIS basic authentication and password replay support

Install in a subrealm

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 tasks

Note the location of configuration files 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

Remove Web Agent

Remove Apache Web Agent

Remove a single instance of IIS Web Agent

Remove all instances of IIS Web Agent

Remove NGINX Plus 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`