Web Agents 2023.11.2

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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the server where you plan to install the agent.

  3. Make sure AM is running.

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

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

  5. When prompted, enter information for your deployment.

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

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

    2. 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:

    3. Enter the full URL of the AM instance that the agent should connect to:

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

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

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

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

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

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

    8. 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/.

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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the server where you plan to install the agent.

  3. Make sure AM is running.

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

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

  1. 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;
…​

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

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

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

  1. After you start the server, check the server error log to make sure startup completed successfully:

    2021…​ [info] 31#31: agent worker startup complete

  2. 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: …​

  3. (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

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.