12.3.1. Using a reverse proxy for HTTPS in front of eXo Platform

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

Apache or Nginx can be used as a reverse proxy in front of eXo Platform. It catches https requests from the browser and proxies the requests to eXo Platform via either AJP or HTTP protocol. The following diagram depicts the case described in this section:

In this case, a user accesses the site via https, for example https://proxy1.com, all his requests and all reponses to him are encrypted by the proxy.

Note

We are assuming you have a standard ssl certificate issued by an official certification authority.

The examples allow you to have a basic installation with ssl enabled. You should fine tune your installation before opening it on the web. Mozilla provide a great site to help you to find a configuration adapted to your needs.

Importing your SSL certificate into Java truststore

You need an SSL certificate for enabling https access to your site. You will configure your certificate in your front-end server (proxy1.com). Besides, you need to add the certificate to JVM truststore. For testing purpose, you can generate and use a self-signed certificate, as follows:

  1. Create a certificate using openssl (if you are using Windows, replace parentheses with quotation marks): openssl req -x509 -nodes -newkey rsa:2048 -keyout mykey.pem -out mycert.pem -subj '/O=MYORG/OU=MYUNIT/C=MY/ST=MYSTATE/L=MYCITY/CN=proxy1.com' -days 730

    You will use mycert.pem to certificate the Apache/Nginx server proxy1.com, so the part "CN=proxy1.com" is important.

  2. Import the certificate to Java truststore. This step is necessary to make gadgets work. Because Java keytool does not accept PEM file, you need to convert mycert.pem into DER format.

    openssl x509 -outform der -in mycert.pem -out mycert.der

    keytool -import -trustcacerts -file mycert.der -keystore $JAVA_HOME/jre/lib/security/cacerts -alias proxy1.com

Note

  • The default password of the Java keystore is "changeit".

  • Users will need to point their browser to https://proxy1.com and accept the certificate exception.

Configuring Apache

Before you start, note that details of Apache setup is not described here, and it depends on Apache version and your OS, so consult Apache documentation if you need.

Required modules

You need mod_ssl, mod_proxy. They are all standard Apache 2 modules, so no installation is required. You just need to enable it with the following command:

sudo a2enmod ssl proxy proxy_http

Configuring a virtual host for SSL port

Add this to site configuration (you should override the default ssl site /etc/apache2/sites-enabled/default-ssl.conf):

<IfModule mod_ssl.c>
	<VirtualHost *:443>
		ServerName proxy1.com
		ProxyPass / http://exo1.com:8080/
		ProxyPassReverse / http://exo1.com:8080/
		ProxyRequests Off
		ProxyPreserveHost Off

		SSLEngine On
		SSLCertificateFile /path/to/file/mycert.pem
		SSLCertificateKeyFile /path/to/file/mykey.pem
	</VirtualHost>
</IfModule>

Configuring Nginx

Instruction for installing Nginx can be found here. In Debian/Ubuntu you can install Nginx with the following command: apt-get install nginx.

Configure the server proxy1.com at port 443 as the following (you can put the configuration in a file like /etc/nginx/sites-enabled/proxy1.com):

server {
	listen 443;
	server_name proxy1.com;
	ssl on;
	ssl_certificate /path/to/file/mycert.pem;
	ssl_certificate_key /path/to/file/mykey.pem;

	location / {
		proxy_pass http://exo1.com:8080;
	}
}

The configuration here is a simple one and it works. For an advanced sample, you may read this blog post.

Configuring HTTP connector

In both eXo Platform Tomcat and JBoss, there is a default HTTP (8080) connector.

In any case, you should configure the connector so that eXo Platform is aware of the proxy in front of it.

It is configured in $PLATFORM_TOMCAT_HOME/conf/server.xml. You will add proxy parameters then it will be:


<Connector address="0.0.0.0" port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
  enableLookups="false" redirectPort="8443"
  connectionTimeout="20000" disableUploadTimeout="true"
  URIEncoding="UTF-8"
  compression="off" compressionMinSize="2048"
  noCompressionUserAgents=".*MSIE 6.*" compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript"
  proxyName="proxy1.com" proxyPort="443" scheme="https" />

It is configured in $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xml (or standalone-exo-cluster.xml in cluster mode). You need to modify the subsystem urn:jboss:domain:web:1.5 like the following:


<subsystem xmlns="urn:jboss:domain:web:1.5" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" socket-binding="http" scheme="https"  proxy-name="proxy1.com" proxy-port="443"/>
    ...
</subsystem>

The socket-binding ports are configured already, find these lines if you want to check:



<socket-binding name="http" port="8080"/>

After restarting the proxy and eXo Platform, you can test https://proxy1.com. If you are testing with dummy server names, make sure you created the hosts proxy1.com and exo1.com.

Note

Using eXo Platform behind an ssl loadbalancer or reverse proxy may cause a problem in gadgets working. To bypass this issue, some options should be added to the connector definition:

  • proxy-port: The port that will be used when sending a redirect.

  • proxy-name: The host name that will be used when sending a redirect. Default value is "null".

  • secure: Indicates if content sent or received by the connector is secured from the user perspective. It is set to "false" by default.

  • scheme: The web connector scheme (such as HTTP or HTTPS).

An example of the connector definition:


<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false" instance-id="${exo.cluster.node.name}">
<connector name="http" protocol="org.apache.coyote.http11.Http11NioProtocol" scheme="https" secure="true" proxy-name="proxy1.com" proxy-port="443"
socket-binding="http"/>
<virtual-server name="default-host" enable-welcome-root="false">
<alias name="localhost"/>
<alias name="proxy1.com"/>
<sso reauthenticate="false"/>
</virtual-server>
</subsystem>
Copyright ©. All rights reserved. eXo Platform SAS
blog comments powered byDisqus