Search
Clear search
Close search
Google apps
Main menu

Configuring the Connectors to use HTTPS

Google Search Appliance software versions 7.0, 7.2 and 7.4
Connector software version 3.0
Connector Manager version 3.0
Installer version 3.0



Introducing HTTPS with the Connectors

The Connector Manager supports using HTTPS requests from the Google Search Appliance for both onboard and offboard connectors. For offboard connectors, you must set up Apache Tomcat to use this feature. For onboard connectors these steps are unnecessary.

This step is highlighted with the 3.0 release of the connectors, because document contents are sent to the Google Search Appliance differently than connectors in the past. For the File System Connector 3.0, the Google Search Appliance issues standard HTTP/HTTPS requests to the Connector Manager to access document contents, and uses a client-certificate for authentication. Thus, for those contents to be encrypted as sent across the network:

  1. Your Tomcat instance must provide HTTPS.

  2. The GSA’s certificate must be valid.

  3. The GSA should trust Tomcat’s certificate if Server Certificate Authentication is enabled in the GSA’s SSL Configuration.

  4. Tomcat should trust the GSA’s certificate and ‘want’ the client certificate.

  5. You must register the Connector Manager instance via HTTPS.

Steps 1–3 are generic to most HTTPS configurations. Step 4 is generic to HTTPS configurations when client certificates are used. Step 5 is a Connector Manager-specific configuration step.


Step 1: Enable HTTPS in Tomcat

Enabling HTTPS in Tomcat requires having a certificate with its corresponding private key loaded into a Java keystore. The certificate must be for the hostname of the Tomcat instance that will be used when connecting.

There are two possible types of certificates you can use:

  1. Certificate Authority-signed certificates.
  2. Self-signed certificates.

Each type of certificate will be covered here, but you may wish to see Tomcat’s SSL documentation for more information. In addition, this documentation only covers Tomcat as configured by default by the connector installer.


Step 1a: Using a Certificate Authority-Signed Certificate

If you wish to use a Certificate Authority-signed certificate you first obtain a signed certificate from the Certificate Authority of your choice. After communicating with the Certificate Authority you should eventually have:

  • a signed certificate,
  • a private key, and
  • the Certificate Authority’s chain.
  1. Use OpenSSL to create a new PKCS12 keystore (at /path/to/keys.p12) from the signed certificate cmcert.crt and the private key cmcert.key:

    openssl pkcs12 -export -in cmcert.crt -inkey cmcert.key \
            -out /path/to/keys.p12 -password pass:changeit -name cm
  2. Convert the new PKCS12 keystore to Java’s KeyStore (KJS) using the keytool command provided by Java. This command will create a new JKS keystore (at /path/to/keys.jks) for use with Tomcat:

    keytool -importkeystore -srckeystore /path/to/keys.p12 \
            -srcstoretype PKCS12 -srcstorepass changeit -alias cm \
            -destkeystore /path/to/keys.kjs \
            -deststorepass changeit -destkeypass changeit
  3. Add the Certificate Authority chain to the trust store. Copy the default trusted certificates located in your JRE’s lib/security/cacerts to a new file of your choosing /path/to/cacerts.jks. You can then import the certificate chain cachain.crt:

    keytool -importcert -trustcacerts -keystore /path/to/cacerts.jks \
            -storepass changeit -file cachain.crt -alias cachain
  4. Enable HTTPS as described in Step 1c.

Step 1b: Using a Self-Signed Certificate

If you wish to generate a self-signed certificate instead, use the keytool command provided by Java. This command will create a new keystore (at /path/to/keys.jks) and create a self-signed certificate and private key that is valid for 365 days:

keytool -genkeypair -keystore /path/to/keys.jks -keyalg RSA -validity 365 \
        -storepass changeit -keypass changeit -alias cm

  1. For What is your first and last name?, enter the hostname of the Tomcat instance.
  2. Answer the other questions however you wish.
  3. Answer yes to Is CN=cmhostname, OU=... correct?
  4. Enable HTTPS as described in Step 1c.
Tip: If you are also using a self-signed certificate for the Google Search Appliance, in preparation for a future step, copy the default trusted certificates located in your JRE’s lib/security/cacerts to a new file of your choosing at /path/to/cacerts.jks.

Step 1c: Configuring Tomcat for HTTPS

Now that the certificate and private keys are ready, Tomcat needs to be configured to use them.

Add the following <Connector> configuration within the <Service> section of Tomcat’s conf/server.xml:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
        maxThreads="150" scheme="https" secure="true"
        sslProtocol="TLS" keystoreFile="/path/to/keys.jks"
        keystorePass="changeit" truststoreFile="/path/to/cacerts.jks"
        truststorePass="changeit"/>


Step 2: Configure a Valid Certificate on the GSA

The certificate installed by default on the GSA is not valid for the hostname you use to access the GSA. To install a valid certificate for your GSA’s hostname, see admin_console_help/admin_SSL.html#External" target="_blank">Uploading an Externally Generated Private Key and Certificate or admin_console_help/admin_SSL.html#UIprocess" target="_blank">Requesting and Installing a Certificate Using the Admin Console.


Where to find the GSA’s Self-Signed Certificate

If you generated a self-signed certificate on the GSA, then you will need to download the certificate for later Tomcat configuration. To get the GSA’s certificate:

Using Chrome
  1. Navigate to the GSA’s secure search: https://gsahostname/. You should see a warning page that says, Your Connection is not private!. (This message appears because the certificate is self-signed and not signed by a trusted Certificate Authority.)
  2. Go to the Three Dots Menu -> More Tools -> Developer Tools. Or press F12 to enter Chrome "Developer Mode.
  3. Click on the Security Tab, and press on "View certificate" button.
  4. Change to the Details tab and click Export....
  5. Save the certificate using the save dialog.
  6. Click Close and Cancel to close the certificate dialog windows.
Using Firefox
  1. Navigate to the GSA’s secure search: https://gsahostname/. You should see a warning page that says, “This Connection is Untrusted.” (This message appears because the certificate is self-signed and not signed by a trusted Certificate Authority.)
  2. Click, I Understand the Risks and Add Exception.
  3. Wait until the View... button is clickable, then click it.
  4. Change to the Details tab and click Export....
  5. Save the certificate using the save dialog.
  6. Click Close and Cancel to close the certificate dialog windows.
Using OpenSSL in Linux
  1. Execute with a command line: openssl s_client -connect gsahostname:443 < /dev/null
  2. Copy the section that begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE----- (including the BEGIN and END CERTIFICATE portions) into a new file. That new file contains the certificate.

Step 3: Configure the GSA to Trust Tomcat’s Certificate

This step is optional if Server Certificate Authentication is disabled in the GSA’s SSL Configuration.

This step is generally unnecessary if Tomcat is using a certificate signed by a Certificate Authority.

Depending on the Certificate Authority used to sign the certificate, you may need to admin_console_help/admin_SSL.html#server_cert" target="_blank">add the Certificate Authority to the GSA.

If you used a self-signed certificate for Tomcat (one not issued by a Certificate Authority), then you need to configure the GSA to trust that certificate:

  1. Go to the Administration > Certificate Authorities page.
  2. Upload the public certificate for your Tomcat as a Certificate Authority.

Step 4: Configure Tomcat to Request and Trust the GSA’s Certificate

  1. Set clientAuth to want in Tomcat’s conf/server.xml for the <Connector> with HTTPS enabled:

    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
            maxThreads="150" scheme="https" secure="true"
            sslProtocol="TLS" keystoreFile="/path/to/keys.jks"
            keystorePass="changeit" truststoreFile="/path/to/cacerts.jks"
            truststorePass="changeit" clientAuth="want
  2. If the GSA is using a certificate signed by a Certificate Authority, then this step is generally complete.

Depending on the Certificate Authority used to sign the certificate, you may need to add the Certificate Authority’s root certificate to the trust store for Tomcat. Also, If the GSA is using a self-signed certificate, then you must add the GSA’s certificate to the trust store for Tomcat.

Import the Google Search Appliance’s certificate or your Google Search Appliance’s Certificate Authority’s root certificate gsa.crt into the already-existing /path/to/cacerts.jks created earlier with:

keytool -importcert -trustcacerts -keystore /path/to/cacerts.jks \
        -storepass changeit -file gsa.crt -alias gsa

Tomcat should already be configured to use /path/to/cacerts.jks due to previous steps.


Step 5: Register the Connector Manager Over HTTPS

After you restart Tomcat due to the conf/server.xml changes, you can now register your Connector Manager over HTTPS. For the Service URL, you should use the HTTPS protocol and port 8443 (as seen in the conf/server.xml config).

It should be in the form: https://cmhostname:8443/connector-manager

Was this article helpful?
How can we improve it?