Install Web Agent

Install Apache Web Agent

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

Consider the following points before you install:

The agent replaces authentication functionality provided by Apache, for example, the mod_auth_* modules. Integration with built-in Apache authentication directives, such as AuthName, FilesMatch, and Require is not supported.
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.

Tune Apache Multi-Processing Modules

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

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

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

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

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

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

Install Apache Web Agent Interactively

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

Run agentadmin --install to install the agent:

Linux
Windows

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

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

You are prompted to read and accept the software license agreement for the agent installation.

When prompted, enter information for your deployment.

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

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

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

When installing the agent as the root user, the agentadmin command can change the directory ownership to the same user and group specified in the Apache configuration. Determine which user or group is running the Apache server by viewing the Group and User directives in the Apache server configuration file. Enter yes to alter directory ownership, press Enter to accept the default: no.
```
Change ownership of created directories using
User and Group settings in httpd.conf
[ q or 'ctrl+c' to exit ]
(yes/no): [no]:yes
```
Failure to set permissions causes issues, such as the Apache server not starting up, getting a blank page when accessing a protected resource, or the web agent generating errors during log file rotation.
The installer can import settings from an existing Web Agent on the new installation and skip prompts for values present in the existing configuration file. You are required to re-enter the agent profile password.

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 agents will use. Ensure that the deployment URI is specified.

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For information about setting up an environment for reverse proxies, see Configuring Apache HTTP Server as a Reverse Proxy Example.

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

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 given to the agent profile created in AM.

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

Enter the AM realm containing the agent profile. 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:/tmp/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 settings are correct, type yes to proceed with installation.
```
Installation parameters:

   OpenAM URL: http://openam.example.com:8080/openam
   Agent URL: http://www.example.com:80
   Agent Profile name: webagent4
   Agent realm/organization name: /
   Agent Profile password source: /tmp/pwd.txt

Confirm configuration (yes/no): [no]:yes
Validating…
Validating… Success.
Cleaning up validation data…
Creating configuration…
Installation complete.
```
On successful completion, the installer adds the agent as a module to the Apache configuration file. You can find a backup configuration file in the Apache configuration directory, called http.conf_amagent_date_and_time_of_installation.

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

Note the location of the configuration files and logs:
- config/: Bootstrap properties to connect to AM and download the configuration. This directory contains properties that are used only in local configuration mode.
- logs/audit/: Audit log directory. Used only if Audit Log Location is LOCAL or ALL.
- 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 container which is being used, 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.
(Unix only) Configure shared runtime resources and shared memory. For more information, see Configure Shared Runtime Resources and Memory.
(Unix only) Ensure the user or group running the Apache HTTP server has the appropriate permissions on the following directories:
- Read permission: /web_agents/apache24_agent/lib
- Read and write permission:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
- Execute permission to validate an installation by using the agentadmin --V[i] command:
  - /web_agents/apache24_agent/instances/agent_nnn
  - /web_agents/apache24_agent/log
  To determine which user or group is running the Apache HTTP server, check the Group and User directives in the Apache HTTP server configuration file, httpd.conf. When permission are incorrect, the following errors can occur:
- Apache HTTP doesn’t start up
- Access to a protected resource returns a blank page
- The agent generates errors during log file rotation
The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.

+
Run the configuration validator for the new agent instance you just created.

The validator ensures, among other things, that WebSocket communication between your web server and AM is possible.

Perform the following steps to find the agent instance and run the agentadmin command:
1. Change directories to the location where your web agent instances are installed. For example, /path/to/web_agents/agent_name/instances.
2. Find the agent instance you just created, for example, agent_2.
3. Run the agentadmin --Vi command. On Unix systems, ensure that you run the command as the user running the web server processes.
  Linux
  
  Windows
  $ sudo -u daemon /path/to/web_agents/agent_name/bin/agentadmin --Vi \ agent_2 am_user /path/to/am_user_password_file / Running configuration validation for agent_2: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam 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.
  
  C:\web_agents\iis_agent\bin> agentadmin --Vi ^ agent_2 am_user C:\path\to\am_user_password_file /
  Do not use the --Vi option to check the instance configuration while the agent is actively protecting a website, as the agent instance may become unresponsive. Instead, use the --V option only. For more information about the --Vi option, see agentadmin Command.
  
  If validate_websocket_connection is not ok, ensure your web server and the network infrastructure between the web server and the AM servers support WebSockets.
  
  Web Agent requires WebSocket communication.
Start the Apache server.
Check the installation, as described in Check the Apache Web Agent Installation.

Install Apache Web Agents on a Virtual Host

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

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

To Prepare for Web Agent Installation on an Apache Virtual Host

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

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

