Configuring Fusion for SSL

The Fusion UI can be run over SSL for secure communication between any HTTP client and Fusion. Fusion uses the Java Secure Socket Extension (JSSE) framework to implement this functionality.

SSL provides both authentication and encryption services:

  • Authentication is carried out via digitally signed certificates and the exchange of public/private key data.

  • All data sent between the client and server is encrypted.

To configure Fusion for SSL you must:

  • Obtain a signed certificate that will be sent to web clients for authentication and put it in a JSSE keystore.

  • Configure the Fusion UI server to run on a secure port and use the SSL protocol.

SSL certificates

The SSL protocol is based on public-key cryptography where encryption keys come in public key, private key pairs. An SSL certificate is used to verify the authenticity of a particular server. It contains the web site name, contact email address, company information and the public key used to encrypt the communication which is shared with the entities that communicate with the owner of the public/private key pair.

The server has a locally protected private key that is accessible via a JSEE keystore. The keystore maintains both the server certificate and the private key, so that when a server authenticates itself to the client, it uses the private key from its keystore for the initial SSL handshake.

Importing certificates into the JSSE keystore

In a production environment, SSL certificates must be signed by a trusted third-party organization called a CA (Certificate Authority). Contact your sys admin to get a signed SSL certificate.

To store certificates, you can use the Java keytool Key and Certificate Management utility which is part of the JDK.

If you have signed certificates, then you create a JSSE keystore by using the keytool "import" command. In the following example, we have a signed certificate from a CA, in pfx format in a pkcs12 file called fusion.keystore.p12. The following command creates a new JSSE keystore (JKS):

keytool -importkeystore -srckeystore /opt/lucidworks/fusion/apps/jetty/ui/etc/fusion.keystore.p12 \
 -srcstoretype pkcs12 -destkeystore -deststoretype JKS

If you have the cert and private key as separate files, then you need to use openssl to create a pkcs12 file.

If you have an intermediate CA certificate, you can use it to generate the private key and certificate file using openssl.

Enabling SSL in the Fusion UI

  1. Run the following:

    cd {fusion_path}/apps/jetty/ui
    java -jar {fusion_path}/apps/jetty/home/start.jar --add-to-start=https
    This step requires an Internet connection. If no connection is available on the Fusion host, run the commands above on a separate host, then copy the resulting fusion/3.1.x/apps/jetty/ui/etc/keystore file to the Fusion host.
  2. Get the hashed version of your keystore password:

    cd {fusion_path}
    java -cp ./apps/libs/jetty-util-9.3.8.v20160314.jar <secret>

    Where <secret> is the password you used for the keystore.

  3. Edit fusion/3.1.x/apps/jetty/ui/start.ini to uncomment and add the hashed password from the previous step to these properties:

    • jetty.sslContext.keyStorePassword

    • jetty.sslContext.keyManagerPassword

    • jetty.sslContext.trustStorePassword

    For example:

    ## Keystore password
    ## Keystore type and provider
    # jetty.sslContext.keyStoreType=JKS
    # jetty.sslContext.keyStoreProvider=
    ## KeyManager password
    ## Truststore password
  4. Set the local SSL port by editing the jetty.ssl.port property.

    For example:

    ## Connector port to listen on
  5. Start Fusion with fusion/3.1.x/bin/fusion start.

    HTTPS should now be enabled on port 8864.

Disable HTTP

To entirely disable HTTP, remove the HTTP connector from the Jetty startup configuration:

rm {fusion_path}/apps/jetty/ui/start.d/http.ini

Configuring Fusion for SSL Solr/SolrCloud

To configure the Fusion HTTP client for a SSL-ed Solr or SolrCloud server, you must specify the system properties.

Step 1. Edit the configuration file

In the fusion/3.1.x/conf/ file, add the following properties to the options api.jvmOptions, connectors.jvmOptions, and ui.jvmOptions: \ \ \

Step 2. Register SolrCloud as a search cluster in Fusion

Send a request to the REST API 'searchCluster' endpoint:

curl -u admin:pass -H 'Content-type: application/json' -X POST 'http://localhost:8764/api/apollo/searchCluster' -d '
  "id" : "ssl",
  "connectString" : "localhost:2181",
  "cloud" : true

Step 3. Test: create collection, index data, query collection

Create collection in SolrCloud with configured SSL:

curl -u admin:pass -H 'Content-type: application/json' -X POST 'http://localhost:8764/api/apollo/collections' -d '
  "id" : "mycollection",
  "searchClusterId" : "ssl"

