Legacy Product

Fusion 5.10
    Fusion 5.10

    SSL Security (Windows)

    Fusion’s UI (which is accessed through the Fusion Proxy service) can run over SSL for secure communication with any HTTP client, using the Java Secure Socket Extension (JSSE) framework. You configure Fusion for SSL by configuring Fusion’s Proxy and UI services.

    Fusion 4.0.2 or later is required to enable SSL security. Version 4.0.2 fixed a bug in the authentication proxy that incorrectly redirected some requests when SSL is enabled.

    Required software

    Configuring Fusion for SSL requires the following software:

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

      The JDK is also a requirement for Fusion Server.

    • OpenSSL. You might need the openssl command line tool:

      • If you have the certificate chain and private key as separate files, then you can use the openssl command line tool to create a PKCS #12 file.

      • If you have an intermediate CA certificate, then you can use it and openssl to generate the certificate chain and private key files.

    Overview of procedure

    How to configure Fusion for SSL:

    1. Load an SSL certificate into a Fusion keystore.

    2. Enable SSL in the Fusion Proxy service.

    3. Restart Fusion and test access through HTTPS.

    4. Disable HTTP access to the Fusion Proxy service.

    5. Ensure that the Fusion Agent can do heartbeats against the Proxy service.

      The heartbeat service is deprecated in Fusion 4.2+.

    1. Load an SSL certificate into a Fusion keystore

    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.

    Load the certificate into a Fusion keystore. Perform the tasks in the appropriate section:

    • Self-signed certificate. If Fusion is behind a firewall, you can use a self-signed certificate for SSL communication with other hosts in your internal network. Create a keystore for the Fusion Proxy service and load the keystore with the self-signed PKCS #12 certificate.

    • Certificate signed by a certificate authority. In a production environment, SSL certificates typically originate with certificate signing requests (CSRs) and are signed by a trusted third-party Certificate Authority (CA). Create a keystore for the Fusion Proxy service and load the keystore with the PKCS #12 certificate from a CA.

    Alternative 1: Self-signed certificate

    If you are using a CSR-originated certificate from a trusted certificate authority, proceed to Alternative 2: CA-signed certificate.

    If Fusion is behind a firewall, you can use a self-signed certificate for SSL communication with other hosts in your internal network. Create a keystore for the Fusion Proxy service and load the keystore with the self-signed PKCS #12 certificate.

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

    How to create a keystore and load a self-signed certificate

    1. Set environment variables:

      set JAVA_HOME=JavaHomeDirectory
set FUSION_HOME=FusionHomeDirectory

      For example, in Fusion 4.1:

      set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_171
set FUSION_HOME=C:\lucidworks\fusion\4.1.2

      In Fusion 4.0:

      set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_171
set FUSION_HOME=C:\lucidworks\fusion\4.0.2

    2. Create the Fusion Proxy service keystore, generate the key pair and self-signed certificate, and load them into the keystore:

      "%JAVA_HOME%\bin\keytool.exe" -genkeypair -keystore "%FUSION_HOME%\apps\jetty\proxy\etc\keystore" -dname "CN=CommonName, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown" -keypass KeyPassword -storepass KeystorePassword -keyalg RSA -alias selfsigned -deststoretype pkcs12 -ext SAN=dns:ServerFqdn,ip:ServerIpAddress
      You must include the qualified domain name and/or the IP address of the Fusion server in the -ext SAN part of the command. Failure to do so results in SSL validation errors.

      Example command:

      "%JAVA_HOME%\bin\keytool.exe" -genkeypair -keystore "%FUSION_HOME%\apps\jetty\proxy\etc\keystore" -dname "CN=CommonName, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown" -keypass 59Winter.Is.Long45 -storepass 46I.Prefer.Vanilla24 -keyalg RSA -alias selfsigned -deststoretype pkcs12 -ext SAN=dns:search.mycorp,ip:192.168.1.40,dns:localhost

      The resulting certificate enables validated SSL transport to these hosts:

    https://search.mycorp:ProxyPort
