This section describes a recommended approach for generating secure keys and setting up certificates. It is not required that you use this approach if you have an alternative solution that you already use.

If you’re installing Alfresco Content Services using the distribution zip, you need to generate certificates for the repository and Solr. By default, the distribution zips are configured to use SSL, so you’ll need to generate these certificates to get your system to run successfully.

You can create the keystores, truststores and certificates required to configure SSL/mutual TLS authentication between different services in Alfresco Content Services, such as the repository and Solr.

Generate secure keys for SSL communication

Use this information to generate certificates for SSL/mutual TLS authentication between the repository and Search Services, using secure keys specific to your installation.

A certificates generator script, run.sh (for Linux) and run.cmd (for Windows) is provided in a GitHub project. The script consists of two parts - the first part is based on OpenSSL (to generate the certificates), and the second part is based on the Java keytool (to build the keystores and truststores). Here, we’ll focus on running the script for a standalone Linux or Windows operating system.

Before you start, you must already have OpenSSL and keytool available in your system path.

1. Browse to the https://github.com/Alfresco/alfresco-ssl-generator GitHub project and click Clone or Download.

   If you downloaded the project, extract the files to a suitable location.

2. Change directory to the following location and run the script:

   (For Linux)

   Code copied to clipboard.
    cd /ssl-tool
    ./run.sh
   

   (For Windows)

   Code copied to clipboard.
    cd ssl-tool-win
    run.cmd
   

   By default, this creates a keystores folder in your current working directory.

   Note: If the keystores folder isn’t empty, the script exits without producing any keystore or truststore. You can safely, remove the keystores folder if you need to re-run the script.

See Keystore directory structure for more and Customize certificate generation for a full list of parameters that allow you to customize your certificates. It is recommended that you set your own passwords when generating certificates.

Customize certificate generation

Here is a full list of parameters that allow you to customize your certificates. These parameters will override the default values listed in the run.sh and run.cmd scripts.

Note: If you plan to use custom DNames in your certificates, you must use double quotes around the values. For example:

Code copied to clipboard.
$ ./run.sh -cacertdname  
"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Windows Alfresco CA"
-repocertdname "/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Repo"
-solrcertdname "/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Solr"

It is recommended that you set your own passwords when generating certificates. For example:

(For Linux)

Code copied to clipboard.
./run.sh -keystorepass "password" -truststorepass "password"

(For Windows)

Code copied to clipboard.
run.cmd -keystorepass "password" -truststorepass "password"

Keystore directory structure

The keystores directory contains the following structure and files:

Code copied to clipboard.
keystores
├── alfresco
│   ├── keystore
│   ├── ssl.keystore
│   ├── ssl.truststore
├── client
│   └── browser.p12
└── solr
│   ├── ssl-repo-client.keystore
│   └── ssl-repo-client.truststore

Set up certificates

Use this information to set up your generated certificates in their correct locations.

Before continuing, make sure that you’ve already completed the steps in Generating secure keys for SSL communication.

1. Copy the files under /keystores/alfresco to the Alfresco Content Services install location:

   Code copied to clipboard.
    ${ALF_DATA_DIR}/keystore
   

2. Copy the files under /keystores/solr to the Alfresco Search Services install location:

   Code copied to clipboard.
    <SOLR_HOME>/keystore
   

3. You can use the file under keystores/client from a browser to access the server using HTTPS on port 8443.

4. Override the SSL properties as shown.

   1. In <TOMCAT_HOME>/shared/classes/alfresco-global.properties update the following:

      Code copied to clipboard.
       dir.keystore=${ALF_DATA_DIR}/keystore
       # encryption
       solr.secureComms=https
       # ssl encryption
       encryption.ssl.keystore.location=${dir.keystore}/ssl.keystore
       encryption.ssl.keystore.type=JCEKS
       encryption.ssl.keystore.keyMetaData.location=
       encryption.ssl.truststore.location=${dir.keystore}/ssl.truststore
       encryption.ssl.truststore.type=JCEKS
       encryption.ssl.truststore.keyMetaData.location=
       # secret key keystore configuration
       encryption.keystore.location=${dir.keystore}/keystore
       encryption.keystore.keyMetaData.location=
       encryption.keystore.type=JCEKS
       solr.host=localhost
       solr.port=8983
       solr.port.ssl=8983
      

      Note: If you’re using a different keystore or truststore type other than the default, JCEKS, you must change the value in the properties file.

   2. For the Tomcat SSL Connector in <TOMCAT_HOME>/conf/server.xml update the following:

      • If using Alfresco Content Services 6.x on Tomcat 8:

      Code copied to clipboard.
       <Connector port="8443" protocol="HTTP/1.1"
           SSLEnabled="true" maxThreads="150" scheme="https"
           keystoreFile="/usr/local/tomcat/alf_data/keystore/ssl.keystore"
           keystorePass="password" keystoreType="JCEKS"
           secure="true" connectionTimeout="240000"
           truststoreFile="/usr/local/tomcat/alf_data/keystore/ssl.truststore"
           truststorePass="password" truststoreType="JCEKS"
           clientAuth="want" sslProtocol="TLS" />
      

      • If using Alfresco Content Services 7.x on Tomcat 9 or 23.x on Tomcat 10:

      Code copied to clipboard.
       <Connector port="8443"
          protocol="org.apache.coyote.http11.Http11NioProtocol"
          connectionTimeout="20000"
          maxThreads="150"
          SSLEnabled="true"
          scheme="https"
          secure="true"
          defaultSSLHostConfigName="localhost">
           <SSLHostConfig hostName="localhost"
                  protocols="TLSv1.2"
                  certificateVerification="required"
                  truststoreFile="/usr/local/tomcat/alf_data/keystore/ssl.truststore"
                  truststorePassword="truststore"
                  truststoreType="JCEKS">
           <Certificate certificateKeystoreFile="/usr/local/tomcat/alf_data/keystore/ssl.keystore"
                    certificateKeyAlias="ssl.repo"
                    type="RSA"
                    certificateKeystorePassword="keystore"
                    certificateKeystoreType="JCEKS"/>
           </SSLHostConfig>
       </Connector>
      

      Note: If you’re using a different keystore or truststore type other than the default, JCEKS, you must change the value in the properties file. Also, make sure that the keystore and truststore file locations are correct for your environment.

   See Installing the Tomcat application server and Solr configuration files for more.

5. Change the SSL properties in <SOLR_HOME>/solrhome/templates/rerank/conf/solrcore.properties.

   The rerank template is used to generate the alfresco and archive Solr cores when you first run Alfresco Search Services.

   Code copied to clipboard.
    # encryption
    alfresco.secureComms=https
    # ssl
    alfresco.encryption.ssl.keystore.type=JCEKS
    alfresco.encryption.ssl.keystore.location=<SOLR_HOME>/ssl-repo-client.keystore
    alfresco.encryption.ssl.keystore.passwordFileLocation=
    alfresco.encryption.ssl.truststore.type=JCEKS
    alfresco.encryption.ssl.truststore.location=<SOLR_HOME>/ssl-repo-client.truststore
    alfresco.encryption.ssl.truststore.passwordFileLocation=alfresco.host=localhost
    alfresco.port.ssl=8443
   

   Note: If you’re using a different keystore or truststore type other than the default, JCEKS, you must change the value in the properties file.

   If the alfresco and archive cores already exist, ensure that alfresco.secureComms is set to https for both the cores in the following files:

   Code copied to clipboard.
    <SOLR_HOME>/solrhome/alfresco/conf/solrcore.properties
    <SOLR_HOME>/solrhome/archive/conf/solrcore.properties
   

   See Solr core configuration properties for more.