Alfresco solr ssl certificate renewal

Alfresco Enterprise Version:

This information is applicable to Alfresco Enterprise 4.x versions

Summary:

The SOLR server indexes data in Alfresco by periodically 'tracking' the changes made to Alfresco. It does so by calling a RESTful API that describe the latest 'transactions' to it. The Alfresco server performs searches through the SOLR server by issuing queries through a special API.

Solution:

There needs to be two-way communication between the Alfresco server and the SOLR server. So that nobody else can abuse this communication channel, it must be secured by means of HTTPS encryption and a mutual client certificate authentication.
There are three important points involved in setting up this mutual trust relationship:

1. Creating a 'keystore directory' and configuring the Alfresco and Solr servers to use it
2. Generating and installing your own 'secure certificates'
3. Replacing default certificates and handling 'certificate expiry'

If you installed Alfresco and SOLR via the Installation Wizard, there is no need to perform step 1, as the directory and associated configuration will already be present. You can proceed straight to step 2.
If you installed SOLR manually, then please carefully review steps 1 and 2 - as otherwise, without configuring your own keystore directory, you may be picking up expired, default keys.

 

1. Creating a keystore directory and configuring the Alfresco and Solr servers to use it

The following instructions assume SOLR has already been extracted and configured, as described in http://docs.alfresco.com/4.0/topic/com.alfresco.enterprise.doc/tasks/solr-webapp-distrib.html.
We will use to refer to the tomcat directory where Alfresco is installed and to the tomcat directory where Solr is installed. These may be the same or different directories, depending on whether you have chosen to install Solr on a standalone server or the same server as Alfresco.

