Secure communication between the Dispatcher and CQ


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


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.

    The <ssl> element enables SSL/TLS and configures it
    The security protocol to be used. This is generally
    one of "SSL", "SSLv3", "TLS", and "TLSv1".
    Default: "SSL"

    Indicate the properties such as the location of
    the keystore containing the servers key.

    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

    The passphrase to access the keystore.
    Default: ""

    Specify the (short) name of the key pair to use
    to use for listening on this port.
    The short name of the key pair entry
    Default: "mykey"
    The password to access the key pair
    Default: ""
  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 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 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.

Dispatcher 4.1.3 onwards added SSL support & don't need Stunnel anymore. Use the distribution package that has a -ssl- in its name. Examples use the distribution package like [1].  

Additional general configuration steps are mentioned below. Refer dispatcher release notes for more details.

  • Enable HTTPS support in the AEM.
  • Make sure OpenSSL v0.9.8 & minor version are installed.
  • Configure secure port & Add secure config flag to /render section in dispatcher.any. Example

                      /hostname ""
                      /port "9443"
                      /secure "1"

  • Rewrite HTTP Location header if web server and backend protocol (http/https) do not match.



Applies to

CQSE 4.x, Granite


Get help faster and easier

New user?

Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online