SEARCH-2213: Document the new approach to set up mTLS certificates.

Alfresco · Aug 5, 2020 · fa3468f · fa3468f
1 parent b1a4481
commit fa3468f
Showing 1 changed file with 101 additions and 9 deletions.
diff --git a/search-services/README.md b/search-services/README.md
@@ -36,8 +36,97 @@ $ unzip alfresco-search-services-*.zip
 $ cd alfresco-search-services
 ```
 
+**From Search Services 1.4.3**
+
+Alfresco *Search Services 1.4.3* distribution ZIP is released with Mutual Authentication TLS (SSL) by default. So before starting the service, generating secure keys for SSL communication is required. You can find detailed information for this step at [Alfresco documentation](https://docs.alfresco.com/search-enterprise/tasks/generate-keys-ssl.html).
+
+From this version, store and certificate passwords are provided using Java Environment Variables.
+
+Use the default options (or `alfrescoformat` as *current*) to generate the certificates with [Alfresco SSL Generator](https://github.com/Alfresco/alfresco-ssl-generator).
+
+The `keystores` folder generated by the SSL Tool contains the keystores and truststores for SSL configuration. In the following steps, it's assumed that SSL Tool has been executed from `/tmp` or `C:\tmp` folder.
+
+```bash
+$ tree /tmp/keystores/
+keystores
+├── alfresco
+│   ├── keystore
+│   ├── ssl.keystore
+│   └── ssl.truststore
+├── client
+│   └── browser.p12
+├── solr
+│   ├── ssl-repo-client.keystore
+│   └── ssl-repo-client.truststore
+└── zeppelin
+    ├── ssl-repo-client.keystore
+    └── ssl-repo-client.truststore
+```
+
+SOLR SSL configuration files are available in `/tmp/keystores/solr` folder.
+
+Modify following properties in `solrhome/templates/rerank/conf/solrcore.properties` file.
+
+```
+alfresco.encryption.ssl.keystore.location=/tmp/keystores/solr/ssl-repo-client.keystore
+alfresco.encryption.ssl.truststore.location=/tmp/keystores/solr/ssl-repo-client.truststore
+```
+
+If you are running from a *Linux* or *Mac OS X* machine, add following lines to `solr.in.sh` file.
+
+```
+SOLR_SSL_KEY_STORE=/tmp/keystores/solr/ssl-repo-client.keystore
+SOLR_SSL_KEY_STORE_PASSWORD=keystore
+SOLR_SSL_KEY_STORE_TYPE=JCEKS
+SOLR_SSL_TRUST_STORE=/tmp/keystores/solr/ssl-repo-client.truststore
+SOLR_SSL_TRUST_STORE_PASSWORD=truststore
+SOLR_SSL_TRUST_STORE_TYPE=JCEKS
+SOLR_SSL_NEED_CLIENT_AUTH=true
+SOLR_SSL_WANT_CLIENT_AUTH=false
+```
+
+If you are running from a *Windows* machine, add following lines to `solr.in.cmd` file.
+
+```
+set SOLR_SSL_KEY_STORE=C:/tmp/keystores/solr/ssl-repo-client.keystore
+set SOLR_SSL_KEY_STORE_PASSWORD=keystore
+set SOLR_SSL_KEY_STORE_TYPE=JCEKS
+set SOLR_SSL_TRUST_STORE=C:/tmp/keystores/solr/ssl-repo-client.truststore
+set SOLR_SSL_TRUST_STORE_PASSWORD=truststore
+set SOLR_SSL_TRUST_STORE_TYPE=JCEKS
+set SOLR_SSL_NEED_CLIENT_AUTH=true
+set SOLR_SSL_WANT_CLIENT_AUTH=false
+```
+
+Once this settings are ready, start SOLR service from command line:
+
+```
+./solr/bin/solr start -a "-Dcreate.alfresco.defaults=alfresco,archive \
+-Dsolr.ssl.checkPeerName=false \
+-Dsolr.allow.unsafe.resourceloading=true \
+-Dssl-keystore.password=keystore
+-Dssl-keystore.aliases=ssl-alfresco-ca,ssl-repo-client
+-Dssl-keystore.ssl-alfresco-ca.password=keystore
+-Dssl-keystore.ssl-repo-client.password=keystore
+-Dssl-truststore.password=truststore
+-Dssl-truststore.aliases=ssl-alfresco-ca,ssl-repo,ssl-repo-client
+-Dssl-truststore.ssl-alfresco-ca.password=truststore
+-Dssl-truststore.ssl-repo.password=truststore
+-Dssl-truststore.ssl-repo-client.password=truststore" -f
+```
+
+SOLR will create Alfresco cores (`alfresco` and `archive`) when starting, and configuration from `rerank` template will be copied to each core.
+
+**Search Services 1.3.0.5 to Search Services 1.4.3**
+
 From Alfresco *Search Services 1.3.0.5*, distribution ZIP is released with Mutual Authentication TLS (SSL) by default. So before starting the service, generating secure keys for SSL communication is required. You can find detailed information for this step at [Alfresco documentation](https://docs.alfresco.com/search-enterprise/tasks/generate-keys-ssl.html).
 
+Use the `alfrescoformat` *classic* option to generate the stores.
+
+```
+$ ./run.sh -keysize 2048 -alfrescoformat classic
+```
+
 The `keystores` folder generated by the SSL Tool contains the keystores and truststores for SSL configuration. In the following steps, it's assumed that SSL Tool has been executed from `/tmp` or `C:\tmp` folder.
 
 ```bash
