HTTPS Architecture with Liferay

Purpose #

This article assumes you have a web-architecture made of a public area and some applications like web-mail. It assumes you want or need to protect the communication between the visitor and the applications and the private areas of Liferay. As a result:

  • The public pages of guest will be available using http or https
  • The traffic between the client and the web-application will be encrypted
  • The traffic between the components of Liferay requiring authentication will be forced to https. Accordingly:
    • The passwords and user ids will be preserved by https at login time
    • The data transmitted once the user is authenticated will be secured by https. I.e the data of the private communities of Liferay will be secured by https.
    • All data related to applications will be secured by https

Architecture #

The architecture set up bases on four tier architecture:

  • A entry server with firewall and the proxy. This is the first tier server. In a three tier architecture this server would also authenticate the users.
  • An authorization server which authenticate the user. This is the second tier server. This server is usually only present in big web-infrastructures.
  • An application server. This is the third tier server. Applications like Liferay or web-mail are installed on this server.
  • The database server. This is the fourth tier server. This server is usually only available in big web-infrastructure.

Software #

The following software are assumed to be used:

  • Sun Solaris 10 operating system
  • MySQL 5 database
  • Apache 2.0 web-server
  • Liferay 5.2.3 Tomcat 6 bundle downloaded from www.liferay.com

Required knowledge #

In order to succeed in setting up this infrastructure, you should definitely have the following knowledge:

  • Good Unix (Linux or Solaris) knowledge.
  • Good TCP/IP knowledge.
  • Some knowledge of Java, Liferay and XML.
  • Good knowledge of the Apache server especially of the mod_rewrite module.
  • Excellent ability to read documentation! Especially you should read the section related to your application server and database in the Liferay Portal Administrator's Guide

Specific Java or Tomcat knowledge is not required.

Server installation #

  • Install first the hardware and wire the network properly.
    • Install the server in a DMZ and watch you do not mix up the cables connected to the Internet and the ones connected to the LAN!
    • Set up a DNS service for you DMZ including all server used and forwarding instructions
    • Secure you DNS server!
  • Install the operating system on each of the physical servers you will use.
  • Install the necessary additional software:
    • You will definitely need a good editor like vim.
    • You might be happy to have curl installed.
    • The databases you plan to use. See the Liferay documentation about the supported databases.
  • Secure you can communicate between your LAN and the servers. A good terminal is necessary!
    • You can use telnet on port 23 for this purpose but this is NOT recommended.
    • Putty and openssl should be considered as a minimum requirements.
  • Write down the ports you plan use. You will need:
    • An http port for the Internet requests: typically 80.
    • An https port for the secure Internet requests: typically 443
    • A Tomcat port for unsecured requests: typically 8080
    • A secured Tomcat port for secured https requests: typically 8443
    • The communication port for putty if used
    • An access to a DNS server usually on port 53
    • You will probably also want to use the Unix email feature on port 25
  • Configure all firewall and secure the correct ports are open on the Internet and on the LAN side.
  • Eventually configure your email server and please avoid relaying spam!
  • Secure all servers have access to the DNS server and can be found with a DNS query.

Liferay installation #

To install Liferay proceed the following way:

  • Download the Liferay Portal Administrator's Guide for your version of liferay. For version 5.2.3 it is located here and read the installation section.
  • Install Liferay as instructed.

Liferay configuration #

To configure Lifreay you will need to setup the portal-ext.properties file. You need to create this file in the directory you uncompressed the Liferay bundle called also Liferay home.

In this file secure the following settings are available:

  • Database configuration: here an example for a MySQL database lportal installed on localhost
    • jdbc.default.driverClassName=com.mysql.jdbc.Driver
    • jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
    • jdbc.default.username= change me
    • jdbc.default.password= change me
  • Configure Liferay to set up the database at his first run:
    • Set schema.run.enabled=true and shema.run.minimal=false
  • Avoid Liferay to handle the secure connections by setting company.security.auth.requires.https=false
  • Pass your web-server configuration to Liferay with the following:
    • web.server.http.port= the port you defined for your unsecured Internet connections
    • web.server.https.port= the port you defined your secured Internet connections
    • web.server.host= change me to www.mydomain.bar

Do not add the other configuration parameters yet. This will only burden the debugging process. Then:

  • Start Liferay.
  • Control the startup of Liferay with tail -f catalina.out. This file is located in your [Liferay home]/tomcat[your version]/ logs.
    • Check the database tables are created.
  • Connect to http://localhost:8080 or to http://yourhost:8080
    • Secure Liferay is working properly
    • Set up your administrator account properly

