Product Overview

WAProxy is an HTTP(S) reverse proxy designed for WebADM. Although any reverse proxy could perform this role, WAProxy is specifically configured by RCDevs to work securely and utilize all the features WebADM offers for reverse proxies. It handles basic load balancing, failover, and both server and client certificates with minimal configuration effort.

Without a WAProxy reverse proxy, WebADM end-user web applications must be accessible from any location where users could be. For instance, if you use OpenOTP Push Login, a user’s phone must access the mobile communication endpoints of your WebADM installation from the internet. This requires placing WebADM in the DMZ (far from your LDAP directory and databases) or maintaining exceptions to allow the DMZ applications to reach WebADM in your internal network. Both scenarios pose challenges for maintaining proper security.

WAProxy addresses this by residing in the DMZ and offering only the services that should be accessible externally, while relaying requests to a WebADM installation within your internal network.

Unless your requirements are highly specific, we recommend using WAProxy as an efficient way to set up a properly functioning proxy.

With WAProxy enabled in WebADM, you can select which end-user applications (WebApps) are published through WAProxy.

System Requirements

The current version of WAProxy runs on Linux 32-bit or 64-bit operating systems with glibc >= 2.5. The installation package includes all required dependencies, allowing WebADM to run on any Linux-based system without additional requirements. It is recommended to use a dedicated machine (physical or virtual) for WAProxy, as some parts of the proxy run with root privileges.

You should already have a running WebADM installation (version >= 1.3), and it must be offering its services on the default TCP port 443.

To run the WebADM Proxy, your dedicated system should meet the following requirements:

  • A Linux distribution with glibc >= 2.5 (such as RedHat, CentOS, SUSE, Debian, or Ubuntu).
  • At least a 1 GHz processor (two cores or vCPUs recommended). Architecture can be either x86 or x86-64.
  • 512 MB of RAM.
  • At least 1GB of free disk space.

Deployment Scenarios

A typical deployment scenario involves placing WAProxy in a DMZ to relay requests to a single WebADM instance, such as our virtual appliance. The diagram on the next page illustrates this setup. White boxes represent machines, while the colored boxes inside them represent running processes. Red lines indicate communication between processes.

WAProxy

A more advanced deployment scenario involves using a WebADM cluster for the backend. This setup maintains high availability by allowing the proxy to route requests to a secondary server if the primary server fails. Additionally, the proxy can distribute incoming requests across both cluster members, effectively increasing the system's request handling capacity—except in cases of simultaneous modifications to the same user.

The diagram on the next page illustrates this configuration. Dotted lines represent communication that occurs only if the primary server is down. The dot-and-dash line indicates that the secondary server may be used both during normal operation and as a fallback when the primary server is unavailable.

WAProxy

Installation

Installation through RPM Repository

On RPM-based systems, you can use the RCDevs repository. Clear the dnf cache and install the Radius Bridge package as follows:

dnf install waproxy

Installation through Debian Repository

apt update

You are now ready to install RCDevs packages on your system:

apt install waproxy

Installation through the Self-Installer

Instead of using the repositories, you can also download the latest package on RCDevs Website. Select the package for the right architecture and execute it on your chosen host machine, as root.

Configuration

After installation, you must run the WAProxy initial setup script located at /opt/waproxy/bin/setup. The setup will prompt you for the FQDN of the proxy, which should be the name clients will use to connect to the proxy from the Internet. The script will generate an HTTPS X.509 certificate based on this information. It will also request the IP or hostname of one of the backend WebADM servers. The WebADM CA certificate file will be retrieved from the backend server and stored in /opt/waproxy/conf/ca.crt. This CA certificate will be used to authenticate users with client certificates for any WebADM application that supports this feature.

The WAProxy configuration file is located at /opt/waproxy/conf/waproxy.conf. All options have reasonable defaults, except for _server_addr1_ and _server_addr2_, which must be set for the proxy to function correctly.

These settings should correspond to the IP addresses or hostnames by which your WebADM hosts are known internally.

Note that configuration changes require a restart of the WAProxy service (see the next section).

Upgrades to WAProxy will create or overwrite the file /opt/waproxy/conf/waproxy.conf.default, which you should review for any new configuration directives introduced by the upgrade.

Basic Configuration

Depending on your WebADM backend setup, WAProxy needs to be configured differently:

  • For a single WebADM server, set server_addr1 in the configuration file.
  • For two backend servers, configure both server_addr1 and server_addr2.

When using two backend servers, you need to choose a scheme for relaying requests to the backend:

  • Setting server_policy to Ordered (the default value) directs the proxy to forward all requests to the first server and use the second server only if the first server fails to respond properly.
  • Setting server_policy to Balanced will configure the proxy to distribute requests to both backend servers in a round-robin fashion.

Custom SSL Certificate

The custom certificate is used solely for access on port 443. If web services such as OpenOTP are published through WAProxy, you must use the default WAProxy certificate issued by the WebADM PKI.

Custom certificates and keys must be in PEM format and located in /opt/waproxy/conf/custom.crt and /opt/waproxy/conf/custom.key.

SSL/TLS Ciphersuite