To Install the Apache Web Agent on Apache Virtual Hosts

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

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

Review the information in Before You Install, and perform the steps in Preinstallation Tasks.
Shut down the Apache server where you plan to install the agent.

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

Linux
Windows

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

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

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

+
Run the configuration validator for the new agent instance you just created.

The validator ensures, among other things, that WebSocket communication between your web server and AM is possible.

Perform the following steps to find the agent instance and run the agentadmin command:
1. Change directories to the location where your web agent instances are installed. For example, /path/to/web_agents/agent_name/instances.
2. Find the agent instance you just created, for example, agent_2.
3. Run the agentadmin --Vi command. On Unix systems, ensure that you run the command as the user running the web server processes.
  Linux
  
  Windows
  $ sudo -u daemon /path/to/web_agents/agent_name/bin/agentadmin --Vi \ agent_2 am_user /path/to/am_user_password_file / Running configuration validation for agent_2: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam 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.
  
  C:\web_agents\iis_agent\bin> agentadmin --Vi ^ agent_2 am_user C:\path\to\am_user_password_file /
  Do not use the --Vi option to check the instance configuration while the agent is actively protecting a website, as the agent instance may become unresponsive. Instead, use the --V option only. For more information about the --Vi option, see agentadmin Command.
  
  If validate_websocket_connection is not ok, ensure your web server and the network infrastructure between the web server and the AM servers support WebSockets.
  
  Web Agent requires WebSocket communication.
Start the Apache server.
Check the installation, as described in Check the Apache Web Agent Installation.

Install Apache Web Agent Silently

Use the agentadmin --s command for silent installation. For information about the options, see agentadmin Command.

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

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

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

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

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

+
Run the configuration validator for the new agent instance you just created.

The validator ensures, among other things, that WebSocket communication between your web server and AM is possible.

Perform the following steps to find the agent instance and run the agentadmin command:
1. Change directories to the location where your web agent instances are installed. For example, /path/to/web_agents/agent_name/instances.
2. Find the agent instance you just created, for example, agent_2.
3. Run the agentadmin --Vi command. On Unix systems, ensure that you run the command as the user running the web server processes.
  Linux
  
  Windows
  $ sudo -u daemon /path/to/web_agents/agent_name/bin/agentadmin --Vi \ agent_2 am_user /path/to/am_user_password_file / Running configuration validation for agent_2: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam 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.
  
  C:\web_agents\iis_agent\bin> agentadmin --Vi ^ agent_2 am_user C:\path\to\am_user_password_file /
  Do not use the --Vi option to check the instance configuration while the agent is actively protecting a website, as the agent instance may become unresponsive. Instead, use the --V option only. For more information about the --Vi option, see agentadmin Command.
  
  If validate_websocket_connection is not ok, ensure your web server and the network infrastructure between the web server and the AM servers support WebSockets.
  
  Web Agent requires WebSocket communication.
Start the Apache server.
Check the installation, as described in Check the Apache Web Agent Installation.

Check the Apache Web Agent Installation

Check the Apache HTTP server error log after you start the server to make sure startup completed successfully:

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

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

