The release of the following versions includes Mutual TLS Authentication by Default for Alfresco Repository and SOLR communications:
- Alfresco Content Services 6.1.0.5
- Alfresco Community Edition latest (and it will be released with 6.2.0-ga)
- Alfresco Search Services 1.3.0.5
- Alfresco Insight Engine 1.1.0.5 (only available in private Docker Repository quay.io)
This blog post describes the changes required to upgrade your installation if you were using SSL or HTTP. Also a review on how the communication between SOLR and Repository works is included, as these concepts help to understand the simplified deployment diagrams with discouraged and recommended configurations.
Exec Summary
- Alfresco is being released from now using Mutual Authentication TLS between Alfresco Repository and SOLR by default
- Before upgrading from Alfresco 6.0, configuration properties in Repository and SOLR must be reviewed, as default values changed from none to https
- Docker Compose templates and Helm Charts must be also reviewed, as when using plain HTTP a new ALFRESCO_SECURE_COMMS environment variable is required to configure Alfresco Search Services and Alfresco Insight Engine images
- Out of the box truststores and keystores have been removed and they must be generated from scratch using the new Alfresco SSL Generator
- If you were using custom truststores and keystores, you can keep on using them when upgrading
- If you were using an unsecure deployment, you must switch to any of the recommended scenarios
Calls to Action
This section provides a guide to upgrade your installation from different use cases:
- You were using Mutual Authentication TLS (SSL)
- You were using HTTP and you want to employ SSL as part of the upgrade
- You were using HTTP and you want to continue using HTTP after the upgrade
1. If you were using Mutual Authentication TLS (SSL)
If you were using Mutual Authentication TLS protocol for these communications, everything should work as before when using these new releases.
However, from these versions, default keystores and truststores have been removed from distribution ZIP files and Docker Images.
- Repository provided the cryptographic stores inside the classpath, as part of the alfresco-repository JAR library.
- Search Services provided the cryptographic stores in the configuration folder for the instance templates, that is copied to alfresco and archive core when created.
Since these resources are not available out of the box anymore, it's required to create a new set of cryptographic stores before upgrading your server or to perform a backup of your previous stores and a restoring process in the upgraded server. A new tool, named Alfresco SSL Generator, has been developed for this purpose. This tool can be used from Windows, Linux and Mac computers and it produces all the cryptographic stores required to configure the Mutual Authentication TLS protocol.
$ cd ssl-tool
$ ./run.sh
$ tree keystores/
keystores/
├── alfresco
│ ├── keystore
│ ├── keystore-passwords.properties
│ ├── ssl-keystore-passwords.properties
│ ├── ssl-truststore-passwords.properties
│ ├── ssl.keystore
│ └── ssl.truststore
├── client
│ └── browser.p12
└── solr
├── ssl-keystore-passwords.properties
├── ssl-truststore-passwords.properties
├── ssl.repo.client.keystore
└── ssl.repo.client.truststoreOnce the new stores have been created, you can copy them to Repository and SOLR configuration folders. Detailed steps for this process are available at:
- Alfresco Content Services 6.1 > Installing the Alfresco WARS
- Alfresco Search Services 1.3 > Installing and configuring Search Services with mutual TLS
If you were using the Docker Images, verify that your configuration is using the keystores and truststores from an external volume or extend default Docker Image to copy these cryptographic stores to the configured paths inside the container. A sample Docker Compose configuration is provided at Alfresco/alfresco-ssl-generator
Detailed information on how to use Alfresco Search Services Docker Image is available at Alfresco/SearchServices
2. If you were using HTTP and you want to switch to SSL
If you were using plain HTTP protocol for these communications but you want to use SSL after the upgrade, you must review your configuration to enable this protocol.
Repository
Inside alfresco-global.properties file, check that following values are set.
solr.host=localhost
solr.port.ssl=8984
solr.secureComms=httpsUse Alfresco SSL Generator to produce all the cryptographic stores required to configure the Mutual Authentication TLS protocol.
Once the new stores have been created, you can copy them to Repository and SOLR configuration folders. Detailed steps for this process are available at Alfresco Content Services 6.1 > Installing the Alfresco WARS
Also Tomcat configuration for Repository needs to be reviewed, as a new SSL Connector for SOLR must be added. Detailed steps for this configuration are available at Alfresco Content Services 6.1 > Installing the Tomcat application server
SOLR
Inside solrcore.properties file (both "alfresco" and "archive" cores), following value must be set.
alfresco.secureComms=httpsAdditionally, Jetty server configuration and cryptographic stores paths must be set. Detailed steps for this configuration are available at Alfresco Search Services 1.3 > Installing and configuring Search Services with mutual TLS
If you were using the Docker Images, keystores and truststores must be set from an external volume or they should be copied to the configured paths inside the container. A sample Docker Compose configuration is provided at Alfresco/alfresco-ssl-generator
Detailed information on how to use Alfresco Search Services Docker Image is available at Alfresco/SearchServices
3. If you were using HTTP and you want to continue using HTTP
If you were using plain HTTP protocol for these communications, you must verify that you are explicitly using this configuration instead of relying on default values.
Repository
Inside alfresco-global.properties file, following value must be set.
solr.secureComms=noneIf you were using the Docker Image, verify that this setting is also set in your service declaration in docker-compose.yml file.
alfresco:
image: alfresco/alfresco-content-repository:6.1.0.5
mem_limit: 1700m
environment:
JAVA_OPTS: "
-Ddb.driver=org.postgresql.Driver
-Ddb.username=alfresco
-Ddb.password=alfresco
-Ddb.url=jdbc:postgresql://postgres:5432/alfresco
-Dsolr.host=solr6
-Dsolr.port=8983
-Dsolr.base.url=/solr
-Dindex.subsystem.name=solr6
-Dsolr.secureComms=none
"SOLR
Inside solrcore.properties file (both "alfresco" and "archive" cores), following value must be set.
alfresco.secureComms=noneIf you are using the Docker Image, a new environment variable named ALFRESCO_SECURE_COMMS is available. This variable accepts "none" for HTTP and "https" for Mutual TLS Authentication, so you should add this line to your service declaration in docker-compose.yml file.
solr6:
image: alfresco/alfresco-search-services:1.3.0.5
environment:
# Solr needs to know how to register itself with Alfresco
- SOLR_ALFRESCO_HOST=alfresco
- SOLR_ALFRESCO_PORT=8080
# Alfresco needs to know how to call solr
- SOLR_SOLR_HOST=solr6
- SOLR_SOLR_PORT=8983
# Create the default alfresco and archive cores
- SOLR_CREATE_ALFRESCO_DEFAULTS=alfresco,archive
- "SOLR_JAVA_MEM=-Xms2g -Xmx2g"
# HTTP by default
- ALFRESCO_SECURE_COMMS=noneWeb Proxy
When using plain HTTP for communications between Repository and SOLR, some REST API services must be protected from external access, as only communications in the internal network are secure. Following snippet is a sample configuration for NGINX, but you can use any other Web Proxy for that.
# Protect access to SOLR APIs
location ~ ^(/.*/service/api/solr/.*)$ {return 403;}
location ~ ^(/.*/s/api/solr/.*)$ {return 403;}
location ~ ^(/.*/wcservice/api/solr/.*)$ {return 403;}
location ~ ^(/.*/wcs/api/solr/.*)$ {return 403;}
location ~ ^(/.*/proxy/alfresco/api/solr/.*)$ {return 403 ;}
location ~ ^(/.*/-default-/proxy/alfresco/api/.*)$ {return 403;}
Additional information for this task is available at Adding a reverse proxy in front of Alfresco Content Services.
We have included also this configuration as default for Docker Compose reference templates:
acs-deployment/docker-compose.yml at master · Alfresco/acs-deployment · GitHub
Using alfresco/alfresco-acs-nginx:3.0.1 Docker Image for NGINX configuration.
acs-community-deployment/docker-compose.yml at master · Alfresco/acs-community-deployment · GitHub
Using alfresco/acs-community-ngnix:1.0.0 Docker Image for NGINX configuration.
These are the main changes you'll find, but detailed information is provided below on why we did this change.
Technical information
In this section communication between Alfresco Repository and SOLR is revisited, in order to provide the right background to understand the discouraged and recommended deployment configurations.
Communication between Alfresco Repository and SOLR
The communication between Alfresco Repository and SOLR happens in both ways:
- SOLR is polling Alfresco Repository for indexing (or tracking) the content, including changes in models, permissions, metadata and content. This polling is asynchronous and the frequency of these invocations can be scheduled using a cron expression named alfresco.cron in solrcore.properties file. By default, this communication happens every 10 seconds.
- Alfresco Repository is querying SOLR to retrieve searching results. These requests happen synchronously every time a user or a program perform a query from end users applications like Share Web Application or Alfresco Content Application.
Simplified Deployment Diagrams
Despite Alfresco can be deployed in many different ways, a simplified scenario can be described in the following diagrams.
Three alternatives are analysed:
- SOLR and Alfresco communicating with HTTP, directly exposing services from Tomcat and Jetty application servers (insecure)
- SOLR and Alfresco communicating with HTTP, exposing services via a Web Proxy (NGINX or equivalent) to protect external accesses to private REST API services (secure)
- SOLR and Alfresco communicating with Mutual Authentication TLS, directly exposing services from Tomcat and Jetty application servers (secure)
SOLR and Alfresco communicating with HTTP (insecure)
When using HTTP, SOLR REST API is exposed without authentication requirements. This means that SOLR can perform tracking operations with Repository but also any external application can use SOLR REST API to get information from repository (metadata, permission, models and content) without authentication.
The access to the SOLR Web Console is also exposed, at it's available by default at http://localhost:8983/solr without authentication.
In this scenario, Repository information is exposed, so you must avoid using this configuration.
SOLR and Alfresco communicating with HTTP and services protected by Web Proxy (secure)
When using HTTP behind a Web Proxy (like NGINX), SOLR REST API is exposed without authentication requirements internally. This means that SOLR can perform tracking operations with Repository using internal HTTP port 8080, but the external access to this API is protected by the Web Proxy. Any external application trying to access to SOLR REST API without authentication, using the external HTTP port 80, will be blocked by the rules described before at "If you were using HTTP > Web Proxy" section.
This approach is the one provided for Docker Compose and Helm Charts by default, as they are using a pre-configured Web Proxy to expose internal services.
The access to the SOLR Web Console, available by default at http://localhost:8983/solr, can be also exposed by the Web Proxy to be served at http://localhost/solr including a simple credential protection or any other mechanism to avoid public access.
NGINX sample configuration is provided below.
# SOLR Web Console
location /solr/ {
proxy_pass http://solr6:8983/;
# Basic authentication
auth_basic "Solr web console";
auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd;
} In this scenario, Repository information is safely protected, so this configuration is recommended.
SOLR and Alfresco communicating with Mutual Authentication TLS (secure)
When using Mutual Authentication TLS, SOLR REST API is exposed in SSL with clientAuth requirement. This means that SOLR can perform tracking operations with Repository using internal HTTPs port 8443 and signing the requests with the SOLR server certificate configured in solrcore.properties. Any external application trying to access to SOLR REST API using the HTTP port 8080, will be blocked by the Repository Web Filter. If the application uses the HTTPs port 8443, a clientAuth will be required and it will fail as the accepted server certificate is privately protected in SOLR server.
The access to the SOLR Web Console, available by default at https://localhost:8983/solr, is also protected by Mutual Authentication TLS. A client certificate, named browser.p12, is provided by the Alfresco SSL Generator in order to grant the access to this server.
In this scenario, Repository information is safely protected, so this configuration is recommended.
6 Comments
