Configure NGINX Plus Web Agents Documentation

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_agent to off for the following situations:

For HTTP servers or HTTP locations that need no AM authentication or policy, such as the public face of a website, /css directories, or /images directories.
When an NGINX HTTP Server is acting as a reverse proxy to AM or Identity Cloud, if you don’t want the agent to take part in protecting URLs in AM or Identity Cloud.

`openam_configuration`

The path to the local bootstrap file for the agent:

openam_configuration <path to nginx.conf>

Default: None, but during agent installation you must provide the path to /etc/nginx/nginx.conf.

`openam_threadpool`

The name of the AM threadpool:

openam_threadpool <name>

Default: The NGINX default threadpool

Before setting this directive, consider the consequence of changing the threadpool name.

openam_agent_instance

A number to identify an instance of NGINX Plus:

openam_agent_instance <number>

Default: 1

In deployments with multiple instances of NGINX Plus, use a unique number for each instance.

Examples

openam_agent is on globally but off` for one HTTP location

When openam_agent configuration is off, configure the server location /agent as on. This allows AM to redirect requests to the /agent endpoint after authentication.

In the following example nginx.conf:

agent_1 in the server context protects the / and /marketplace`location contexts
No agent instance protects the /customers`location context.

server {
  listen       80 default_server;
  server_name  localhost;
  openam_agent on;
  openam_agent_configuration /web_agents/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 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/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 Agents Documentation. You can use any reverse proxy that supports the WebSocket protocol.

Simplified diagram showing an NGINX configured as a reverse proxy between AM and the agent.

Figure 1. NGINX reverse proxy configured between the agent and AM

For information about how to configure NGINX for load balancing, and for other environment requirements, refer to the NGINX documentation at NGINX as a WebSocket Proxy.

After interactive or silent installation, follow these steps to configure NGINX as a reverse proxy.

Locate the NGINX Plus server configuration file 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 from Agent connection to AM through a load balancer/reverse proxy

Web Agents 2024.3