https://192.168.1.40:ProxyPort
https://localhost:ProxyPort

    Where ProxyPort is the Fusion Proxy port.

    Alternative 2: CA-signed certificate

    If Fusion is behind a firewall and you are using a self-signed certificate, skip this section. Perform the tasks in Alternative 1: Self-signed certificate.

    In a production environment, SSL certificates typically originate with certificate signing requests (CSRs) and are signed by a trusted third-party Certificate Authority (CA).

    The steps here assume that you are the person who will be obtaining the SSL certificate chain and private key files. If you are not that person, contact your system administrator.

    Preliminary steps

    1. Obtain a domain from a domain registrar.

    2. Change the A record of your domain to the public IP address of your web server instance.

    Generate SSL certificate files

    Use an SSL certificate provider to generate the certificate chain and private key files, or a PKCS #12 certificate, from a trusted CA:

    • Certificate chain and private key files. In this case, you will need to convert these files into a single certificate file in PKCS #12 format.

    • A PKCS #12 certificate that contains both the certificate chain and private key. In this case, no conversion is necessary.

    How to obtain certificate files

    1. In most cases, you will need to temporarily open ports 80 and 443 in your firewall configuration. The SSL certificate provider must be able to make successful HTTP and HTTPS requests to your server through the Domain Name System (DNS).

    2. Use an SSL certificate provider to generate the certificate chain (fullchain.pem) and private key (privkey.pem) files, or the PKCS #12 certificate, from a trusted CA. Steps will vary based on the certificate provider. Contact your certificate provider for details.

    3. Close ports 80 and 443 in your firewall configuration.

    4. Change the A record of your domain to the public domain-name address of your web server instance.

    Proceed to the next sections as follows:

    Convert the certificate chain and private key files to a PKCS #12 certificate

    If you have a PKCS #12 certificate, skip this section and proceed to the section Import the PKCS #12 certificate into the Fusion Proxy service keystore.
    How to create a PKCS #12 certificate

    With the certificate chain and private key as separate files, use the openssl command line tool in OpenSSL to create a PKCS #12 certificate.

    openssl pkcs12 -export -out \path\to\keystore.p12 -in \path\to\fullchain.pem -inkey \path\to\privkey.pem
    Do not enter a blank password.

    Create the Fusion Proxy service keystore and import the PKCS #12 certificate

    Use the Java keytool Key and Certificate Management utility to create a keystore for the Fusion Proxy service (%FUSION_HOME%\apps\jetty\proxy\etc\keystore) and import the PKCS #12 certificate file. Fusion uses this certificate to perform SSL.

    If you are starting with a certificate file in PFX format (file extension .pfx), that format is now identical to PKCS #12 format.

    1. To create the keystore and import the PKCS #12 certificate:

      "%JAVA_HOME%\bin\keytool.exe" -genkeypair -alias mykeystore -keyalg RSA -keysize 2048 -keystore keystore.jks

"%JAVA_HOME%\bin\keytool.exe" -importkeystore -srckeystore mycertificate.p12 -srcstoretype PKCS12 -destkeystore keystore.jks

    2. Use the keytool import command to create a JSSE keystore.

      keytool -importkeystore -srckeystore \path\to\keystore.p12 -srcstoretype PKCS12 -destkeystore "%FUSION_HOME%\apps\jetty\proxy\etc\keystore" -deststoretype PKCS12

    3. (Optional) If desired, delete the PKCS #12 certificate file that resides outside of the Fusion Proxy service keystore (the one you created from the certificate chain and private key files, or obtained from a trusted CA.

      del \path\to\keystore.p12

    2. Enable HTTPS in the Fusion Proxy service

    Before beginning these steps, load an SSL certificate into a Fusion keystore.

    How to enable HTTPS in the Fusion Proxy service:

    1. (Only for Fusion Server 4.0.x and 4.1.0) Prevent the start.jar program from downloading a default keystore file, which is not needed. Edit %FUSION_HOME%\apps\jetty\home\modules\ssl.mod. Comment out the indicated line. Change:

      [files]