Notice If you can not access your Liferay server:

  • Disable the firewall on the server
  • Secure your DNS resolution works properly for a remote access (http://yourhost:8080)
  • If it still does not work:
    • From the prompt of the server issue the command: telnet localhost 8080
    • At the prompt issue the command GET. If HTML code is returned on the console if Liferay works.

SSL and proxy configuration #

Ok, this is the real tricky part. We will aim to secure the following:

  • The visitor connects to your site with http and is redirected to https as soon as he enters an area to be protected.
    • The requests to the login portlet of Liferay and all subsequent web-request will be converted to https
    • The requests to the applications will be automatically converted to https.
  • If the visitor uses https to connect to your site and all its request will remain secured by https.

We will secure the protocol switch by using only Apache proxy features.

Access to the site with http #

Visitor -> http -> Public area -> http ->Liferay server -> http -> Visitor -> http...
              |	
              | (Conversion to https)
              |
              |-> Login portlet -> https -> Liferay server -> https -> Visitor -> https...
              |-> Web application - https -> Application servers -> https -> Visitor -> https...

Access to the site with https #

Visitor -> https -> Public area -> https ->Liferay server -> https -> Visitor -> https...
              |
               -> Login portlet -> https -> Liferay server -> https -> Visitor -> https...
              |-> Web application - https -> Application servers -> https -> Visitor -> https...

1. Apache SSL configuration #

This configuration requires you setup a VirtualHosts for the SSL port 443. In general you will find in your http.conf files a statement like <VirtualHost _default_:443>. If not you will have to setup this virtual host yourself.

I will not document the configuration of SSL Apache here. The configuration can be done with an self-signed or a production certificate. Please refer to the Apache documentation, the OpenSSL documentation and read the httpd.conf comments of your installation. Here a some links which might help:

Start Apache and secure you can access the default pages delivered with http and https.

2. Liferay SSL configuration #

Liferay will not serve https out of the box. In order to keep the https protocol after the protocol conversion, Liferay will have to serve https to the Apache proxy placed in front of it. Therefor we will configure the Tomcat server to serve https. Getting Tomcat to serve https requires to generate the SSL keys and to configure the Tomcat server.

a) Generate the Tomcat server SSL key #

  • Search for the keytool on your proxy server: find / -name keytool -ls.
  • Create a directory under your Apache ServerRoot to hold the SSL key of Tomcat: mkdir [ServerRoot]/passwd. Never create this directory under the DocumentRoot directory!!
  • Write down this path you will use it later.
  • Change into this directory
  • Stop Liferay
  • Generate the SSL key for your Tomcat server.

This will generate a key valid for the next 10 years of a 2048 bit length on a Solaris 10 server (follow the instructions on the screen):

[Path to]/keytool \
-genkey -v -alias tomcat -keyalg RSA \
-validity 3650 -keysize 2048 \
-keystore [Path to your passwd directory]/.keystore \
-storepass [My strong password] -keypass [SAME strong password]

Notice

  • The passwords used for -storepass and - keypass MUSST be the identical or you will get an error at Liferay startup time.
  • No special key installation is necessary.
  • More on SSL Key and Tomcat can be found here.

b) Configure the Tomcat server for SSL #

To enable SSL for Tomcat you need to modify the configuration files.

  • 1) Modification of server.xml:
    • File location: [Liferay home]/tomcat-6.0.18/conf
    • Uncomment the entry: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"... (remove the <!-- line before and the --> line after)
    • Modify this entry according to the example below
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
        maxThreads="150" scheme="https" secure="true"
        keystoreFile="~[Path to my]/.keystore"
        keystorePass="Key password"
        clientAuth="false" sslProtocol="TLS" />

Notice

  • The keystoreFile argument is equivalent to the -keystore argument you used to generate the SSL key with keytool
  • The keystorePass argument is equivalent to the - storepass argument you used to generate the SSL key with keytool
  • 2) Modification of the web.xml file
    • File location: [Liferay home]/webapps/ROOT/WEB-INF/web.xml
    • Search for <security-constraint>
    • Search for the child node <user-data-constraint>
    • Modify this node to become <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  • 3) Start Liferay
    • Control the startup of Liferay with tail -f catalina.out. This file is located in your [Liferay home]/tomcat[your version]/ logs.
    • Connect to https://localhost:8443 or to https://yourhost:8443
    • Secure Liferay is working properly

