NGINX Plus Web Agent
Install NGINX Plus Web Agent
Examples use the NGINX Plus R31 agent path. For other supported versions, replace the R31 agent path with the required version. Learn more about supported versions of NGINX in Other requirements.
Consider the following for NGINX Plus 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. Learn more in Troubleshoot.
-
The agent and NGINX must load the same version of the OpenSSL libraries. If you have multiple supported versions of OpenSSL installed, you could experience stability issues when using the Web Agent.
Use the standard
ldconfig
utility to configure the dynamic linker, or set theLD_LIBRARY_PATH
variable in NGINX to ensure the same version is loaded.
Install NGINX Plus Web Agent interactively
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the server where you plan to install the agent.
-
Make sure AM is running.
-
Run the
agentadmin --i
command to install the agent:$ cd /web_agents/nginx31_agent/bin/ $ ./agentadmin --i
-
When prompted, enter information for your deployment.
To cancel the installation at any time, press Ctrl+C. -
Enter the full path to the NGINX Plus server configuration file,
nginx.conf
:Enter the complete path to your NGINX server configuration file [ q or 'ctrl+c' to exit ] [nginx.conf]:/etc/nginx/nginx.conf
-
The installer can import settings from an existing web agent to the new installation and skips prompts for any values present in the existing configuration file. You will be required to re-enter the agent profile 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 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
-
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, enter
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, enter
yes
to proceed with installation:Installation parameters: AM URL: https://am.example.com:8443/am Agent URL: http://www.example.com:80 Agent Profile name: nginx_agent Agent realm/organization name: / Agent Profile password source: /secure-directory/pwd.txt Confirm configuration (yes/no): [no]: yes Validating… Validating… Success. Cleaning up validation data… Creating configuration… In order to complete the installation of the agent, update the configuration file /etc/nginx/nginx.conf if this is the first agent in the installation, please insert the following directives into the top section of the NGINX configuration load_module /web_agents/nginx31_agent/lib/openam_ngx_auth_module.so; then insert the following directives into the server or location NGINX configuration sections that you wish this agent to protect: openam_agent on; openam_agent_configuration /web_agents/nginx31_agent/instances/agent_1/config/agent.conf; Please ensure that the agent installation files have read/write permissions for the NGINX server’s user Please press any key to continue. Installation complete.
Each agent instance has a numbered configuration and logs directory. The first agent configuration and logs are located in
/web_agents/nginx31_agent/instances/agent_1/
.
-
-
Finish installation as described in Complete the NGINX Plus Web Agent Installation.
Install NGINX Plus Web Agent silently
Use the agentadmin --s
command for silent installation.
You can find details about the options in
agentadmin command.
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the server where you plan to install the agent.
-
Make sure AM is running.
-
Run the
agentadmin --s
command with the required arguments. For example:$ agentadmin --s \ "/etc/nginx/nginx.conf" \ "https://am.example.com:8443/am" \ "http://www.example.com:80" \ "/" \ "nginx_agent" \ "/secure-directory/pwd.txt" Web Agent for NGINX Server installation. Validating… Validating… Success. Cleaning up validation data… Creating configuration… In order to complete the installation of the agent, update the configuration file /etc/nginx/nginx.conf if this is the first agent in the installation, please insert the following directives into the top section of the NGINX configuration load_module /web_agents/nginx31_agent/lib/openam_ngx_auth_module.so; then insert the following directives into the server or location NGINX configuration sections that you wish this agent to protect: openam_agent on; openam_agent_configuration /web_agents/nginx31_agent/instances/agent_3/config/agent.conf; Please ensure that the agent installation files have read/write permissions for the NGINX server’s user Please press any key to continue.
-
Finish the installation as described in Complete the NGINX Plus Web Agent Installation.
Complete the NGINX Plus Web Agent installation
After interactive or silent installation, follow these steps to complete the installation.
-
Edit the NGINX Plus server configuration file
nginx.conf
to load the agent moduleopenam_ngx_auth_module.so
:$ vi nginx.conf user nginx; worker_processes auto; error_log /var/log/nginx/error.log notice; pid /var/run/nginx.pid; load_module /web_agents/nginx31_agent/lib/openam_ngx_auth_module.so; …
-
Add and
openam_agent
directive at the global level ofnginx.conf
to set the agent ason
. Learn more in openam_agent. -
Give the user or group running the NGINX Plus server appropriate permissions for the following directories:
-
Read permission:
/web_agents/nginx31_agent/lib
-
Read and write permission:
-
/web_agents/nginx31_agent/instances/agent_nnn
-
/web_agents/nginx31_agent/log
-
Apply execute permissions on the folders listed above, recursively, for the user that runs the NGINX Plus server.
To determine which user or group is running the NGINX Plus server, check the
User
directive in the NGINX Plus server configuration file.Failure to set permissions causes issues, such as the NGINX Plus server not starting up, getting a blank page when accessing a protected resource, or the web agent generating errors during log file rotation.
You could encounter the same issues if SELinux is enabled in enforcing
mode and it is not configured to allow access to agent directories. Learn more in Troubleshoot. -
-
Start the server.
The NGINX Plus server only sets the REMOTE_USER
variable if the request contains an HTTP Authorization header, but the NGINX agent does not set an an HTTP Authorization header after the user has authenticated. Therefore, if you need to set the variable so CGI scripts can use it, configure the agent to create a custom header with the required attribute and then configure the NGINX Plus server to capture that header and convert it into theREMOTE_USER
variable.
Check the NGINX Web Agent installation
-
After you start the server, check the server error log to make sure startup completed successfully:
2021… [info] 31#31: agent worker startup complete
-
Make an HTTP request to a resource protected by the agent, then check the
/web_agents/nginx23_agent/log/system_0.log
file to verify that no startup errors occurred:Web Agent Version: 2024.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
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 NGINX Plus Web Agent
NGINX directives
Add NGINX directives to the 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 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_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
ison
globally but off` for one HTTP location-
When openam_agent
configuration isoff
, configure the server location/agent
ason
. This allows AM to redirect requests to the/agent
endpoint after authentication.In the following example
nginx.conf
:-
agent_1
in theserver
context protects the/
and/marketplace`location
contexts -
No agent instance protects the
/customers`location
context.
server { listen 80 default_server; server_name localhost; openam_agent on; openam_agent_configuration /web_agents/nginx31_agent/instances/agent_1/config/agent.conf; #charset koi8-r; #access_log /var/log/nginx/log/host.access.log main; location / { root /www/; index index.html index.htm; } location /customers { openam_agent off root /www/customers index index.html } location /market { root /www/marketplace index index.html } }
-
- Different agent instances protect different parts of the deployment
-
In the following example
nginx.conf
:-
agent_1
at theserver
context protects the/
and/marketplace`location
contexts -
agent_2
protects the/customers`location
context
server { listen 80 default_server; server_name localhost; openam_agent on; openam_agent_configuration /web_agents/nginx31_agent/instances/agent_1/config/agent.conf; #charset koi8-r; #access_log /var/log/nginx/log/host.access.log main; location / { root /www/; index index.html index.htm; } location /customers { openam_agent on; openam_agent_configuration /web_agents/nginx31_agent/instances/agent_2/config/agent.conf; root /www/customers index index.html } location /market { root /www/marketplace index index.html } }
-
NGINX as a reverse proxy
This section contains an example configuration of NGINX as a reverse proxy between AM and Web Agent. You can use any reverse proxy that supports the WebSocket protocol.
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
nginx.conf
. -
Edit
nginx.conf
to add directives to the context you want to protect:server { ... location /am { proxy_set_header Host $host proxy_pass http://hostname:port/am; proxy_http_version 1.1; proxy_set_header Connection ""; # to allow keep alives to work # } location /am/notifications/ { proxy_pass http://hostname:port/am/notifications; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_set_header Host $host; } ... }
-
Ensure the user or group running the NGINX Plus server has the appropriate permissions over the following directories:
-
Read Permission:
/web_agents/nginx31_agent/lib
-
Read and Write Permission:
-
/web_agents/nginx31_agent/instances/agent_nnn
-
/web_agents/nginx31_agent/log
-
-
-
Restart the reverse proxy instance.
-
Configure AM to recover the forwarded header configured in the reverse proxy.
-
Review other configuration that a reverse proxy environment can require. Learn more in Agent connection to AM through a load balancer/reverse proxy