1. Ensure that Alfresco has already been started at least once, i.e. the /webapps/alfresco/WEB-INF directory exists
2. Create and populate a keystore directory for the Alfresco and SOLR servers. By convention, we will create this in /alf_data/keystore. Please note that at this stage the keystore directory will just be a template, containing standard keys available to everybody. To secure the installation you must carry out the steps to generate new keys, specified in section 2.
• Unix:
• mkdir -p /alf_data/keystore
• cp /webapps/alfresco/WEB-INF/classes/alfresco/keystore/* /alf_data/keystore
• Windows:
• mkdir \alf_data\keystore
• copy \webapps\alfresco\WEB-INF\classes\alfresco\keystore\* \alf_data\keystore
3. Configure the Alfresco and SOLR tomcats to use the keystore and truststore for https requests, by editing the specification of the connector on port 8443 in /conf/server.xml and /conf/server.xml as follows, remembering to replace /alf_data/keystore with the full path to your keystore directory

                  maxThreads="150" scheme="https" keystoreFile="/alf_data/keystore/ssl.keystore" keystorePass="kT9X6oe68t" keystoreType="JCEKS"
                  secure="true" connectionTimeout="240000" truststoreFile="/alf_data/keystore/ssl.truststore" truststorePass="kT9X6oe68t" truststoreType="JCEKS"
     clientAuth="false" sslProtocol="TLS" />
   

4. Configure Alfresco itself to use the keystore and truststore for client requests to SOLR, by specifying dir.keystore in ALFRESCO_TOMCAT_HOME/shared/classes/alfresco-global.properties, remembering to replace /alf_data/keystore with the full path to your keystore directory
• dir.keystore=/alf_data/keystore
5. Configure an identity for the Alfresco server. In /conf/tomcat-users.xml, add the following. Note that you can choose a different username, such as the host name of the Alfresco server, but it must match the REPO_CERT_DNAME you will later specify in the keystore in section 2.

6. Configure an identity for the Solr server. In /conf/tomcat-users.xml, add the following. . Note that you can choose a different username but it must match the SOLR_CLIENT_CERT_DNAME you will later specify in the keystore in section 2.

    

7. To complete the installation, it’s necessary to secure communications by generating your own keys. See section 2.

2. Generating and installing your own secure certificates

Use these instructions to replace or update the keys used to secure communications between Alfresco and SOLR, using secure keys specific to your Alfresco installation.
NOTE: If applying these instructions to a clustered installation, the steps should be carried out on a single host and then the generated .keystore and .truststore files must be replicated(used) on all other hosts in the cluster.
The following instructions assume that solr has been extracted and a keystore directory has already been created, either automatically by the Alfresco installer, or manually by following the instructions in section 1

1. Obtain the file generate_keystores.sh (for Linux and Solaris) or generate_keystores.bat (for Windows) from the Customer Support website under 'Online Resources > Downloads > Alfresco Enterprise 4.0 > '
2. Edit the environment variables at the beginning of the file to match your environment
• If you are updating an environment created by the Alfresco installer, you will only need to edit ALFRESCO_HOME to specify the correct installation directory
• For manual installations, carefully review ALFRESCO_KEYSTORE_HOME, SOLR_HOME, JAVA_HOME, REPO_CERT_DNAME and SOLR_CLIENT_CERT_DNAME and edit as appropriate
3. Run the edited script
4. You should see the message 'Certificate update complete' and another message reminding you what dir.keystore should be set to in alfresco-global.properties

3. Replacing default certificates and handling certificate expiry

If you see errors such as the following in the logs, it means that the expiry date set in one or more of your SSL certificates has passed.

17:35:14,109 ERROR [org.quartz.core.ErrorLogger] Job (DEFAULT.search.archiveCoreBackupJobDetail threw an exception.
org.quartz.SchedulerException: Job threw an unhandled exception. [See nested exception: org.alfresco.error.AlfrescoRuntimeException: 07180158 Bakup for core archive feailed .... ]
at org.quartz.core.JobRunShell.run(JobRunShell.java:227)
at org.quartz.simpl.SimpleThreadPool$WorkerThread.run(SimpleThreadPool.java:563)
Caused by: org.alfresco.error.AlfrescoRuntimeException: 07180158 Backup for core archive failed ....
at org.alfresco.repo.search.impl.solr.SolrBackupClient.executeImpl(SolrBackupClient.java:158)
at org.alfresco.repo.search.impl.solr.SolrBackupClient.execute(SolrBackupClient.java:112)
at org.alfresco.repo.search.impl.solr.SolrBackupJob.execute(SolrBackupJob.java:58)
at org.quartz.core.JobRunShell.run(JobRunShell.java:216)
... 1 more
Caused by: org.apache.solr.client.solrj.SolrServerException: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path validation failed: java.security.cert.CertPathValidatorException: timestamp check failed

1. It is recommend to generate new secure certificates following the instructions in section 2
   As a temporary measure, you can substitute all your existing .keystore, .truststore and .p12 files with the new Alfresco default files. These can be found in zip file 'keystores.zip' available in the support website download section with the generate keystore scripts.
   
2. There are numerous locations for these files in the Alfresco/SOLR install, you must find and replace all the .keystore, .truststore and .p12 files with the new secure certificates

This is an example list of typical (v4.0.2.x ) file paths to be updated is below, but please be aware these files may be located in different relative locations in your system:
/alf_data/keystore/browser.p12
/alf_data/keystore/ssl.truststore
/alf_data/keystore/ssl.keystore
/alf_data/solr/workspace-SpacesStore/conf/ssl.repo.client.truststore
/alf_data/solr/workspace-SpacesStore/conf/ssl.repo.client.keystore
/alf_data/solr/archive-SpacesStore/conf/ssl.repo.client.truststore
/alf_data/solr/archive-SpacesStore/conf/ssl.repo.client.keystore
/alf_data/solr/templates/test/conf/ssl.repo.client.truststore
/alf_data/solr/templates/test/conf/ssl.repo.client.keystore

Additional NOTEs:

• Use the generate keystore script provided with the Alfresco Enterprise version you are updating
• In the case of version 4.0.2, ideally it is best to update your install to 4.0.2.9, else use the scripts found under 4.0.2.9 downloads for 4.0.2 secure certificate generation
• The /alf_data/solr/templates directory does not exist in 4.0, 4.0.1 installs.
• Users connecting directly to SOLR web app will need to replace their browser.p12 file with the new one (http://docs.alfresco.com/4.0/topic/com.alfresco.enterprise.doc/tasks/solr-SSL-connecting.html)
• (cluster) If applying these instructions to a clustered installation, the .keystore and .truststore files must be replicated(used) on all other hosts in the cluster