Updating SSL Certificates In Solr

So Your Solr SSL Certificate Is Expiring Soon?

Let's deal with that. If you've set up your Sitecore instance in Azure to point to an external Solr instance, then you've likely got it setup with its own SSL certificate. If you were running Sitecore 9 in Azure it's far more likely you'd be running Azure Search but in a few instances, we've set up separate Solr instances. Once a year, or depending upon the lifespan of your SSL certificate, you will need to swap out the cert with a valid one... preferably before it expires.

Unlike swapping out an SSL binding in Azure, or an IIS binding on a local instance, this change only requires a simple restart of the service after editing of a single cmd file.

Replacing The Certificate

Upload PFX File

My recommendation is to create a pfx file of your certificate prior to all this. Upload your pfx file to a folder on the Solr server. My suggestion would be: <solr directory>/server/etc/<your cert.pfx>

Update solr.in.cmd File

Next, in your favourite text editor, open up <solr directory>/bin/solr.in.cmd.

REM Uncomment to set SSL-related system properties
REM Be sure to update the paths to the correct keystore for your environment
set SOLR_SSL_KEY_STORE=C:\<solr directory>\server\etc\solr-ssl.keystore.jks
set SOLR_SSL_KEY_STORE_PASSWORD=secret
set SOLR_SSL_KEY_STORE_TYPE=JKS
set SOLR_SSL_TRUST_STORE=C:\<solr directory>\server\etc\solr-ssl.keystore.jks
set SOLR_SSL_TRUST_STORE_PASSWORD=secret
set SOLR_SSL_TRUST_STORE_TYPE=JKS
set SOLR_SSL_NEED_CLIENT_AUTH=false
set SOLR_SSL_WANT_CLIENT_AUTH=false

Now, what you want to do is update the SOLR_SSL_KEY_STORE lines and the SOLR_SSL_TRUST_STORE lines to point to the new file (.pfx), update the password line, and if need be update the type. In my testing, I've was able to run it with the type line still commented out with REM.

Once edited, it should resemble the following.

set SOLR_SSL_KEY_STORE=C:\<solr directory>\server\etc\new_solr_ssl_cert.pfx
set SOLR_SSL_KEY_STORE_PASSWORD=secret123
set SOLR_SSL_KEY_STORE_TYPE=PKCS12
set SOLR_SSL_TRUST_STORE=C:\<solr directory>\server\etc\new_solr_ssl_cert.pfx
set SOLR_SSL_TRUST_STORE_PASSWORD=secret123
set SOLR_SSL_TRUST_STORE_TYPE=PKCS12

Restarting The Solr Service

With the edits in place, it's now time to restart the Solr service. If you're on Windows and you've got the Solr installed as such, just open up Services, find your Solr service, and restart it. If it fails to restart, see below for potential causes. If you don't have Solr running as a service, that's something you will want to look into. My suggestion is to have a look at nssm.

Point Of Note

When updating to Solr certificate, there's one thing you need to be aware of: The password should not contain any special characters. It's not uncommon for SSL certs to contain special characters, but Solr doesn't like them in the format we have to work with. It should be purely alpha-numeric. If it does, during the restart you may get a message that the service failed to restart. If you get that error, this is certainly something to check.

If changing the password does not work, validate you have the correct password, and the location of the pfx file is correct and that if you set a TYPE it is correct. If none of that works, replace revert your change and restart your Solr service to re-install the old certificate until you can determine what may be incorrect.

Testing Your SSL Cert

Once the service has restarted, and an appropriate time has passed, you can open up a browser and load up https://<domain name>:8983/solr. Certainly, if you've set up Solr to run on a separate port, swap in with that. If you're not prompted as the destination then right-click on the lock icon in the URL and verify your SSL cert is showing as the one being used.