The default configuration supports various SSL/TLS versions and ciphers to maintain compatibility with older clients. You can enable or disable specific versions and ciphers using the configuration settings in /opt/waproxy/conf/waproxy.env (create this file if it does not already exist in your environment).
Have a look on the Hardening documentation for more information about the syntax.

Network Configuration

Similar to WebADM, WAProxy does not serve web applications over unencrypted HTTP. Port 80 (or the port specified by port_std, if changed) will redirect clients to port 443 (or the port specified by port_ssl).

You can adjust the ports on which the proxy offers its services by setting the port_std and port_ssl directives in the waproxy.env file. By default, the proxy will contact the WebADM backend over ports 443 and 8443 (if web service publication is configured).

Backend Configuration

IP of WAProxy servers

You should configure each WebADM server that the proxy forwards requests to. On these servers, edit the /opt/webadm/conf/webadm.conf file and add your WAProxy’s IP addresses, separated by commas, to the waproxy_proxies directive:

waproxy_proxies "<YOUR_WAPROXY_IP1>", "<YOUR_WAPROXY_IP2>"

If there are one or more reverse proxies between your WAProxy server and the clients, you need to include the number of reverse proxies (including the WAProxy server) in the waproxy_proxies directive so that WebADM can accurately determine the client’s IP address. In that case, configure the directive like this:

waproxy_proxies "<YOUR_WAPROXY_IP> <NUMBER_REVERSE_PROXIES>", "<YOUR_WAPROXY_IP2> <NUMBER_REVERSE_PROXIES>"

Push Login communications

If you use push login with OpenOTP Token applications, configure them to use the proxy’s OpenOTP endpoints instead of WebADM’s default.
In the applications’ configuration page, look for the “Mobile EndPoint URL” setting. The WAProxy endpoints should be set to https://<public-proxy-name>/ws/openotp/.

If cloud_wsproxy is enabled in the WebADM configuration file, push responses will pass through cloud.rcdevs.com to reach the WebADM backends.

Publishing web services

By default, WAProxy does not proxy the web services provided by WebADM on port 8443. You can enable this by setting the following directive in the /opt/waproxy/conf/waproxy.conf file:

publish_websrvs Yes

To access the Web Services through WAProxy, you need to:

  • Publish OpenOTP to WAProxy in the settings of "MFA Authentication Server (OpenOTP)".
WAProxy
  • Use a client certificate or API Key issued by WebADM when accessing the web service URL. Refer to the dedicated documentation for instructions on how to issue a certificate or an API Key.

Auto-renewal of TLS certificate

To enable auto-renewal of the TLS certificate used by the WAProxy server, you can add a cron job to run the /opt/waproxy/bin/waproxy renew command. This command will renew the certificate if it is nearing expiration and reload the rcdevs-waproxy processes to apply the new certificate. Additionally, restarting WAProxy a few days before the certificate's expiration will also trigger an automatic renewal of the certificate.

Advanced customization of Apache

If you have experience with Apache HTTPd, you can modify /opt/waproxy/lib/httpd.ini to meet your specific needs. However, be aware that WAProxy upgrades will overwrite this file. We view the choice of Apache’s HTTP server as an implementation detail that may change with future releases. If you find yourself needing such changes, please contact us so we can consider incorporating them into an official release.

Start and Stop services

If you allow the installer to place the WAProxy init scripts on your machine, the proxy service should start automatically at boot. You can also start and stop the proxy using your distribution's standard commands, such as systemctl start waproxy or systemctl stop waproxy for distributions using systemd, like RHEL or Debian. Alternatively, you can use /opt/waproxy/bin/waproxy start|restart|stop.

Upgrading or Removing

When a new version of WAProxy is released, you can download and install it as you did for your first installation. The installer will offer you the option of upgrading your installation. Be aware that, to do so, the installer will stop WAProxy. As a matter of principle, you should back up the /opt/waproxy directory before the upgrade.
The installer also gives you the option of removing an existing WAProxy installation.

You can “reset” your installation by executing /opt/waproxy/setup reset, which removes any init, rc and log rotate scripts the installer put on the machine. This will also remove the proxy’s logs, key and certificates.

If the installation was done through the RCDevs repository, use your package manager to update WAProxy.

Troubleshooting

Connections that "stall" until they time out may indicate that a firewall is dropping packets, possibly due to incorrect hostname configurations. Ensure that you also check the host's own firewall.

WAProxy was not designed to work with SELinux. If your host has SELinux enabled, set its mode to "Permissive." On Red Hat 7, you can execute setenforce Permissive and set SELINUX=permissive in /etc/selinux/config to make this change permanent.

If you have not set up a proper PKI, you might encounter errors in the logs, such as “AH00898: Error during SSL Handshake with remote server,” when accessing a resource through the proxy. These errors can occur if the WebADM servers present certificates that do not match their names.

You can find detailed error traces in /opt/waproxy/logs/waproxy.log. These logs are rotated if you allowed the installer to set up the log rotation script on your machine (assuming log rotation is run regularly on your host).

For verbose logs, you can edit the /opt/waproxy/lib/httpd.ini file and set the LogLevel directive to the desired level. Restart the WAProxy service for the changes to take effect.