Web Agents 2024.9

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

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/nginx31_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 agent.conf 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/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/.

  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" 
    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.
  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/nginx31_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. Learn more from openam_agent.

  3. 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 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 Troubleshoot.
  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: 2024.9
    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.

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_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 Advanced Identity Cloud, if you don’t want the agent to take part in protecting URLs in AM or Advanced 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 Agent. 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.

  1. Locate the NGINX Plus server configuration file nginx.conf.

  2. 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;
        }
      ...
    }
  3. 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

  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. Learn more from Agent connection to AM through a load balancer/reverse proxy