--- title: Configure NGINX Plus Web Agents description: Add NGINX directives to the /etc/nginx/nginx.conf configuration file to configure the global environment or individual HTTP servers and HTTP locations. component: web-agents version: 2023.11 page_id: web-agents:installation-guide:configure-nginx canonical_url: https://docs.pingidentity.com/web-agents/2023.11/installation-guide/configure-nginx.html section_ids: NGINX_directives: NGINX directives openam_agent: openam_agent openam_configuration: openam_configuration openam_threadpool: openam_threadpool openam_agent_instance: openam_agent_instance examples: Examples nginx-reverse-proxy-server: NGINX as a reverse proxy --- # Configure NGINX Plus Web Agents ## 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 PingOne Advanced Identity Cloud, if you don't want the agent to take part in protecting URLs in AM or PingOne Advanced Identity Cloud. | ### `openam_configuration` The path to the local bootstrap file for the agent: `openam_configuration ` 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 ` 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 ` 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 Agents. 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.](_images/apache-proxy.svg)Figure 1. NGINX reverse proxy configured between the agent and AM Find information on configuring NGINX for load balancing and other environment requirements in [NGINX as a WebSocket Proxy](https://www.f5.com/company/blog/nginx/websocket-nginx) in the NGINX documentation. After [interactive](install-nginx.html#install-nginx-web-agent) or [silent](install-nginx.html#silent-nginx-agent-installation) installation, follow these steps to configure NGINX as a reverse proxy. 1. Locate the NGINX Plus server configuration file `/etc/nginx/nginx.conf`. 2. Edit `nginx.conf` to add directives to the context you want to protect: ```bash 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; } ... } ``` 3. 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` 4. Restart the reverse proxy instance. 5. Configure AM to recover the forwarded header configured in the reverse proxy. 6. 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](../user-guide/load-balancers-proxies.html#comms-am-agents)