Notice If you can not access your Liferay server:

  • Disable the firewall on the server
  • Secure your DNS resolution works properly for a remote access (https://yourhost:8443)
  • If it still does not work use curl to connect to https://localhost:8433 from the prompt.

c) Installing the Apache proxies #

Ok, if you get here you definitely deserve a beer. Now fasten your seat belt, since you will configure a chain of apache proxies securing https is used when required by your security policy. I will show examples for one and several physical servers. The less server you have the more Apache VirtualHosts will be involved.

Prerequisites #

In order to secure https is used if your web-application are called from the Internet and the user passwords for these applications are protected against sniffing by https each application need to have its own URL. For example your web-mail application will have the URL: http://www.mydomain.bar/mail. This can be achieved by installing each application in its own directory. Example:

  • Your Apache has its ServerRoot in /var/apache2
  • Your Apache DocumentRoot is located in /var/apache2/htdocs
  • The web-mail application shall be installed under /var/apache2/htdocs/mail
  • By properly configuring Apache you can call your web-mail application with the URL http://www.mydomain.bar/mail/index.php
Redirects versus proxy statements #

Redirects will not generate a new GET statement to your Apache server but only rewrite the URL the server received from the visitor. Examples:

  • Assuming a one server web-infrastructure:
    • Your web-mail application is installed in /var/apache2/htdocs/mailsevice on your web-server
    • Your web-documents are located under /var/apache2/htdocs on your web-server
    • Your visitor should be able to access his mail with http://www.mydomain.bar/mail
    • Then you would redirect the URL http://www.mydomain.bar/mail to http://www.mydomain.bar/mailservice
    • As a result the visitor would see http://www.mydomain.bar/mailservice in the address bar of his browser which is not a problem in a one server architecture.
  • Assuming a two server web-infrastructure:
    • Your web-server is www in mydomain.bar
    • Your application server is app in mydomain.bar
    • Your web-mail application is installed on app.mydomain.bar in /var/apache2/htdocs/mailsevice
    • Your web-documents are located on www.mydomain.bar under /var/apache2/htdocs
    • Your visitor should be able to access his mail with http://www.mydomain.bar/mail
    • If you would redirect the URL http://www.mydomain.bar/mail to http://app.mydomain.bar/mailservice the visitor would see http://app.mydomain.bar/mailservice in the address bar of his browser. In general this will prevent him to use the application.

Accordingly redirects should be used if you redirect an URL within the same VirtualHosts of your apache server, since URL consistency is not preserved by redirect statements.

Proxy statement secure a constistent URL space. Your visitor will only see only http://www.mydomain.bar in the address bar of his browser. Accordingly he will be able to use the applications on other servers since these statement allow to rewrite the URL of the visitor and the response of the server.

Accordingly:

  • Assuming a one server web-infrastructure:
    • Your web-mail application is installed in /var/apache2/htdocs/mailsevice on your web-server
    • Your web-documents are located under /var/apache2/htdocs on your web-server
    • Your visitor should be able to access his mail with http://www.mydomain.bar/mail
    • You setup a proxy statement redirecting URL http://www.mydomain.bar/mail to http://www.mydomain.bar/mailservice
    • As a result the visitor would see http://www.mydomain.bar/mail in the address bar his browser provided you did this properly
  • Assuming a two server web-infrastructure:
    • Your web-server is www in mydomain.bar
    • Your application server is app in mydomain.bar
    • Your web-mail application is installed on app.mydomain.bar in /var/apache2/htdocs/mailsevice
    • Your web-documents are located on www.mydomain.bar under /var/apache2/htdocs
    • Your visitor should be able to access his mail with http://www.mydomain.bar/mail
    • You setup a proxy statement redirecting the URL http://www.mydomain.bar/mail to http://app.mydomain.bar/mailservice. The visitor would see http://www.mydomain.bar/mail in his browser which will not result in an error when the visitor starts to use the application.

We will use a combination of redirects and proxies to secure https is used for the URL we want to protect.

Proxy and redirect chains overview #

