Contents

If the application server (e.g. Apache Tomcat) on which formcycle is installed is running behind another server, e.g. a reverse proxy, a load balancer or similar, it should be checked that the information of a request is passed on to it unchanged. In concrete terms this means that both the Host header and the protocol used must be passed on unchanged by the intermediate servers. In most standard configurations, however, this is not the case because the requests are received by the intermediate server and sent to the application server as a new request. 

The problematic scenario (see figure) is the following:

1. The user calls the URL https://www.example.com/formcycle.
2. The request is received and evaluated by the intermediate server.
3. The intermediate server makes a new request to the designated server. However, since an internal request is made here, the call URL is changed to http://192.168.0.1/formcycle. This URL now arrives at the application server and no longer contains the required information about which URL was actually called by the user.

Since FORMCYCLE interprets the original request URL of the user, especially when logging into a form, and this URL may not be determined correctly, it is necessary to configure intermediate servers accordingly. Make sure that both the HTTP header Host and the protocol used (HTTP or HTTPS) are forwarded unchanged. Also, the correct forwarding of WebSocket connections must be provided. Alternatively to the concret protocols, the intermediate server can also use X-Forwarded headers to indicate which protocol the request used originally.

Example configuration Apache

For the correct configuration of an Apache server, which acts as a reverse proxy, three points are relevant and have to be stored e.g. in the configuration of the VirtualHosts:

1. The instruction ProxyPreserveHost On to get the originally called Host header 
2. The separation of the individual protocols and its usage when forwarding to the application server. This means that for HTTP and HTTPS a separate VirtualHost with appropriate configuration must be used.
3. Configuration of the conditional RewriteRule for the forwarding of WebSocket connections via WS and WSS. By default, FORMCYCLE uses the corresponding ports of the servlet container (WS port = HTTP port, WSS port = HTTPS port).

For the Apache settings it is necessary to activate the corresponding modules. The following are required as minimum:

• proxy
• proxy_http
• proxy_wstunnel
• rewrite

Further information about the modules of Apache you will find here.

The configuration described above, as well as any settings that may be necessary when using self-generated certificates, is briefly illustrated here: 

<VirtualHost www.example.com:80>
        ...
        # Enables retention of the originally called host up to the application server.
        ProxyPreserveHost On
        ...
        # Forwarding via HTTP
        ProxyPass / http://192.168.0.1/
        ProxyPassReverse / http://192.168.0.1/
        ...
        # Forwarding of websocket-connections via WS
        RewriteEngine on
        RewriteCond %{HTTP:Upgrade} websocket [NC]
        RewriteCond %{HTTP:Connection} upgrade [NC]
        RewriteRule ^/?(.*) "ws://192.168.0.1:80/$1" [P,L]
</VirtualHost>

<IfModule mod_ssl.c>
    <VirtualHost www.example.com:443>
        ...
        SSLEngine on
        SSLProxyEngine On
        ...
        # Enables retention of the originally called host up to the application server.
        ProxyPreserveHost On

        # Deactivates the certificate check of the application server if necessary.
        # Necessary if the certificates are self-created.
        SSLProxyVerify none
        SSLProxyCheckPeerCN off
        SSLProxyCheckPeerName off
        SSLProxyCheckPeerExpire off
        ...
        # Forwarding via HTTPS
        ProxyPass / https://192.168.0.1/
        ProxyPassReverse / https://192.168.0.1/
        ...
        # Forwarding of websocket-connections via WSS
        RewriteEngine on
        RewriteCond %{HTTP:Upgrade} websocket [NC]
        RewriteCond %{HTTP:Connection} upgrade [NC]
        RewriteRule ^/?(.*) "wss://192.168.0.1:443/$1" [P,L]
    </VirtualHost>
</IfModule>

Usage of X-Forwarded headers for unencrypted communication

If the intermediate server supports sending X-Forwarded headers and the servlet container which hosts FORMCYCLE can evaluate these headers, the communication between the intermediate server and FORMCYCLE can also be done via another protocol. Both the intermediate server and the servlet container must be configured to use these headers. For more information on configuration, refer to the documentation of the respective product. 

Configuration examples

With Apache, for example, the following configuration inside the responsible VirtualHosts can be used to include the appropriate headers:

//HTTP
RequestHeader set X-Forwarded-Port "80"
RequestHeader set X-Forwarded-Proto "http"

//HTTPS
RequestHeader set X-Forwarded-Port "443"
RequestHeader set X-Forwarded-Proto "https"

With nginx, for example, the following configuration can be used to send the corresponding headers in the section responsible for the reverse proxy:

proxy_pass http://127.0.0.1:8080/formcycle/;
proxy_set_header Host $http_host;
proxy_set_header x-real-ip $remote_addr;
proxy_set_header x-forwarded-proto $scheme;

For Apache Tomcat servers, the following valve entry must be added to the server.xml within the catalina engine to evaluate the sent X-Forwarded headers:

<Engine......
 <Valve className="org.apache.catalina.valves.RemoteIpValve"
  internalProxies="<IP's of the trusted proxy server>"
  remoteIpHeader="x-forwarded-for"
  protocolHeader="x-forwarded-proto"
  protocolHeaderHttpsValue="https" />
</Engine>

Note: If the configuration of the X-Forwarded header does not work, it may be necessary to configure the IPs of the trustworthy proxy servers in the internalProxies property. One or more IP addresses (e.g.: 192\.168\.0\.10|192\.168\.0\.11) or an IP address range is expected here, which can be defined using a regular expression (e.g .: 169\.254\.\d{1,3}\.\d{1,3}).

For the changes in the server.xml of the Apache Tomcat Server to take effect, the service must be restarted.