Sitecore 9 – Importing a Wildcard or Public CA Certificate into Solr

If you are using Sitecore 9 with Solr, you are most likely (should) be using Solr over SSL/HTTPS. Self-Signed Certificates are an option in non-Production environments but in the following scenarios you should use a Public Certificate Authority:

• Production on IaaS
• Azure AppServices with Solr on IaaS (AppServices cannot use Self-Signed Certificates, but require a CA installed on the Solr VMs or Load Balancer in front of the Solr VMs to communicate)

In these scenarios you have two options for your public certificate. This assumes you are using a Wildcard Certificate to cover your domain versus individual certificates per server. The following instructions will work for both scenarios.

The first is offloading to the load balancer. This may not be an option if your load balancer does not have SSL Offloading as a feature (ex. Azure Load Balancers). Secondly, use the Java Keystore as Solr does not have a place to install certificates per se, but leverages the underlying Java infrastructure for its certificate management.

Importing an Wildcard or Public CA to the Java (Solr) Keystore

Assuming you have a .p12 or .pfx Certificate, you can import this into your Keystore via the following (Windows instructions):

• Import your .p12 or .pfx into the Windows Trusted Root Store as you need both the cert installed on the Server and in the Keystore for it to function
• Important: The password for your .p12 or .pfx needs to match your JKS (Java Keystore). Example, if your JKS has a password of “secret” the certificate should have the password of “secret”. Without this, I have noticed issues with Solr not starting. You can always import the certificate with a complex password and then export it with the new password (delete the certificate with the old password before importing the new certificate)
• Open a command prompt in Administrator mode
• Browse to your Java bin where the Keystore tool is stored. Ex: cd C:\Solr\jdk1.8.0_144\bin
• List your current certificates to view what is currently there (assuming your Keystore has a password of “secret” and is in the following location):

  keytool -list -v -keystore C:\Solr\solr-6.6.2\server\etc\solr-ssl.keystore.jks -storepass secret

• Remove any unnecessary certificates via the following (Note: the “alias” in the previous command and may look like a GUID):

  keytool -delete -alias "te-4342d465-6dd8-40ca-b495-772fc50f04d6" -keystore C:\Solr\solr-6.6.2\server\etc\solr-ssl.keystore.jks -storepass secret

• Import your .pfx via the following (Important: You will be prompted for multiple passwords for both your Keystore and the actual password that came with your .p12 or .pfx):

  keytool -importkeystore -srckeystore C:\certificates\mywildcard.pfx -srcstoretype pkcs12 -destkeystore C:\Solr\solr-6.6.2\server\etc\solr-ssl.keystore.jks -deststoretype JKS

• Restart the Solr application and verify that Solr is now using your Wildcard or Public CA Certificate for SSL

Java Keystore Gotcha

Be warned that if you attempt to import a .pfx Certificate that has special characters in its password, the Java Keystore will “import” it and display it in the Keystore but likely produce TLS errors in the Solr application when you try to browse to the site. This is due to a bug in the Java Keystore that has not been resolved yet that does not allow special characters in the .pfx password. To resolve this, you can export the .p12 or .pfx you imported into your Windows Server via the Certificates MMC and set a new password that does not have special characters. Use this certificate for your Keystore import.