Install the IIS Web Agent

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 1. 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
```
You are prompted to read and accept the software license agreement for the agent installation.

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://openam.sample.com:58080/openam)
[ q or 'ctrl+c' to exit ]
OpenAM server URL: https://openam.example.com:8443/openam

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 AM realm containing the agent profile. 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:

   OpenAM URL: https://openam.example.com:8443/openam
   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\.

Note the location of the configuration files and logs:
- config/: Bootstrap properties to connect to AM and download the configuration. This directory contains properties that are used only in local configuration mode.
- logs/audit/: Audit log directory. Used only if Audit Log Location is LOCAL or ALL.
- 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 container which is being used, 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.
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, see agentadmin Command.
  
  When permissions are not set correctly, errors such as getting a blank page when accessing a protected resource can occur.
Run the configuration validator for the new agent instance you just created.

The validator ensures, among other things, that WebSocket communication between your web server and AM is possible.

Perform the following steps to find the agent instance and run the agentadmin command:
1. Change directories to the location where your web agent instances are installed. For example, /path/to/web_agents/agent_name/instances.
2. Find the agent instance you just created, for example, agent_2.
3. Run the agentadmin --Vi command. On Unix systems, ensure that you run the command as the user running the web server processes.
  Linux
  
  Windows
  $ sudo -u daemon /path/to/web_agents/agent_name/bin/agentadmin --Vi \ agent_2 am_user /path/to/am_user_password_file / Running configuration validation for agent_2: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam 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.
  
  C:\web_agents\iis_agent\bin> agentadmin --Vi ^ agent_2 am_user C:\path\to\am_user_password_file /
  Do not use the --Vi option to check the instance configuration while the agent is actively protecting a website, as the agent instance may become unresponsive. Instead, use the --V option only. For more information about the --Vi option, see agentadmin Command.
  
  If validate_websocket_connection is not ok, ensure your web server and the network infrastructure between the web server and the AM servers support WebSockets.
  
  Web Agent requires WebSocket communication.
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, see 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://openam.example.com:8443/openam" ^
  "http://iis.example.com:80" ^
  "/" ^
  "iisagent" ^
  "c:\pwd.txt" ^
  --acceptLicence

OpenAM 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, see agentadmin Command.
  
  When permissions are not set correctly, errors such as getting a blank page when accessing a protected resource can occur.
Run the configuration validator for the new agent instance you just created.

The validator ensures, among other things, that WebSocket communication between your web server and AM is possible.

Perform the following steps to find the agent instance and run the agentadmin command:
1. Change directories to the location where your web agent instances are installed. For example, /path/to/web_agents/agent_name/instances.
2. Find the agent instance you just created, for example, agent_2.
3. Run the agentadmin --Vi command. On Unix systems, ensure that you run the command as the user running the web server processes.
  Linux
  
  Windows
  $ sudo -u daemon /path/to/web_agents/agent_name/bin/agentadmin --Vi \ agent_2 am_user /path/to/am_user_password_file / Running configuration validation for agent_2: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam 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.
  
  C:\web_agents\iis_agent\bin> agentadmin --Vi ^ agent_2 am_user C:\path\to\am_user_password_file /
  Do not use the --Vi option to check the instance configuration while the agent is actively protecting a website, as the agent instance may become unresponsive. Instead, use the --V option only. For more information about the --Vi option, see agentadmin Command.
  
  If validate_websocket_connection is not ok, ensure your web server and the network infrastructure between the web server and the AM servers support WebSockets.
  
  Web Agent requires WebSocket communication.
(Optional) If you installed the agent in a parent application, enable it for its child applications by following the steps in To Disable And Enable Web 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, see To Disable And Enable Web Agent Protection for Children 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

OpenAM 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 Web 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 LOGON_USER. The agent either sets all three, or does not set any of them.

When Logon and Impersonation is enabled, the agent performs Windows logon 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-SSL connection.

Summary: Enable SSL encryption 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 console, 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 the Authentication Post Processing Classes property, add the class com.sun.identity.authentication.spi.ReplayPasswd.
Restart AM or the container where it runs.
In the AM console 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 logon 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 then enable Show Password in HTTP Header.
(Optional) If you require Windows logon, or you need to use basic authentication with SharePoint or OWA, then you must configure Active Directory as a user data store, and you must configure the IIS web agent profile User ID Parameter and User ID Parameter Type so that the web agent requests AM to provide the appropriate account information from Active Directory in its policy response.

Skip this step if you do not use SharePoint or OWA and no Windows logon is required.

Make sure the AM data store is configured to use Active Directory as the user data store.

In the AM console under Realms > Realm Name > Applications > Agents > Web > Agent Name > OpenAM Services > Policy Client Service, set User ID Parameter and User ID Parameter Type, and then save your work. For example if the real username for Windows domain logon 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 the 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 web agent can set the HTTP headers REMOTE_USER, AUTH_USER, or LOGON_USER and USER_PASSWORD with Active Directory attribute values suitable for Windows logon, setting the remote user, and so forth.
(Optional) To access Microsoft Office from SharePoint pages, configure AM to persist the authentication cookie. For information, see "Persistent Cookie Module" or " Persistent Cookie Decision Node in AM’s Authentication and Single Sign-On Guide.

Install NGINX Plus Web Agent

Examples use the NGINX Plus R25 agent path. For other supported versions, replace the R25 agent path with the required version. For information about supported versions of NGINX, see Supported Operating Systems and Web Servers.

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/nginx25_agent/bin/
$ ./agentadmin --i
```
You are asked to read and accept the software license agreement for the agent installation.

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://openam.sample.com:58080/openam)
 [ q or 'ctrl+c' to exit ]
 OpenAM server URL:https://openam.example.com:8443/openam

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 AM realm containing the agent profile. 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:/tmp/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:

 OpenAM URL: https://openam.example.com:8443/openam
 Agent URL: http://www.example.com:80
 Agent Profile name: nginx_agent
 Agent realm/organization name: /
 Agent Profile password source: /tmp/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/nginx25_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/nginx25_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/nginx25_agent/instances/agent_1/.

