PingAccess

Installing on NGINX

Install a PingAccess agent on an NGINX system.

This procedure assumes your NGINX installation lives at $NGINX. Modify the paths this procedure uses based on the location of your NGINX installation and configuration files.

Before you begin

  • Download an NGINX agent .zip file from the PingAccess Downloads page and extract the contents to the $PINGACCESS_AGENT_NGINX directory.

    Amazon Linux 2 systems use RHEL 7 download bundles. Ping Identity will remove support for the last two RHEL 7 download bundles (NGINX Plus R31 and NGINX OSS 1.25.3) when support is added for NGINX Plus R36 and NGINX OSS 1.29.3.

  • The agent RPM has required dependencies that might be available through standard repositories. If these dependencies aren’t available in your Linux version, you can install them using the following included packages.

    Included packages for RHEL 8:

    • libsodium-1.0.18-2.el8.x86_64.rpm

    • libunwind-1.3.1-3.el8.x86_64.rpm

    • openpgm-5.2.122-21.el8.x86_64.rpm

    • zeromq-4.3.4-3.el8.x86_64.rpm

    Included packages for RHEL 9:

    • libsodium-1.0.18-8.el9.x86_64.rpm

    • libunwind-1.6.2-1.el9.x86_64.rpm

    • openpgm-5.2.122-28.el9.x86_64.rpm

    • zeromq-4.3.4-2.el9.x86_64.rpm

  • Configure an agent in the PingAccess admin console.

Steps

  1. To install the NGINX module, run the yum install pingaccess-agent-nginx-*.rpm lib*.rpm command.

  2. Prepare the <agent_name>_agent.properties file:

    1. In the PingAccess admin console, go to Applications > Agents and open your configured agent. In the Shared Secrets section, click the Download icon to download the <agent_name>_agent.properties file.

    2. Copy the <agent_name>_agent.properties file to $NGINX/paa/agent.properties.

    3. If you’re installing on NGINX OSS, edit the <agent_name>_agent.properties file, setting the agent.engine.configuration.maxConnections property to a value of 0.

  3. Make the following modifications to the NGINX configuration file, $NGINX/nginx.conf:

    1. To load the PingAccess Agent for NGINX module, add the following directive:

      load_module modules/ngx_http_paa_module.so;

    2. To configure the PingAccess Agent for NGINX module, add the following directive in the http {} block:

      include $NGINX/paa/http.conf;

      In the PingAccess Adding agents procedure, the PingAccess Host must match the certificate CN or Subject Alternative Name (SAN).

  4. Make the following modifications to the $NGINX/paa/http.conf file:

    1. To enable the PingAccess agent, modify the following property:

      paa_enabled on;

      If you’ve set the agent.engine.configuration.failover.hosts property in the agent.properties file, you must update the paa_upstream and upstream blocks in the provided http.conf file to a value consistent with a CN or SAN of the certificate associated with the PingAccess Agent HTTPS Listener. Otherwise, you won’t be able to establish an HTTPS connection to either the primary or backup server.

    2. If you’re installing on NGINX OSS, comment out the line containing the queue directive.

      For example:

      # queue 65536;

  5. Restart the NGINX server:

    1. To stop the NGINX server, run the sudo systemctl stop nginx command.

    2. To start the NGINX server, run the sudo systemctl start nginx command.