https://raw.githubusercontent.com/eclipse/jetty.project/master/jetty-server/src/test/config/etc/keystore?id=${jetty.tag.version}|etc/keystore

      To:

      [files]
#https://raw.githubusercontent.com/eclipse/jetty.project/master/jetty-server/src/test/config/etc/keystore?id=${jetty.tag.version}|etc/keystore

    2. Set environment variables:

      set JAVA_HOME=JavaHomeDirectory
set FUSION_HOME=FusionHomeDirectory

      For example, in Fusion 4.1:

      set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_171
set FUSION_HOME=C:\lucidworks\fusion\4.1.2

      In Fusion 4.0:

      set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_171
set FUSION_HOME=C:\lucidworks\fusion\4.0.2

    3. Add HTTPS protocol support to the Jetty TLS (SSL) connector:

      cd "%FUSION_HOME%\apps\jetty\proxy\"
java -jar "%FUSION_HOME%\apps\jetty\home\start.jar" --add-to-start=https

      Example output:

      INFO: ssl             initialized (transitively) in ${jetty.base}/start.ini
INFO: https           initialized in ${jetty.base}/start.ini
INFO: Base directory was modified

    4. Get the obfuscated version of your keystore password: The Jetty utility is in various places: 4.0.x: %FUSION_HOME%\apps\libs\jetty-util-9.3.8.v20160314.jar or: %FUSION_HOME%\apps\jetty\home\lib\jetty-util-9.3.8.v20160314.jar (Switch to the latter for consistency.) 4.1.0: %FUSION_HOME%\apps\jetty\home\lib\jetty-util-9.3.8.v20160314.jar 4.1.1 and later: %FUSION_HOME%\apps\jetty\home\lib\jetty-util-9.4.12.v20180830.jar

      java -cp "$FUSION_HOME/apps/jetty/home/lib/*" org.eclipse.jetty.util.security.Password PASSWORD

      Replace PASSWORD with the password you used for the keystore. If the password contains special characters, URL encode them.

      Example output:

      2018-05-15 12:32:48.988:INFO::main: Logging initialized @133ms
password345XYZ
OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0
MD5:b91cd1a54781790beaa2baf741fa6789

    5. Edit the file %FUSION_HOME%\apps\jetty\proxy\start.ini:

      1. Include obfuscated passwords by adding these properties to the end of the file:

        • jetty.sslContext.keyStorePassword

        • jetty.sslContext.keyManagerPassword

        • jetty.sslContext.trustStorePassword

      2. Use the OBF-encrypted password from step 4 (including the OBF: string) as the value for all three of the properties.

        For example:

        ## Keystore password
jetty.sslContext.keyStorePassword=OBF:2uha1vgt1jg01a4b1a4j1jda1vg11ugg

...

## KeyManager password
jetty.sslContext.keyManagerPassword=OBF:2uha1vgt1jg01a4b1a4j1jda1vg11ugg

## Truststore password
jetty.sslContext.trustStorePassword=OBF:2uha1vgt1jg01a4b1a4j1jda1vg11ugg

      3. Set the local SSL port by adding the jetty.ssl.port property to the end of the file, and providing the port number. For example:

        ## Connector port to listen on
jetty.ssl.port=8443

      4. Save the file %FUSION_HOME%\apps\jetty\proxy\start.ini.

    3. Restart Fusion and test access through HTTPS

    1. Restart all Fusion services:

      bin\fusion.cmd restart

      HTTPS should now be enabled in the Fusion Proxy service.

    2. Sign in to the Fusion UI. Specify the HTTPS URL scheme and SSL port, for example, https://search.mycorp:8443.

    4. Disable HTTP access to the Fusion Proxy service

    Disable HTTP access. You have a choice. Perform the tasks in the appropriate section:

    Alternative 1: Disable HTTP access on the firewall or load balancer

    Disable HTTP access to the Fusion Proxy service on the firewall or load balancer:

    1. Disallow all requests for port 8764 from the outside world. Only localhost should be able to communicate with Fusion on the non-SSL port 8764. Block all other requestors.

    2. If you are using a firewall or load balancer in front of Fusion, use it to redirect all HTTP requests to use HTTPS instead. For example, Apache would redirect all incoming HTTP traffic to HTTPS.

    Alternative 2: Disable listening for HTTP requests in the Fusion Proxy service

    Ideally, you should disable HTTP access using the firewall or load balancer. Follow the steps in this section only if disabling HTTP access on the firewall or load balancer is not feasible.

    You can only use this alternative if your SSL certificate covers a hostname that can be accessed from the local host. For example, if your certificate only covers https://fusion.com, then your local machine must be able to access Fusion from that exact host. If necessary, change the hosts file so that this can work.

    How to disable HTTP

    1. Edit \lucidworks\fusion\latest.x\apps\jetty\proxy\start.d\http.ini.

      1. Change this line:

        --module=http

        To:

        #--module=http

      2. Save the file.

    2. Edit the Fusion configuration file, \lucidworks\fusion\latest.x\conf\fusion.cors (fusion.properties in Fusion 4.x).

      1. Ensure that the Agent JVM uses the Fusion Proxy service’s keystore by adding this to the end of the file:

        agent.jvmOptions=-Djavax.net.ssl.trustStore="%{FUSION_HOME}%\\apps\\jetty\\proxy\\etc\\keystore" -Djavax.net.ssl.trustStorePassword=PASSWORD -Djavax.net.ssl.keyStore="%{FUSION_HOME}%\\apps\\jetty\\proxy\\etc\\keystore" -Djavax.net.ssl.keyStorePassword=PASSWORD

        Replace PASSWORD with your Fusion keystore password.

      2. Uncomment the default.address and change it to the hostname of the server that is validated by your SSL certificate.

        If the hostname saved in default.address is not validated by your SSL certificate, then the Fusion Proxy service will not start, because the agent’s liveness detector will not be able to access the HTTPS port to determine whether Fusion is running.

        If you self-signed the certificate, then the default.address must match the hostname you specified while signing the certificate. Failure to do this will result in the Fusion Proxy service not starting after you have disabled HTTP.

        For example, if your SSL certificate’s validated hostname is search.mycorp, then change:

        #default.address = 127.0.0.1

        To:

        default.address = search.mycorp

      3. Change the proxy.port to the SSL port you chose. For example, change:

        proxy.port = 8764

        To:

        proxy.port = 8443

      4. Uncomment proxy.ssl and change its value to true. Change:

        # proxy.ssl=false

        To:

        proxy.ssl=true

    Stop and start Fusion for these changes to take effect.

    5. Ensure that the Fusion Agent can do heartbeats against the Proxy service

    This section does not apply to Fusion 4.2+.

    By default, the Fusion Agent makes HTTP requests to the Fusion Proxy service to ask whether the Proxy service is running (heartbeat checks). So, when you disable HTTP access to the Proxy service, the Fusion Agent needs an alternative way to do the heartbeat checks.

    1. Add an entry to the /etc/hosts file for the Fusion node so that the DNS routes the qualified domain name to the correct IP address, for example:

      192.168.1.6   search.mycorp

      Or use a local IP address:

      127.0.0.1   search.mycorp

    2. Add proxy.address and specify the hostname of the server on which the Proxy service runs, for example:

      proxy.address=search.mycorp

    3. Stop and start all Fusion services (do not just perform a restart):

      cd "%FUSION_HOME%\bin"
fusion.cmd stop
fusion.cmd start

      HTTPS should now be disabled in the Fusion Proxy service.

    4. Verify that you cannot sign in to the Fusion UI using the HTTP URL scheme and non-SSL port, for example, http://search.mycorp:8764.

    References and tutorials