Configuring Alfresco SSL certificates

Alfresco is configured by default to use HTTPs in port 8443 to serve SOLR indexing requests. In order to identify this request, authentication is wanted for this SSL communication.

If you are using Alfresco default installer, your running SSL certificates are the same as any other developer using this method, because of they are distributed with Alfresco itself.

In order to configure your own certificates, two methods are available:

• Generate your own self-signed certificates, recommended for testing or Intranet environments
• Import certificates issued by an external CA, recommended for Internet environments

A repo certificate for Alfresco Repo and a client certificate for SOLR web application must be generated and they have to be included in keystores and truststores to build a confident relation between Alfresco and SOLR web apps.

Generating self signed certificates using Alfresco script

When using Alfresco installer, a helper script is copied to:

/opt/alfresco/alf_data/keystore/generate_keystores.sh

Alfresco documentation will help to configure that shell, but I’m including some notes below in order to avoid mistakes:

• ALFRESCO_HOME variable should include Alfresco installation folder, for instance /opt/alfresco
• ALFRESCO_KEYSTORE_HOME variable should include Alfresco default keystore folder, for example /opt/alfresco/alf_data/keystore
• CERTIFICATE_HOME variable should include a temporary place to store generated certificates, for example /home/alfresco
• SOLR_HOME variable should include SOLR configuration folder, for example /opt/alfresco/solr4
• REPO_CERT_DNAME and SOLR_CLIENT_CERT_DNAME variables can be configured to include your own data in organization, location or country
• Every line including $SOLR_HOME/templates/* can be removed, because it’s not required and it’s not used in Alfresco 5 instances

Once configured, the execution of this script will update Alfresco configuration to include your own SSL certificates, both Alfresco and SOLR sides.

Importing certificates issued by an external CA

However if you need to provide qualified electronic certificates for SSL, you will need to include some external certificates issued by an external CA.

The simplest is to rename that issued certificates as ssl.repo.crt for Alfresco side and ssl.repo.client.crt for SOLR side and then copy both them to CERTIFICATE_HOME folder set in generate_keystores.sh script. After that, comment or remove any line starting with "$JAVA_HOME/bin/keytool" and execute the script.

Your Alfresco installation will have been updated to use your certificates provided by the external CA.

Installing your certificates from scratch

However, if you decide to build your own truststore and keystore for Alfresco and SOLR web applications, some other work is required.

Start by requesting two certificates to your CA:

• ssl.repo
  • Certificate used to identify Alfresco Web App
• ssl.repo.client
  • Certificate used to identify SOLR Web App

After that, build four different stores including these certificates:

• ssl.keystore
  • Private key ssl.repo
• ssl.truststore
  • Public key ssl.repo
  • Public key ssl.repo.client
• ssl.repo.client.keystore
  • Private key ssl.repo.client
• ssl.repo.client.truststore
  • Public key ssl.repo

Copy the repo stores (ssl.keystore and ssl.truststore) to /opt/alfresco/alf_data/keystore folder and both client stores (ssl.repo.client.keystore and ssl.repo.client.truststore) to /opt/alfresco/solr4/archive-SpacesStore/conf and opt/alfresco-5.1.f/solr4/workspace-SpacesStore/conf.

You can use default password for every keystore or truststore (kT9X6oe68t) or you can change it for a new one (let’s say password). If you changed that passwords, you have to update different configuration files:

• /opt/alfresco/tomcat/conf/server.xml
• /opt/alfresco/solr4/archive-SpacesStore/conf/ssl-keystore-passwords.properties
• /opt/alfresco/solr4/archive-SpacesStore/conf/ssl-truststore-passwords.properties
• /opt/alfresco/solr4/workspace-SpacesStore/conf/ssl-keystore-passwords.properties
• /opt/alfresco/solr4/workspace-SpacesStore/conf/ssl-truststore-passwords.properties

Just replace kT9X6oe68t for your selected password in every file.

From this point your Alfresco installation will use the new certificates for SSL connections.

Simplifying certificates management

As the JVM itself includes its own truststore, usually located at java/lib/security/cacerts with password changeit, Alfresco truststores (ssl.truststore and ssl.repo.client.truststore) can be ignored. Just importing both certificates in JVM cacerts file and configuring the keystores as described above, Alfresco will run properly with your new keys.

In fact, including certificates itself in JVM Truststore is not required at all. It should be enough by including issuer certificate, that is, the public part of the certificate of the CA which was issuing that SSL repo and SSL client certificates. So the figure can be expressed as follows.

This cacerts store can be used also to import any other SSL certificates, as LDAP ones.

Generating self signed certificates using your own script

Axel Faust shared a customized script to generate this keys and to update Alfresco keystores and truststores according to that simplified scheme.

Required tools:

• OpenSSL, a cryptographic library to manage electronic certificates and even to create your own CA
• keytool, the standard Oracle Java program to manage certificates (included by default in the JDK)

# own (internal) CA created using standard OpenSSL, e.g. following https://jamielinux.com/docs/openssl-certificate-authority/
 
# Repository Certificate
openssl req -newkey rsa:1024 -nodes -out repository.csr -keyout repository.key

openssl ca -batch -notext -in repository.csr -out repository.cer
 
# Repository Keystore => client authentication Repo => SOLR
openssl pkcs12 –export –out repository.p12 –inkey repository.key –in repository.cer –certfile ca.cer

keytool –importkeystore -srcstoretype JKS -srcProviderName SUN –srckeystore repository.p12 –srcstoretype pkcs12 \
-deststoretype JKS -destProviderName SUN –destkeystore ssl.repo.keystore –srcalias 1 –destalias repo.ssl

keytool –import –trustcacerts -storetype JKS -providerName SUN –file ca.cer –alias ca.ssl –keystore ssl.repo.keystore
 
# SOLR Certificate
openssl req -newkey rsa:1024 -nodes -out solr.csr -keyout solr.key

openssl ca -batch -notext -in solr.csr -out solr.cer
 
# SOLR Keystore => client authentication SOLR => Repo
openssl pkcs12 –export –out solr.p12 –inkey solr.key –in solr.cer –certfile ca.cer

keytool –importkeystore -srcstoretype JKS -srcProviderName SUN –srckeystore solr.p12 –srcstoretype pkcs12 \
 -deststoretype JKS -destProviderName SUN –destkeystore ssl.solr.keystore –srcalias 1 –destalias solr.ssl

keytool –import –trustcacerts –file ca.cer –alias ca.ssl –keystore ssl.solr.keystore
 
# Generic Truststore => Apache HTTPd as HTTPS Server
keytool –import –trustcacerts -storetype JKS -providerName SUN –file ca.cer –alias ca.ssl –keystore ssl.truststore

Once this script has been executed, following keystores and truststores are available:

• ssl.repo.keystore
• ssl.solr.keystore
• ssl.truststore

Configuring SSL by using Apache or Nginx

However, both two methods described above are not recommended for production environments, because installing a Web Server in front of Apache Tomcat provides more control an easier administering tasks.

Detailed configuration by using Let’s Encrypt CA is available at keensoft blog. Also Alfresco documentation provides instructions to configure an SSL environment for production environments.

In this scenario, as SOLR is not reachable from the outside, SSL can be removed from Tomcat, avoiding the overhead produced by cyphering communications between Alfresco and SOLR and improving system performance.

There are different options to configure SSL communications in Alfresco, but using default installation resources will produce risks in your system. Choose any of this alternatives and provide a safer platform to your users.