With a lot of hope the following it will help I will try to explain how the proxy system works:

  • Assuming a one server configuration:
    • The visitor connects to a protected page (Liferay login) or an application with http:
    • The URL of the visitor is identified as being protected by the Apache HTTP virtual host running on port 80
    • The request is redirected to the SSL Apache virtual host on port 443 of the same physical server with a proxy statement.
    • The SSL Apache virtual host on port 443 will redirect with a redirect statement the application server using https
    • As the answer comes back from the application server the Apache HTTP virtual host proxy on port 80 will rewrite the URL to www.mydomain.bar securing the redirection is transparent to the user.
  • Assuming a two or more server configuration:
    • The visitor connects to a protected page (Liferay login) or an application with http:
    • The URL of the visitor is identified as being protected by the Apache HTTP virtual host running on port 80
    • The request is redirected to an SSL Apache virtual host on port 443 on the same server with a proxy statement
    • The SSL Apache virtual host will redirect the request to the application server with a proxy statement
    • As the answer comes back from the application server the Apache HTTP virtual host proxy on port 80 will rewrite the URL to www.mydomain.bar securing the redirection is transparent to the user.
Implementation #
  • One server configuration: implement this configuration on your Liferay server.
  • Two or more server configuration: choose on of the server to be the central proxy for Liferay and the applications.

On your Apache proxy server set up the following in your httpd.conf file. This will configure the virtual host as a reverse proxy securing URL consistency for your visitor:

First enable the proxy modules by securing the following are uncommented at the start of your httpd.conf file:

    # General proxy module
    LoadModule proxy_module libexec/mod_proxy.so
    # Enables SSL proxy connections
    LoadModule proxy_connect_module libexec/mod_proxy_connect.so
    # Support for http proxy
    LoadModule proxy_http_module libexec/mod_proxy_http.so
    # Support for rewriting URLs (needed despite the proxy modules)
    LoadModule rewrite_module libexec/mod_rewrite.so

Next configure the central proxy for the http requests:

<IfModule mod_proxy.c>
    ### This par secures the redirection to the SSL virtual host and
    ### the access to the public domain of the Liferay portal.

    # Proxy access configuration. 
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>

    ### Proxy configuration:
    # To be able to connect to the SSL service
    SSLProxyEngine      On
    # EXTREMELY IMPORTANT!!!
    ProxyRequests       Off
    # Secures the same host is displayed in the address bar of the browser.
    ProxyPassReverse    /              http://localhost:8080/
    # Enable mod_rewrite
    RewriteEngine   On
    RewriteLog      "[Your path to the apache logs]/rewrite.log"
    # Increase up to 4 to debug.
    RewriteLogLevel 1
    # Secures your server will not loop for ever
    RewriteOptions  MaxRedirects=10
    # Will pass the full URL to the other hosts and virtual hosts: IMPORTANT!
    ProxyPreserveHost On


    ### Rewriting applications and portal login request to https
    ### Syntax
    # The last RewriteCond MUSST NOT have [NC,OR] at the end
    # [NC] => no case: secures the URL is correctly redirected
    # [OR] => boolean operator OR

    RewriteCond         %{REQUEST_URI}      /[application url]                  [NC,OR]
    RewriteCond         %{HTTP_REFERER}     /[application url]                  [NC,OR]
    ... (i.e. the web-mail application described above)...
    RewriteCond         %{HTTP_REFERER}     /mail                               [NC,OR]
    RewriteCond         %{REQUEST_URI}      /mail                               [NC,OR]
    ... Protect the login portlet of liferay
    RewriteCond         %{REQUEST_URI}      login                               [NC,OR]
    RewriteCond         %{HTTP_REFERER}     login                               [NC]
    RewriteRule         ^(.*)$              https://%{SERVER_NAME}$1            [L,P]

    ### Rewriting other URLS for the portal: all above URLs must be listed here
    ### Syntax
    # ! => boolean not
    # All application URL listed above must be excluded here
    # The first statement secures https is not rewritten twice (endless loop)
    # Never use [OR] in the following. [NC] can be used to securely match URLs
    RewriteCond         %{HTTPS}            !^on                                [NC]
    RewriteCond         %{REQUEST_URI}      !^[application url]
    ... (i.e. the web-mail application described above)...
    RewriteCond         %{REQUEST_URI}      !^/mail
    ...
    RewriteRule         (^.*)               http://localhost:8080%{REQUEST_URI} [P]

</IfModule>

This configuration will pass all URL to be protected to your HTTPS virtual host. You will need to configure it to redirect the requests to the correct service. Accordingly in the section <VirtualHost _default_:443> of the apache configuration of your central proxy insert the following:

    ### Proxy configuration:
    # To be able to connect to the SSL service
    SSLProxyEngine      On
    # EXTREMELY IMPORTANT!!!
    ProxyRequests       Off
    # Secures the same host is displayed in the address bar of the browser.
    ProxyPassReverse    /              https://localhost:8443
    # Enable mod_rewrite
    RewriteEngine   On
    RewriteLog      "[Your path to the apache logs]/ssl_rewrite.log"
    # Increase up to 4 to debug.
    RewriteLogLevel 1
    # Secures your server will not loop for ever
    RewriteOptions  MaxRedirects=10
    # Will pass the full URL to the other hosts and virtual hosts: IMPORTANT!
    ProxyPreserveHost On

    ### Redirecting application https request to application servers.
    ### Syntax
    # The last RewriteCond MUSST NOT have [NC,OR] at the end
    # [NC] => no case: secures the URL is correctly redirected
    # [OR] => boolean operator OR
 
    ### Example of the web-mail redirected on app.mydomain.bar
    RewriteCond         %{HTTP_REFERER}     /mail                               [NC,OR]
    RewriteCond         %{REQUEST_URI}      /mail                               [NC]
    RewriteRule         ^(.*)$              https://app.mydomain.bar$1          [L,P]

    ### Example for several applications installed on a server.
    RewriteCond         %{REQUEST_URI}      /[application url]                  [NC,OR]
    RewriteCond         %{HTTP_REFERER}     /[application url]                  [NC,OR]
    ... all application on this server ...
    RewriteCond         %{REQUEST_URI}      /[application url]                  [NC,OR]
    RewriteCond         %{HTTP_REFERER}     /[application url]                  [NC]                            
    RewriteRule         ^(.*)$              https://app1.mydomain.bar$1         [L,P]

    ### And so on for all applications servers

    ### Rewriting URLS for the portal connecting to the Liferay SSL server
    ### Syntax
    # ! => boolean not
    # All application URL listed above must be excluded here
    # Never use [OR] in the following. [NC] can be used to securely match URLs
    RewriteCond         %{REQUEST_URI}      !^[application url]
    ... our mail example...
    RewriteCond         %{REQUEST_URI}      !^/mail
    ...
    RewriteRule         ^(.*)$              https://localhost:8443$1             [L,P]

In addition you need to configure you application server properly. With the above configurations the whole URL is passed to the application servers. In order to preserve URL consistency, your application servers must handle them properly. Secure the following is available in the configuration file on the Apache serving your applications. Obviously the applications server must support https!

### secure LoadModule rewrite_module libexec/mod_rewrite.so is uncommented!
<IfModule rewrite_module>
    RewriteLog  "[Your path to the apache logs]/ssl_rewrite.log"
    # Increase up to 4 to debug.
    RewriteLogLevel 1
    RewriteEngine on

    ### Syntax
    # If not connected to port 443 and application url then https redirect to the same server
    # Notice: here a redirect and not a proxy statement is used! 
    RewriteCond %{SERVER_PORT}      !443
    RewriteCond %{QUERY_STRING}     [application url]			[NC]
    RewriteRule  ^.*                https://%{SERVER_NAME}%{REQUEST_URI}  [L,R]

    ... our mail example:
    RewriteCond %{SERVER_PORT}      !443
    RewriteCond %{QUERY_STRING}     /mail				[NC]
    RewriteRule  ^.*                https://%{SERVER_NAME}%{REQUEST_URI}  [L,R]

    ...

</IfModule>

Debugging #

Debugging this configuration kept me busy during weeks. It now works on my infrastructure. There is no 100 ways to proceed. I would suggest the following:

  • Reread this paper carefully and try to really understand the theoretical parts of it.
  • Read all documentation about proxies and rewrite rules of the Apache site.
  • Set the parameter RewriteLogLevel of your configuration files to 2, 3 or 4
  • Tail the RewriteLog you defined.
  • Be patient...
0 Attachments
44248 Views
Average (3 Votes)
The average rating is 4.33333333333333 stars out of 5.
Comments
Threaded Replies Author Date
Can someone with A) an understanding of this... Matt Walker November 28, 2011 1:27 PM
emoticons enabled - AWESOME. Let's try again...... Matt Walker November 28, 2011 1:30 PM

Can someone with
A) an understanding of this material
emoticon a native-speaker-level understanding of English with obsessiveness for punctuation and grammar

re-write this so that it is intelligible?

This assumes, of course, that Liferay management will continue their "you're on your own, pal" tradition of non-existent documentation
Posted on 11/28/11 1:27 PM.
emoticons enabled - AWESOME. Let's try again...

Can someone with
A ) an understanding of this material, and
B ) a native-speaker-level understanding of English with obsessiveness for punctuation and grammar
Posted on 11/28/11 1:30 PM in reply to Matt Walker.