Index data using an existing pipeline:

curl -u admin:pass 'http://localhost:8764/api/apollo/index-pipelines/mycollection-default/collections/mycollection/index' -XPOST -H "Content-type: application/json" -d '{
  "id": "1",
  "foo_s": "bar",
  "spam_s": 42

Query the collection using the default query pipeline:

curl -u admin:pass 'http://localhost:8764/api/apollo/query-pipelines/mycollection-default/collections/mycollection/select?q=*:*'

Generating a self-signed certificate

If don’t have signed certificates from an external CA, then you can generate a set of self-signed certificates using the Java keytool utility to generate a public/private key pair and generate a self-signed certificate.

The keytool option "-genkeypair" generates a public/private key pair. It wraps the public key into an X.509 v3 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias. The full set of arguments to this command are:

    {-alias alias}
    {-keyalg keyalg}
    {-keysize keysize}
    {-sigalg sigalg}
    [-dname dname]
    [-keypass keypass]
    {-startdate value}
    {-ext ext}*
    {-validity valDays}
    {-storetype storetype}
    {-keystore keystore}
    [-storepass storepass]
    {-providerClass provider_class_name {-providerArg provider_arg}}

Arguments of interest are:

  • keyalg specifies the algorithm to be used to generate the key pair. This must be RSA in order to talk to browser clients IE and Navigator.

  • keysize specifies the size of each key to be generated. Depends on keyalg. For RSA, this should be 2048.

  • dname specifies the X.500 Distinguished Name to be associated with the alias, and is used as the issuer and subject fields in the self-signed certificate. If no distinguished name is provided at the command line, the user will be prompted for one. An X.500 Distinguished name is a set of named fields, of these, the field named "CN", ("Common Name"), is the internet-facing fully qualified domain name of the server.

  • keypass is a password used to protect the private key of the generated key pair. If no password is provided, the user is prompted for it. If you press RETURN at the prompt, the key password is set to the same password as that used for the keystore. keypass must be at least 6 characters long.

  • ext is used to embed extensions into the certificate generated. For Fusion, the server certificate should include the "SAN" or SubjectAlternativeName extension which allows alternative URIs and IP addresses to be associated with this certificate.

Keystore files created by the keystore tool are in the JKS format, which is a proprietary file format capable of storing multiple key-pairs, certificates, and symmetric encryption keys, and with all entries indexed by the keypair alias.

To generate a self-signed certificate for the Fusion UI running as "localhost", we use the following arguments:

keytool -genkeypair \
 -alias localhost -keyalg RSA -keysize 2048 \
 -keypass secret -storepass secret \
 -validity 365 -keystore my.keystore.jks \
 -ext SAN=DNS:localhost,IP: \
 -dname "CN=localhost, OU=org unit, O=org, L=loc, ST=st, C=country"

We check our work using the openssl tool to pretty-print the signed certificate in file "my.keystore.jks". This is not strictly necessary; this should always be done before sending the certificate to a CA to get it signed properly in order to verify that the certificate information is complete and correct.

To get from the keystore JKS format to a human-readable printout, it must be converted to the text-based "PEM" format, which is ASCII (Base64) armored data prefixed with a “—– BEGIN …” line. This requires three steps.

First, we use the keytool to convert the proprietary JKS format to the PKCS #12 format:

keytool -importkeystore \
 -srckeystore my.keystore.jks -destkeystore my.keystore.p12 \
 -srcstoretype jks -deststoretype pkcs12

This command prompts for passwords - as before, the password is "secret".

Next, we use openssl to convert the PKCS format to PEM format:

openssl pkcs12 -in my.keystore.p12 -out my.keystore.pem

Finally, to pretty-print the certificate, we use the following openssl command:

openssl x509 -in my.keystore.pem -text -noout

This converts the PEM format to text format, and writes the output to the terminal. The output is:

        Version: 3 (0x2)
        Serial Number: 1442779707 (0x55ff123b)
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=country, ST=st, L=loc, O=org, OU=org unit, CN=localhost
            Not Before: Apr  8 07:39:35 2015 GMT
            Not After : Apr  7 07:39:35 2016 GMT
        Subject: C=country, ST=st, L=loc, O=org, OU=org unit, CN=localhost
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (2048 bit)
                Modulus (2048 bit):
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:localhost, IP Address:
            X509v3 Subject Key Identifier:
    Signature Algorithm: sha256WithRSAEncryption