Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > Author: angelborroy

The release of the following versions includes Mutual TLS Authentication by Default for Alfresco Repository and SOLR communications:

 

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:

  1. You were using Mutual Authentication TLS (SSL)
  2. You were using HTTP and you want to employ SSL as part of the upgrade
  3. 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.truststore

 

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:


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=https

 

Use 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=https

 

Additionally, 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=none

If 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=none

If 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=none

 

Web 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.

 

SOLR Indexing scheduled task

 

 

Searching from an end user 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)

Unprotected deployment for ACS using http

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)

 

ACS deployment protected by Web Proxy

 

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)

ACS deployment protected by Mutual Authentication TLS

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.

This article is about modules for the ACS repository and does not cover Share. Share modules from previous Alfresco versions can be deployed to ACS 6 without modifications.

 

This article describes how to migrate Alfresco SDK 3 based projects alfresco-platform-jar-archetype to Alfresco SDK 3 projects including the new dependencies from ACS 6. However, as a third party developer, it might be a lot easier for you to wait for the next version of the official Alfresco SDK.

 

Step 1: Upgrade Alfresco and Share versions

 

Find following properties in your original pom.xml file...

 

<alfresco.platform.version>5.2.f</alfresco.platform.version>
<alfresco.share.version>5.2.e</alfresco.share.version>

 

... and replace the values with the following numbers...

 

<alfresco.platform.version>6.0.7-ga</alfresco.platform.version>
<alfresco.share.version>6.0.b</alfresco.share.version>

 

Step 2: Change Alfresco distribution dependency name

 

Identify Alfresco distribution dependency in your original pom.xml file...

 

