How do I configure the dispatcher to connect to CQ using HTTPS instead of HTTP?

Solution

To enable HTTPS communication between the dispatcher and CQ, do the following:

1. Enable HTTPS support in the CQ servlet engine.
2. Connect Stunnel to the CQ'HTTPS port.
3. Configure dispatcher to connect to Stunnel instead of connecting directly to CQ.

Note: These instructions only apply to an Apache Web Server-based dispatcher setup in Linux.

These instructions assume that your dispatcher is set up on redhat linux, and that you are using Apache 2.2 web server.

Enable HTTPS in CQ5 (CQ5.1 - CQ5.4)

1. (On the cq5 instance server) Use java keytool to generate a self-signed certificate keystore. Then, run the keytool command below under the crx-quickstart/server/etc/ directory. When running the command, set the password in the -storepass parameter to a password of your choosing.
   keytool -genkey -keyalg RSA -alias self-signed -keystore keystore.jks -storepass password -validity 360 -keysize 2048
2. This command creates a file named keystore.jks. If you did not run the command from the  crx-quickstart/server/etc/ directory, then copy the keystore.jks file to that directory now.
   • If you have SSL certificates, then import them into your Java VM using keytool.
3. Add the following xml after the </listener> tag in your crx-quickstart/server/etc/server.xml file. Set the passwords in the configuration below to match the ones you set in step 1 above.
   <!--
   The port to listen for secure connections, 443 is
   the standard port for HTTPS.
   -->
   <bind-port>8889</bind-port>
   
   <!--
   The <ssl> element enables SSL/TLS and configures it
   -->
   <ssl>
   <!--
   The security protocol to be used. This is generally
   one of "SSL", "SSLv3", "TLS", and "TLSv1".
   Default: "SSL"
   -->
   <protocol>SSL</protocol>
   
   <!--
   Indicate the properties such as the location of
   the keystore containing the servers key.
   -->
   <key-store>
   
   <!--
   The authentication algorithm to be used. The
   default value is appropriate for Sun's JSSE
   implementation. Only specify anything
   supported by the JSSE provider used.
   Default: "SunX509"
   -->
   <!-- <algorithm>SunX509</algorithm> -->
   
   <!--
   The type of the keystore identified by the
   <name> element. Sun's JSSE/JCE implementations
   support "JKS", "JCEKS", and "PKCS12"
   Default: "JKS"
   -->
   <!-- <type>JKS</type> -->
   
   <!--
   The location of the keystore file. If the name
   is a relative path it is relative to the Servlet
   Engine's startup directory.
   Default: ".keystore" file in the user's home
   directory.
   -->
   <name>etc/keystore.jks</name>
   
   <!--
   The passphrase to access the keystore.
   Default: ""
   -->
   <passphrase>password</passphrase>
   </key-store>
   
   <!--
   Specify the (short) name of the key pair to use
   to use for listening on this port.
   -->
   <key>
   <!--
   The short name of the key pair entry
   Default: "mykey"
   -->
   <alias>self-signed</alias>
   <!--
   The password to access the key pair
   Default: ""
   -->
   <password>password</password>
   </key>
   </ssl>
   <max-threads>128</max-threads>
   </listener>
4. Restart CQ5
   
5. Test the configuration by going to https://hostname:8889/

Enable HTTPS in CQ5 (CQ5.5, CQ5.6)

See the official documentation here for instructions.

Enable Stunnel on the dispatcher server

1. (On the dispatcher server) Run the following commands to install Stunnel:
   sudo /sbin/chkconfig --add Stunnel
   
   If you are using a different operating system then use the package manager in the OS to download Stunnel or download it from the Stunnel site http://www.stunnel.org. Then, install it and configure it to run on OS startup.
   
2. Open /etc/stunnel/stunnel.conf for editing using this command
   sudo vi /etc/stunnel/stunnel.conf
3. In stunnel.conf set:
   client = yes
4. Add the following to stunnel.conf (replace with the port of the cq5 instance)
   accept = 8081
   connect = :8889
5. Start Stunnel
   

Configure CQ dispatcher to point to Stunnel port instead of the publish instance

1. Reconfigure the /renders section in the dispatcher.any file to point to 127.0.0.1 port 8081 instead of pointing to the destination CQ5 instance. See here for the documentation on that section of the dispatcher.any
2. Restart apache and verify that the dispatcher still works when going through Stunnel.
   

Applies to

CQSE 4.x, Granite