Note the location of the configuration files and logs:
- config/: Bootstrap properties to connect to AM and download the configuration. This directory contains properties that are used only in local configuration mode.
- logs/audit/: Audit log directory. Used only if Audit Log Location is LOCAL or ALL.
- 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 container which is being used, 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.
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, see 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://openam.example.com:8443/openam" \
 "http://www.example.com:80" \
 "/" \
 "nginx_agent" \
 "/tmp/pwd.txt" \
 --acceptLicence
OpenAM 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/nginx25_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/nginx25_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, following these steps to complete the installation.

Edit the NGINX Plus server configuration file nginx.conf to load the web agent module openam_ngx_auth_module.so, if it is not already configured:

$ 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/nginx25_agent/lib/openam_ngx_auth_module.so;…

Edit the NGINX Plus server configuration file containing the context you want to protect and add web agent directives to it. The following directives are supported:
openam_agent [on | off]
Controls if an agent instance is on or off for a particular http, server, or location context.

Set to on for a context to protect it and its contents. If a context already protected requires a specific web agent configuration, follow the procedures in this section again to create a new web agent instance for it. The installer will configure the next available web agent instance, for example, agent_2.

Set to off for a context to disable the web agent protection for that context and its contents. If the context has a parent, disabling the directive does not affect the protection for the parent.
Example 1

server { listen 80 default_server; server_name localhost; openam_agent on; openam_agent_configuration /web_agents/nginx25_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/nginx25_agent/instances/agent_2/config/agent.conf; root /www/customers index index.html } location /market { root /www/marketplace index index.html } }
The web agent instance agent_1 configured at the server context is protecting the / and /market`location contexts. The location context /customers is protected by a second web agent instance, agent_2.
Example 2

server { listen 80 default_server; server_name localhost; openam_agent on; openam_agent_configuration /web_agents/nginx25_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 } }
The agent instance agent_1 is protecting the server context and the / and /market`location contexts. Protection is disabled for the /customers`location context.
Configure shared runtime resources and shared memory. For more information, see Configure Shared Runtime Resources and Memory.
Ensure the user or group running the NGINX Plus server has the appropriate permissions over the following directories:
- Read Permission: /web_agents/nginx25_agent/lib
- Read and Write Permission:
  - /web_agents/nginx25_agent/instances/agent_nnn
  - /web_agents/nginx25_agent/log
    
    Apply execute permissions on the folders listed above, recursively, for the user that runs the NGINX Plus server.
    
    To determine which user or group is running the NGINX Plus server, check the User directive in the NGINX Plus server configuration file.
    
    Failure to set permissions causes issues, such as the NGINX Plus server not starting up, getting a blank page when accessing a protected resource, or the web agent generating errors during log file rotation.
    
    You may see the same issues if SELinux is enabled in enforcing mode and it is not configured to allow access to agent directories. For more information, see Troubleshooting.
Run the configuration validator for the new agent instance you just created.

The validator ensures, among other things, that WebSocket communication between your web server and AM is possible.

Perform the following steps to find the agent instance and run the agentadmin command:
1. Change directories to the location where your web agent instances are installed. For example, /path/to/web_agents/agent_name/instances.
2. Find the agent instance you just created, for example, agent_2.
3. Run the agentadmin --Vi command. On Unix systems, ensure that you run the command as the user running the web server processes.
  Linux
  
  Windows
  $ sudo -u daemon /path/to/web_agents/agent_name/bin/agentadmin --Vi \ agent_2 am_user /path/to/am_user_password_file / Running configuration validation for agent_2: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam 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.
  
  C:\web_agents\iis_agent\bin> agentadmin --Vi ^ agent_2 am_user C:\path\to\am_user_password_file /
  Do not use the --Vi option to check the instance configuration while the agent is actively protecting a website, as the agent instance may become unresponsive. Instead, use the --V option only. For more information about the --Vi option, see agentadmin Command.
  
  If validate_websocket_connection is not ok, ensure your web server and the network infrastructure between the web server and the AM servers support WebSockets.
  
  Web Agent requires WebSocket communication.

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:
```
OpenAM Web Agent Version: 5.9.1
Revision: ab12cde, Container: NGINX Plus 23 Linux 64bit (Ubuntu20),
Build date: …
```
(Optional) If you have a policy configured, test that the agent is processing requests. For example, make an HTTP request to a resource protected by the agent, and check that you are redirected to {am.abbr} to authenticate. After authentication, AM redirects you back to the resource you tried to access.

Web Policy Agents 5.9.1

Install Web Agent

Install Apache Web Agent

Tune Apache Multi-Processing Modules

Install Apache Web Agent Interactively

Install Apache Web Agents on a Virtual Host

Install Apache Web Agent Silently

Check the Apache Web Agent Installation

Install the 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 Web 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 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