@@ -87,14 +176,14 @@ SOLR_SSL_WANT_CLIENT_AUTH=false
 If you are running from a *Windows* machine, add following lines to `solr.in.cmd` file.
 
 ```
-set SOLR_SSL_KEY_STORE=C:\tmp\keystores\solr\ssl.repo.client.keystore
-SOLR_SSL_KEY_STORE_PASSWORD=keystore
-SOLR_SSL_KEY_STORE_TYPE=JCEKS
-SOLR_SSL_TRUST_STORE=C:\tmp\keystores\solr\ssl.repo.client.truststore
-SOLR_SSL_TRUST_STORE_PASSWORD=truststore
-SOLR_SSL_TRUST_STORE_TYPE=JCEKS
-SOLR_SSL_NEED_CLIENT_AUTH=true
-SOLR_SSL_WANT_CLIENT_AUTH=false
+set SOLR_SSL_KEY_STORE=C:/tmp/keystores/solr/ssl.repo.client.keystore
+set SOLR_SSL_KEY_STORE_PASSWORD=keystore
+set SOLR_SSL_KEY_STORE_TYPE=JCEKS
+set SOLR_SSL_TRUST_STORE=C:/tmp/keystores/solr/ssl.repo.client.truststore
+set SOLR_SSL_TRUST_STORE_PASSWORD=truststore
+set SOLR_SSL_TRUST_STORE_TYPE=JCEKS
+set SOLR_SSL_NEED_CLIENT_AUTH=true
+set SOLR_SSL_WANT_CLIENT_AUTH=false
 ```
 
 Once this settings are ready, start SOLR service from command line:
@@ -107,6 +196,9 @@ $ ./solr/bin/solr start -a "-Dcreate.alfresco.defaults=alfresco,archive \
 
 SOLR will create Alfresco cores (`alfresco` and `archive`) when starting, and configuration from `rerank` template will be copied to each core.
 
+
+**For any version (1.3+)**
+
 If you also started an ACS instance running in [https://localhost:8443/alfresco](https://localhost:8443/alfresco) with the keystores provided by the SSL Tool (`keystores/alfresco` folder), then the index will be populated.
 
 SOLR Web Console will be available at:
@@ -393,7 +485,7 @@ To use the public image instead of the local one (`searchservices:develop`) just
 ## Docker Master-Slave setup
 ### Enable Search Slave Replica config
 
-To enable slave node specify environment value `REPLICATION_TYPE=slave`, by default Master config is enabled and slave is disabled. 
+To enable slave node specify environment value `REPLICATION_TYPE=slave`, by default Master config is enabled and slave is disabled.
 
 During deployment time whenever Search Services or Insight Engine image starts, it will execute the script [search_config_setup.sh](/packaging/src/docker) which will configure the slave config setup based on the value specified in the script.