Nuxeo Installation & Debug & Apache Reverse Proxy Setup with Client Certificate Authentication

Install Nuxeo on Ubuntu Server 12.04

Refer to

http://www.nuxeo.com/en/downloads/download-debian

http://doc.nuxeo.com/display/ADMINDOC/Installing+the+Nuxeo+Platform+on+Linux:

  1. determine codename of the Linux distribution ("precise" for Ubuntu 12.04 LTS)
  2. determine which version of Nuxeo is to be installed - "releases" for LTS and "fasttracks" for fast track.
  3. add nuxeo repository according to want-to-install version, i.e. add file "/etc/apt/sources.list.d/nuexo.list" with one line "deb http://apt.nuxeo.org/ lucid releases"
  4. add nuxeo key, first save the text to a file "nuexo.key", then run "apt-key add nuexo.key" (URL: http://apt.nuxeo.org/nuxeo.key)
  5. "sudo apt-get update"
  6. "sudo apt-get install nuxeo"... a long long download, then a simple configuration screen.

To install a mail server for nuxeo server to send email:

  1. sudo apt-get install postfix
  2. test it: sendmail you@domain.com
  3. if not received: mailq (check queue)
  4. configure nuxeo to use local mail server with Administrator account and web interface (Admin Center -> System Information -> Setup)
  5. follow a document and try to receive change notification
  6. sudo dpkg-reconfigure postfix (most important: DO NOT OPENRELAY)
  7. further secure postfix to listen only on local IP: http://www.cyberciti.biz/faq/postfix-receive-mail-on-specific-network-interfaces/

Reverse Proxy with Apache + Authentication with User Certificate (Possibly Self-signed)

References:

http://doc.nuxeo.com/display/ADMINDOC/HTTP+and+HTTPS+reverse-proxy+configuration

http://answers.nuxeo.com/questions/4609/nuxeo-live-edit-throws-a-java-npe

http://doc.nuxeo.com/pages/viewpage.action?pageId=6030082

Tested Environment:

Below configuration has been tested and was found to work on:

  • Server: Ubuntu Server 12.04 LTS + Nuxeo Platform 5.6
  • Ubuntu Client: Ubuntu Desktop 12.04 LTS + Firefox + Nuxeo LiveEdit Protocol Handler 0.5.2
  • Windows Client: both Windows 7 and Windows XP + Nuxeo LiveEdit plugin for IE

Steps:

(1) After installing Apache server, enable site ssl and necessary modules

a2ensite default-ssl

a2enmod ssl proxy proxy_http headers rewrite

service apache2 restart

(2) Edit site configuration file ("/etc/apache2/sites-enabled/default-ssl")

Configurations below enables reverse proxy through https, and also enables authentication by client certificate. It also works well with LiveEdit and Nuxeo Drive.

It's not sufficient to just drop this configure file and expect things to work. Read carefully comments below the configuration file for further details - note that other files and actions are also involved to make this configuration work!

<IfModule mod_ssl.c>
<VirtualHost *:443>
        ServerName nutest.test.com
        ServerAlias nutest.test.com
        ProxyPass / http://127.0.0.1:8080/
        ProxyPassReverse / http://127.0.0.1:8080/
        RequestHeader append nuxeo-virtual-host "https://nutest.test.com/"
        ServerAdmin webmaster@localhost
        SSLVerifyClient optional
        <ProxyMatch ^http\://127\.0\.0\.1\:8080((/nuxeo/nxstartup.faces)|(/nuxeo/login.jsp))>
                SSLRequireSSL
                Include /etc/apache2/access_control
                SSLCACertificatePath /etc/ssl/test_certs/
               
                SSLVerifyDepth  3
                RewriteEngine        on
                RewriteCond     %{SSL:SSL_CLIENT_VERIFY} !=SUCCESS
                RewriteRule     .? - [F]
                ErrorDocument 403 "ACCESS DENIED: You need a client side certificate issued by EAST IP to access this site"
        </ProxyMatch>
        ErrorLog ${APACHE_LOG_DIR}/error.log
        LogLevel warn
        CustomLog ${APACHE_LOG_DIR}/ssl_access.log combined
        SSLEngine on
        SSLCertificateFile    /etc/ssl/certs/nutest.pem
        SSLCertificateKeyFile /etc/ssl/private/nutest.key
        BrowserMatch "MSIE [2-6]" \
                nokeepalive ssl-unclean-shutdown \
                downgrade-1.0 force-response-1.0
        BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
</VirtualHost>
</IfModule>

Comments and Explanations (IMPORTANT, READ CAREFULLY):

  • ServerName and ServerAlias must be set for LiveEdit to work on certain Java versions. See http://answers.nuxeo.com/questions/4609/nuxeo-live-edit-throws-a-java-npe
  • ProxyPass, ProxyPassReverse and RequestHeader directives are standard setup from Nuxeo documentation, to enable reverse proxy. See http://doc.nuxeo.com/display/ADMINDOC/HTTP+and+HTTPS+reverse-proxy+configuration
  • Outside <ProxyMatch> block, SSLVerifyClient is set to "optional" to allow the RewriteEngine inside ProxyMatch to work and, with the rewrite directives, provide a better error message when client certificate is rejected. If SSLVerifyClient were put inside ProxyMatch, then IE8 would have a problem connecting. The reason, per my understanding by observing (openssl s_client) and guessing, is that when SSLVerifyClient is put inside proxy, the first response does not require client to present certificate. Although from the second request on, client is indeed requested to present certificate, IE8 somehow has a problem handling it (the renegotiation?); when put putside, SSLVerifyClient must be set to "optional" and must NOT be set to "require", since we want to allow LiveEdit to work, which does not present user certificate.
  • <ProxyMatch...> block requires client certificate authentication for matching resources. The regular expression in this directive matches PROXYED resource, which include two resources that client will encounter when log into server. More paths can be included into the expression to make the server more secure. However, there are reasons why not simply require client certificate authentication on everything:
    • Must exclude two resources: /nuxeo/restAPI/ and /nuxeo/nxliveedit.face. The reason for exclusion of the two resources is that the LiveEdit plugin will not provide client certificate for server to verify. Therefore, to walk around this problem, server do not request client certificate for resources accessed by LiveEdit plugin. Expression like "<ProxyMatch ^http\://127\.0\.0\.1\:8080(?!((/nuxeo/restAPI/)|(/nuxeo/nxliveedit.face)))>" will exclude these two resources.
    • Client certificate authentication limits file upload size, see below "Known Potential Problem & Solution" for details. So, needs to exclude resource that might be requested with POST request with file upload.
    • Then, the sample above only requires client certificate authentication for two matching resources, a simple (but less secure) way to both implement client certificate authentication, and circumvent above problems.
  • Within <ProxyMatch> block, SSLRequireSSL requires SSL connection
  • Within <ProxyMatch> block, "Include /etc/apache2/access_control" includes files in the configured dir into this configuration. Included files may, for example, check up the client certificates. Create the configured dir and put control directives into any file in that dir, for example:
    • SSLRequire %{SSL_CLIENT_S_DN_Email} in {"email_address_of_allowed_user@allowed.com"}
    • SSLRequire %{SSL_CLIENT_S_DN_O} in {"Allowed Organization"}
  • Within <ProxyMatch> block, SSLCACertificatePath specifies a dir to place the trusted CA certificates. Only client certificates issued by the trusted CAs can be accepted. After placing the CA certificates into that dir, cd to the dir and execute "c_rehash ." to create the required symbolic links; Alternatively, if we use just a few certificates, we can use SSLCACertificateFile directive instead of SSLCACertificatePath.
  • Within <ProxyMatch> block, SSLVerifyDepth specifies the depth of trust link. Increase the number if the trust link is long.
  • SSLCertificateFile and SSLCertificateKeyFile provide the server certificate and private key
  • The rest of the configuration is from the standard configuration template

(3) Client-side setup

First, import the client certificate into web browser and try to access and login Nuxeo. If it does not work, check the reverse proxy and client certificate authentication settings, as well as the log files on server (/var/log/apache2/ssl_access.log).

If uses self signed certificate or certificate issued by an untrusted CA, import the CA certificate into browser.

If client uses LiveEdit, and the issuer of the client certificate is not trusted by the Java Runtime Environment (JRE) on client end (for example, self signed) in which the LiveEdit plugin runs, import the issuer's certificate into the JRE's cacerts keyring with the JRE's keytool:

keytool -importcert -trustcacerts -alias alias_for_your_ca -file your_ca_cert.pem -keystore /opt/jdk1.7.0_09/jre/lib/security/cacerts

(4) Debug LiveEdit Problems

If in any case LiveEdit does not work and throw a Java exception, do the follows to diagnose the problem:

First, find the log file for the plugin

For Firefox, look at "Tools -> Add-ons -> Nuxeo LiveEdit Protocol Handler -> Preferences" and find the working dir. For windows, search under the user dir for the log file. The log file may exist only AFTER the Java exception is thrown and named "nuxeo-liveedit-openoffice-extension.log"

Then, inspect the log file and search for solution

The log file contains the complete stack dump and other information to help to diagnose the problem.

Server-end Trouble Shooting

When something went wrong it's worth to check:

  • If something does not work via Apache front, does it work with Nuxeo directly? (so is that an Apache issue?)
  • /var/log/apache2 - repeat the failure and check the log here, anything unusual? (not 200, 3XX? especially, 4XX?)
  • /var/log/nuxeo - nuxeo log

Known Potential Problems & Solutions

1. Lack of ServerAlias / ServerName directives causing failure of Live Edit

See http://answers.nuxeo.com/questions/4609/nuxeo-live-edit-throws-a-java-npe

Symptom: "javax.net.ssl.SSLProtocolException: handshake alert: unrecognized_name" found in Live Edit log

Solution: add "ServerAlias" "ServerName" directive in Apache configuration

2. Server Certificate not trusted by Client Java Environment where Live Edit plugin is running

Solution: import the issuer (CA) certificate, see above

3. Live Edit does not provide client certificate to server

Walk around: do not request client certificate authentication for resources that Live Edit would request, see above

4. When uploading document exceeding certain size, upload will fail

Symptom: in ssl_access.log found http response 413 in POST requests indicating request over-size; in error.log found "could not buffer message body to allow SSL renegotiation to proceed";

Reason: when SSLVerifyClient directive is used or otherwise requires buffer request in memory, large POST request (file upload) could fail. See Apache document for directive SSLRenegBufferSize.

Walk around: not a good solution to just increase buffer size, because it allows denial-of-service attack and hardly memory buffer could be large enough for upload. Just do not request client verify for upload resources.

5. Live Edit does not work on IE9+, unless in compatible mode

This is a known issue and solutions are given here: http://doc.nuxeo.com/display/USERDOC56/Live+Edit+compatibility+table

I chose to change Live Edit detection to "server". Users will see Live Edit icon regardless whether or not plugin is installed. This can be nuisances but still better than requesting user to adjust their browsers.