Experience League

Experience Cloud

Document Cloud

Using SSL with Dispatcher

Use SSL connections between Dispatcher and the render computer:

One-way SSL
Mutual SSL

NOTE

Operations related to the SSL certificates are bound to third party products. They are not covered by the Adobe Platinum Maintenance and Support contract.

Use SSL When Dispatcher Connects to AEM

Configure Dispatcher to communicate with the AEM or CQ render instance using SSL connections.

Before you configure Dispatcher, configure AEM or CQ to use SSL:

AEM 6.2: Enabling HTTP Over SSL
AEM 6.1: Enabling HTTP Over SSL
Older AEM versions: see this page.

When Dispatcher recieves an HTTPS request, Dispatcher includes the following headers in the subsequent request that it sends to AEM or CQ:

X-Forwarded-SSL
X-Forwarded-SSL-Cipher
X-Forwarded-SSL-Keysize
X-Forwarded-SSL-Session-ID

A request through Apache-2.4 with mod_ssl includes headers that are similar to the following example:

X-Forwarded-SSL: on
X-Forwarded-SSL-Cipher: DHE-RSA-AES256-SHA
X-Forwarded-SSL-Session-ID: 814825E8CD055B4C166C2EF6D75E1D0FE786FFB29DEB6DE1E239D5C771CB5B4D

Configuring Dispatcher to Use SSL

To configure Dispatcher to connect with AEM or CQ over SSL, your dispatcher.any file requires the following properties:

A virtual host that handles HTTPS requests.
The renders section of the virtual host includes an item that identifies the host name and port of the CQ or AEM instance that uses HTTPS.
The renders item includes a property named secure of value 1.

Note: Create another virtual host for handling HTTP requests if required.

The following example dispatcher.any file shows the property values for connecting using HTTPS to a CQ instance that is running on host localhost and port 8443:

/farms
{
   /secure
   { 
      /virtualhosts
      {
         # select this farm for all incoming HTTPS requestss
         "https://*"
      }
      /renders
      {
      /0001
         {
            # hostname or IP of the render
            /hostname "localhost"
            # port of the render
            /port "8443"
            # connect via HTTPS
            /secure "1"
         }
      }
     # the rest of the properties are omitted
   }

   /non-secure
   { 
      /virtualhosts
      {
         # select this farm for all incoming HTTP requests
         "https://*"
      }
      /renders
      {
         /0001
      {
         # hostname or IP of the render
         /hostname "localhost"
         # port of the render
         /port "4503"
      }
   }
    # the rest of the properties are omitted
}

Configuring Mutual SSL Between Dispatcher and AEM

Configure the connections between Dispatcher and the render computer (typically an AEM or CQ publish instance) to use Mutual SSL:

Dispatcher connects to the render instance over SSL.
The render instance verifies the validity of Dispatcher’s certificate.
Dispatcher verifies that the CA of the render instance’s certificate is trusted.
(Optional) Dispatcher verifies that the certificate of the render instance matches the render instance’s server address.

To configure mutual SSL, you require certificates that are signed by a trusted certificate authority (CA). Self-signed certificates are not adequate. You can either act as the CA or use the services of a third-party CA to sign your certificates. To configure mutual SSL, you require the following items:

Signed certificates for the render instance and Dispatcher
The CA certificate (if you are acting as the CA)
OpenSSL libraries for generating the CA, certificates, and certificate requests.

Perform the following steps to configure mutual SSL:

Install the latest version of Dispatcher for your platform. Use a Dispatcher binary that supports SSL (SSL is in the file name, such as dispatcher-apache2.4-linux-x86-64-ssl10-4.1.7.tar).
Create or obtain CA-signed certificate for Dispatcher and the render instance.
Create a keystore containing render certificate and configure the render’s HTTP service to use it.
Configure the Dispatcher web server module for mutual SSL.

Creating or Obtaining CA-Signed Certificates

Create or obtain the CA-signed certificates that authenticate the publish instance and Dispatcher.

Creating Your CA

If you are acting as the CA, use OpenSSL to create the Certificate Authority that signs the server and client certificates. (You must have the OpenSSL libraries installed.) If you are using a third-party CA, do not perform this procedure.

Open a terminal and change the current directory to the directory that contiains the CA.sh file, such as /usr/local/ssl/misc.
To create the CA, enter the following command and then provide values when promtped:
```
./CA.sh -newca
```
NOTE

Several properties in the openssl.cnf file control the behavior of the CA.sh script. You should modify this file as required before you create your CA.

Creating the Certificates

Use OpenSSL to create the certificate requests to send to the third-party CA or to sign with your CA.

When you create a certificate, OpenSSL uses the Common Name property to identify the certificate holder. For the certificate of the render instance, use the instance computer’s host name as the Common Name if you are configuring Dispatcher to accept the certificate only if it matches the hostname of the Publish instance. (See the DispatcherCheckPeerCN property.)

Open a terminal and change the current directory to the directory that contains the CH.sh file of your OpenSSL libraries.
Enter the following command and provide values when prompted. If required, use the host name of the publish instance as the Common Name. The host name is DNS-resolvable name for the IP address of the render:
```
./CA.sh -newreq
```
If you are using a third-party CA, send the newreq.pem file to the CA to sign. If you are acting as the CA, continue to step 3.
Enter the following command to sign the certificate using the certificate of your CA:
```
./CA.sh -sign
```
Two files named newcert.pem and newkey.pem are created in the directory that contains your CA management files. These are the public certificate and private key for the render computer, respectively.
Rename newcert.pem to rendercert.pem, and rename newkey.pem to renderkey.pem.
Repeat steps 2 and 3 to create a new certificate and a new public key for the Dispatcher module. Ensure that you use a Common Name that is specific to the Dispatcher instance.
Rename newcert.pem to dispcert.pem, and rename newkey.pem to dispkey.pem.

Configuring SSL on the Render Computer

Configure SSL on the render instance using the rendercert.pem and renderkey.pem files.

Converting the Render Certificate to JKS Format

Use the following commmand to convert the render certificate, which is a PEM file, to a PKCS#12 file. Also include the certificate of the CA that signed the render certificate:

In a terminal window, change the current directory to the location of the render certificate and private key.
Enter the following commmand to convert the render certificate, which is a PEM file, to a PKCS#12 file. Also include the certificate of the CA that signed the render certificate:
```
openssl pkcs12 -export -in rendercert.pem -inkey renderkey.pem  -certfile demoCA/cacert.pem -out rendercert.p12
```

Enter the following command to convert PKCS#12 file to Java KeyStore (JKS) format:

keytool -importkeystore -srckeystore servercert.p12 -srcstoretype pkcs12 -destkeystore render.keystore

The Java Keystore is created using a default alias. Change the alias if desired:
```
keytool -changealias -alias 1 -destalias jettyhttp -keystore render.keystore
```

Adding the CA Cert to the Render’s Truststore

If you are acting as the CA, import your CA certificate into a keystore. Then, configure the JVM that runs the render instance to trust the keystore.

Use a text editor to open the cacert.pem file and remove all the text that precedes the followign line:

-----BEGIN CERTIFICATE-----

Use the following command to import the certificate into a keystore:

keytool -import -keystore cacerts.keystore -alias myca -storepass password -file cacert.pem

To configure the JVM that runs your render instance to trust the keystore, use the following system property:
```
-Djavax.net.ssl.trustStore=<location of cacerts.keystore>
```
For example, if you use the crx-quickstart/bin/quickstart script to start your publish instance you can modify the CQ_JVM_OPTS property:
```
CQ_JVM_OPTS='-server -Xmx2048m -XX:MaxPermSize=512M -Djavax.net.ssl.trustStore=/usr/lib/cq6.0/publish/ssl/cacerts.keystore'
```

Configuring the Render Instance

Use the render certificate with the instructions in the Enable SSL on the Publish Instance section to configure the HTTP service of the render instance to use SSL:

AEM 6.2: Enabling HTTP Over SSL
AEM 6.1: Enabling HTTP Over SSL
Older AEM versions: see this page.

Configuring SSL for the Dispatcher Module

To configure Dispatcher to use mutual SSL, prepare the Dispatcher certificate and then configure the web server module.

Creating a Unified Dispatcher Certificate

Combine the dispatcher certificate and the unencrypted private key into a single PEM file. Use a text editor or the cat command to create a file that is similar to the following example:

Open a terminal and change the current directory to the location of the dispkey.pem file.

To decrypt the private key, enter the following command:

openssl rsa -in dispkey.pem -out dispkey_unencrypted.pem

Use a text editor or the cat command to combine the unencrypted private key and the certificate in a single file that is similar to the following example:

-----BEGIN RSA PRIVATE KEY-----
MIICxjBABgkqhkiG9w0B...
...M2HWhDn5ywJsX
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIC3TCCAk...
...roZAs=
-----END CERTIFICATE-----

Specifying the Certificate to Use for Dispatcher

Add the following properties to the Dispatcher module configuration (in httpd.conf):

DispatcherCertificateFile: The path to the Dispatcher unified certificate file, containing the public certificate and the unencrypted private key. This file is used when SSL server requests the Dispatcher client certificate.
DispatcherCACertificateFile: The path to the CA certificate file, used if the SSL server presents a CA that is not trusted by a root authority.
DispatcherCheckPeerCN: Whether to enable ( On) or disable ( Off) host name checking for remote server certificates.

The following code is an example configuration:


<IfModule disp_apache2.c>
  DispatcherConfig conf/dispatcher.any
  DispatcherLog    logs/dispatcher.log
  DispatcherLogLevel 3
  DispatcherNoServerHeader 0
  DispatcherDeclineRoot 0
  DispatcherUseProcessedURL 0
  DispatcherPassError 0
  DispatcherCertificateFile disp_unified.pem
  DispatcherCACertificateFile cacert.pem
  DispatcherCheckPeerCN On
</IfModule>

Resources on adobe.com

Ecommerce Integrations Automated Onboarding Personalized Experiences Customer Communications Content Intelligence Personalized Communications

View next:

Privacy (UPDATED)