Running GlobalSight Behind an Apache Reverse Proxy

Running GlobalSight behind an Apache reverse proxy lets you manage access to GlobalSight through the popular and flexible Apache web server. We show how to set up HTTPS access to GlobalSight (including the Desktop Icon) and host GlobalSight on the same domain as other web content.

Configuring GlobalSight

The first step is to run GlobalSight on a port other than the standard web port 80. This will free up port 80 for apache. Simply run the GlobalSight installer and select an alternate port. We will use port 8000 in this example. Test that you can reach GlobalSight on port 8000. (Your firewall may block this. That won't be a problem in the final configuration because access to port 8000 only happen from Apache running on the same server.

There is one final configuration change. Because the port GlobalSight is running on is not the real port users will use, you need to tell GlobalSight its real URL. (This URL is used in email notifications.) To do this, run the mysql client on your GlobalSight database and run

update SYSTEM_PARAMETER
set value='https://www.example.com/globalsight'
where name='cap.login.url';

www.example.com should be replaced with your hostname.

Note: If you run the installer again, it will overwrite this parameter, and you will have to issue the SQL statement again.

Obtaining an SSL Certificate

It is assumed that you have OpenSSL installed.

In order to obtain an SSL certificate, you will need to generate a private key for your server, and then generate a certificate request containing a public key.

First, we generate a key pair. www.example.com should be changed to the external hostname of the site you are generating the certificate for:

openssl genrsa -out www.example.com.key 2048

Reference for openssl genrsa

The .key file that this generates will contain private key information, so keep it safe! It will also be needed later during Apache configuration. For now, it is used to generate the certificate request:

openssl req -new -config www.example.com.conf -key www.example.com.key -out www.example.com.csr

The -config argument here points to a .conf file which you will want to create. Here is an example:

[ req ]
prompt = no
distinguished_name = www.example.com
key = www.example.com.key
out = www.example.com.csr

[ www.globalsight.com ]
commonName          = www.example.com
organizationName    = <company>
localityName        = <city>
stateOrProvinceName = <state>
countryName         = <country>

Fill in all the parts in brackets. The format for this file is described as part of the reference for openssl req.

You should now have a .csr file that contains your certificate request. You will need to provide this file to your certificate authority when you purchase a certificate from them.

The certificate authority will provide you with a certificate (.crt). They may also provide a bundle containing other certificates. The reason for this is that certificates operate on a chain model, where you may need to walk up through multiple certificates in order to get to the actual authority. Information about these "in-between" certificates is contained in this bundle. We assume it is called ca_bundle.crt

The .key file you generated, along with your site-specific cert and any supplimental cert bundle the CA provided you should be installed in /etc/ssl or somewhere similar. Note that the .key file should be owned and only accessible by root/Administrator.

Further information about keys and certificates.

Configuring Apache

It is assumed that you have Apache installed and running. Apache 2 was used to test this configuration. The following Apache modules must be enabled: mod_ssl, mod_proxy, and mod_proxy_http. The exact configuation commands depend upon your Apache build, but if you look in the default configuration file for LoadModule commands, you will probably find what you need.

Here is an example configuration that uses HTTPS and also serves other content on the same domain.

<VirtualHost *:80>
   Servername www.example.com
   DocumentRoot /var/www/
   Redirect /globalsight https://www.example.com/globalsight
</VirtualHost>
<VirtualHost _default_:443>
   Servername www.example.com
   SSLEngine on
   SSLCertificateKeyFile   /etc/ssl/private/www.example.com.key
   SSLCertificateFile      /etc/ssl/certs/www.example.com.crt
   SSLCertificateChainFile /etc/ssl/certs/ca_bundle.crt
   BrowserMatch ".*MSIE.*" \
           nokeepalive ssl-unclean-shutdown \
           downgrade-1.0 force-response-1.0
   DocumentRoot /var/www/

   # retry=0 means no timeout before trying again after failure
   ProxyPass /globalsight http://localhost:8000/globalsight retry=0
   ProxyPassReverse /globalsight http://localhost:8000/globalsight
   <Proxy http://localhost:8000/globalsight>
       Allow from all
   </Proxy>
</VirtualHost>

Basically, there are two entries here. The first <VirtualHost> section handles port 80. The purpose of this block is to redirect access to the GlobalSight application (/globalsight) to the HTTPS port, while serving static content in /var/www over regular HTTP. This redirect is essential in order for Desktop Icon to use HTTPS, since Desktop Icon does not know how to connect over HTTPS automatically. (The Desktop Icon should still be configured to use port 80; it will follow the redirect to HTTPS.)

The second <VirtualHost> section, which handles requests to port 443 (HTTPS), is where the interesting stuff lives.

First, there is the SSL configuration. Be sure to adjust the paths to where you put these files. The BrowserMatch lines are recommended for compatibility with Internet Explorer.

ProxyPass causes Apache to pass requests along to GlobalSight on port 8000 using reverse proxying. The ProxyPassReverse line rewrites HTTP Location headers that may be produced by GlobalSight with port 8000.

One thing to note is the use of retry=0 in the ProxyPass line. By default, if the proxy operation fails (because GlobalSight is down), Apache will put the proxy on an internal cooldown and won't try to access it again for a little while. In the case of GlobalSight restarts, this is frustrating, because the service will appear to be offline for longer than it actually is. retry=0 disables this behavior, so GlobalSight will be immediately available.

The final <Proxy> section ensures that Apache allows the request to be proxied.

After modifying the apache configuration, you will need to restart apache.

Security Note about Webservices

If you access GlobalSight Webservices through the proxy, the IP address whitelist for webservices usage is effectively disabled. To GlobalSight, all requests look like they're coming from the proxy, which is on 127.0.0.1. So you must either allow all proxied requests to use Webservices (include 127.0.0.1 in the Remote IP Filter for Webservices), or none. This includes the Desktop Icon, which uses Webservices.

If you would like to allow only some hosts to use Webservices, they must access port 8000 directly. Of course then, they will use HTTP, not HTTPS.

Configuring client machines for SSL access

When you configure GlobalSight for https access as described above, you will need to import the security certificates to each client machine. Otherwise file upload applets will start uploading but will fail immaturely.

See the solution described at http://www.mkyong.com/webservices/jax-ws/suncertpathbuilderexception-unable-to-find-valid-certification-path-to-requested-target/