Sitecore + SOLR + SSL

When you are doing local Sitecore development, you might need to setup a local SOLR instance to host your indexes. This is especially important if your project isn’t using Lucene indexes in production and you need to replicate the environment. When replicating production for troubleshooting, it is also useful to replicate the security setup as well, including SSL.

In this article, I’ll cover how you can take your SOLR installation and get it running on HTTPS in 11 easy steps!

Installing SOLR

Before you can enable SSL, you need to make sure SOLR is installed. Sitecore provides a walkthrough of this on the doc site:

https://doc.sitecore.net/sitecore_experience_platform/setting_up_and_maintaining/search_and_indexing/walkthrough_setting_up_solr

When installing Solr locally, I prefer using Bitnami (https://bitnami.com/stack/solr/installer). By default, Bitnami displays the latest version for download on their site. At the time of writing this was 6.6.0. However, they do have archives where you can get installers for older versions so you can meet Sitecore recommended versions.

Example Bitnami archives:

• 6.1: https://downloads.bitnami.com/files/stacks/solr/6.1.0-2/bitnami-solr-6.1.0-2-windows-installer.exe
• 5.1: https://downloads.bitnami.com/files/stacks/solr/5.1.0-1/bitnami-solr-5.1.0-1-windows-installer.exe
• 4.10: https://downloads.bitnami.com/files/solr/bitnami-solr-4.10.3-0-windows-installer.exe
• 4.1: https://downloads.bitnami.com/files/solr/bitnami-solr-4.1.0-1-windows-installer.exe

View Sitecore’s compatibility with SOLR versions: https://kb.sitecore.net/articles/227897

How to enable SSL

Using the JDK Keytool command we can create self-signed certificates to be used by the SOLR instance. For the following steps, the following variables are used. You should replace these variables with your applicable path when typing out the commands, or just add the path to your system’s environment variables.

• {JAVA_HOME} : The path where you have Java installed (e.g.C:\Program Files (x86)\jre1.8.0_131\)
• {SOLR_HOME} : The path where you have Solr installed (e.g. C:\Bitnami\apache-solr\)

NOTE: The following steps are based on instructions provided by Apache (https://lucene.apache.org/solr/guide/6_6/enabling-ssl.html) with alterations that I used to simplify the flow:

1. Open command prompt
2. Change to the Solr ‘etc’ directory:

       cd "{SOLR_HOME}\server\etc"

3. Execute the keygentool command

       "{JAVA_HOME}\bin\keytool.exe" -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.jks -ext SAN=DNS:localhost,IP:127.0.0.1 -dname "CN=localhost, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"
   
   

   This will generate the keystore with a password of ‘secret’ as valid for localhost and 127.0.0.1. You can add other DNS and IPs as desired, or skip hostname verification.

   See full instructions at: https://lucene.apache.org/solr/guide/6_6/enabling-ssl.html

4. Convert generated JKS to PKCS12

       "{JAVA_HOME}\bin\keytool.exe" -importkeystore -srckeystore solr-ssl.keystore.jks -destkeystore solr-ssl.keystore.p12 -srcstoretype jks -deststoretype pkcs12

5. Enter password when prompted. The password ‘secret’ was used in the previous step.Remember to use your password instead if you changed it in the keygen command parameters.
6. Open Windows Explorer and navigate to the ‘etc’ directory (“{SOLR_HOME}\server\etc”)
7. Double-click on the generated ‘p12’ file (solr-ssl.keystore.p12 if you used the default parameters from the previous steps)
8. In the dialog, specify the following values:
   • Store Location: Local Machine
   • File name: Leave as provided
   • Password: secret
   • Certificate Store: Trusted Root Certification Authorities

   Remember to use your password instead if you changed it during the previous steps.

9. Open the solr.in.cmd file for editing (e.g. {SOLR_HOME}\bin\solr.in.cmd)
10. Edit the SSL settings:

        set SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks
        set SOLR_SSL_KEY_STORE_PASSWORD=secret
        set SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks
        set SOLR_SSL_TRUST_STORE_PASSWORD=secret
        set SOLR_SSL_NEED_CLIENT_AUTH=false
        set SOLR_SSL_WANT_CLIENT_AUTH=false

    Remember to update passwords and file paths to match to the parameters you specified.

11. Restart SOLR to pick up the changes.

What about Sitecore PaaS?

If you are deploying to PaaS, you cannot use self-signed certificates for your SOLR setup as you will not be able to add it to the Sitecore app service certificate store. In this scenario, you will want to use something like https://letsencrypt.org/ to create your certificate and install that into your Solr VM.