<dependency>
    <groupId>${alfresco.groupId}</groupId>
    <artifactId>alfresco-platform-distribution</artifactId>
    <version>${alfresco.platform.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

 

...and replace the name by using the following entry...

 

<dependency>
    <groupId>${alfresco.groupId}</groupId>
    <artifactId>alfresco-content-services-community-distribution</artifactId>
    <version>${alfresco.platform.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

 

From this point you can compile and package your addon for ACS 6. 

 

Step 3: Refactor your code where required

 

Updates that might affect your custom code are (among others):

 

  • Spring
  • Quartz
  • POI
  • Jackson
  • multiple commons-* libraries

 

Removed libraries:

 

  • Hibernate

 

ACS 6 Migration Guide wiki page collects useful information about updating Java code to work with the ACS6 repository.

 

Conclusion

 

These simple instructions can be applied to upgrade your repository addons to ACS 6, but Alfresco will release a detailed guide for migration procedures in the future. 

Alfresco is delivering a Docker Compose for ACS Community deployment that can only be used for local testing environments:

 

acs-community-deployment/docker-compose at master · Alfresco/acs-community-deployment · GitHub 

 

In order to deploy the product in real environments, some additional configurations must be performed. You can find some of this configurations described at Using Alfresco 201804-EA in a simple PROD environment 

 

However, as it should be advisable to maintain original Alfresco resources untouched, another approach is required. Docker Compose allows to share configuration by using additional YML specification files to override the original one. Below some instructions to configure default Alfresco Docker Compose for ACS 6 Community are provided.

 

Checkout or download official Docker Compose

 

$ git clone git@github.com:Alfresco/acs-community-deployment.git
Cloning into 'acs-community-deployment'...
remote: Counting objects: 145, done.
remote: Compressing objects: 100% (91/91), done.
remote: Total 145 (delta 79), reused 103 (delta 49), pack-reused 0
Receiving objects: 100% (145/145), 27.53 KiB | 240.00 KiB/s, done.
Resolving deltas: 100% (79/79), done.

$ cd acs-community-deployment/docker-compose/

$ ls
docker-compose.yml

 

Create a docker-compose.override.yml file

 

You can add volumes mapping, ports exposition and additional Docker images to original Docker Compose.

 

$ touch docker-compose.override.yml

$ cat docker-compose.override.yml
version: "3"

services:

    httpd:
        build: ./httpd
        ports:
          - 443:443
        links:
          - alfresco
          - share
          - solr6 

    alfresco:
      volumes:
          - ./data/alf-repo-data:/usr/local/tomcat/alf_data
      ports:
          - 21:2121

    postgres:
      volumes:
          - ./data/postgres-data:/var/lib/postgresql/data

    solr6:
      volumes:
          - ./data/solr-data:/opt/alfresco-search-services/data

 

Add your customised images

 

Adding an NGIX or Apache HTTPd server should be recommendable for many environments.

 

$ tree httpd
httpd
├── Dockerfile
└── assets
    ├── CA.pem
    ├── alfresco-vhost.conf
    ├── server.crt
    └── server.key

 

You can use something provided by the Community like this one, or any other you like.

 

Start the composition

 

You can use default commands to run Docker Compose.

Extensions declared in docker-compose.override.yml file will be picked automatically, so your volumes, ports and additional Docker images will be available in the composition.

 

$ docker-compose up -d --build

 

Now Alfresco is running in a real environment by using official (and untouched) Docker Compose resource.

There are great resources inside this Community on how to deploy Alfresco 6 using Docker Compose

Although some real environments will require Kubernetes deployment, many others will be managed with a simple Docker Composition. This post is based in Alfresco 201804-EA release, but these instructions can be applied on many other Alfresco 6 releases.

 

This post includes sample configuration for every point, but you can check detailed and running configuration at 201804-EA Docker template

 

Images

Alfresco 6 provides several Docker Images to build every container for different services:

 

Persistent storage

Docker relies on external storage to persist information. When running an Alfresco server, repository, database and search containers are storing data that needs to be persisted.

A volumes tag must be added in docker-compose.yml file to every container definition to map local storage from your server with logical storage inside the container.

alfresco:
    volumes:
        - alf-repo-data:/usr/local/tomcat/alf_data
postgres:
    volumes:
        - postgres-data:/var/lib/postgresql/data
solr6:
    volumes:
        - solr-data:/opt/alfresco-search-services/data

volumes:
    alf-repo-data:
        external: true
    postgres-data:
        external: true
    solr-data:
        external: true

This code is using named volumes. In case they didn't exists, they can be created by using following shell lines:

$ docker volume create alf-repo-data
$ docker volume create postgres-data
$ docker volume create solr-data

Once this configuration is applied, your data will survive any Docker or Server re-starting.

 

Ports configuration

Docker uses internal ports for containers and it exposes to the server a mapping of these ports. In order to configure Alfresco protocols, ports exposition needs to be declared in Alfresco Repository Dockerfile...

EXPOSE 2121 1143 2525 1445 1137/udp 1138/udp 1139

... and mapping needs to be declared in docker-compose.yml

alfresco:
ports:
- 21:2121      # FTP port
- 25:2525      # SMTP port
- 143:1143     # IMAP port
- 445:1145     # CIFS
- 137:1137/udp # CIFS
- 138:1138/udp # CIFS
- 139:1139     # CIFS

It's also required to open these ports in the firewall of the operative system hosting Docker. 

Once this configuration is applied, your Alfresco server will be accessed by FTP, SMTP, IMAP and CIFS.

 

Web applications ports (AJP 8009 for Alfresco, AJP 8009 for Share and HTTP 8983 for Solr) must be also exposed to configure the Proxy at httpd container.

ProxyPass "/share" "ajp://share:8009/share"
ProxyPassReverse "/share" "ajp://share:8009/share"

ProxyPass "/solr" "http://solr6:8983/solr"
ProxyPassReverse "/solr" "http://solr6:8983/solr"   

ProxyPass "/alfresco" "ajp://alfresco:8009/alfresco"
ProxyPassReverse "/alfresco" "ajp://alfresco:8009/alfresco"

It can be used any other Web Container (as NGINX) to provide such configuration.

Once this configuration is applied, your Alfresco server will be accessed by using the same HTTP Port. In the next point the use of port 443 for HTTPs is detailed.

 

Configuring SSL Certificates

To provide real SSL Certificates, assets folder can be filled with working files:

  • CA.pem - CA Certificate Path
  • server.crt - Certificate File
  • server.key - Certificate Key File

Otherwise, it can be configured an external Docker volume to hold these certificates. 

Listen 443
<VirtualHost *:443>
ServerName alfresco.keensoft.es
SSLEngine on
SSLCertificateFile /usr/local/apache2/conf/server.crt
SSLCertificateKeyFile /usr/local/apache2/conf/server.key
SSLCACertificatePath /etc/pki/tls/certs/
SSLOptions +StdEnvVars +ExportCertData
</VirtualHost>

Once this configuration is applied, your Alfresco server will be accessed by HTTPs.

 

Adding modules

Folders to hold AMP or JAR modules has been provided.

alfresco/target/amps
alfresco/target/jars
share/target/amps_share
share/target/jars

Every addon copied into this folders will be deployed in the container.

If further configuration is required in alfresco-global.properties, Dockerfile can be modified to add pairs of property=value blocks

# Add services configuration to alfresco-global.properties
RUN echo -e '\n\
property=value\n\
\n\
' >> /usr/local/tomcat/shared/classes/alfresco-global.properties

Once this configuration is applied, your Alfresco server will provide features from installed modules.

 

Resources

Filter Blog

By date: By tag: