Alfresco MTLS Configuration Deep Dive

cancel
Showing results for 
Search instead for 
Did you mean: 

Alfresco MTLS Configuration Deep Dive

angelborroy
Alfresco Employee
4 5 4,873

solr_certificates.png

 

When setting MTLS configuration between SOLR and Repository, some steps need to be done:

  1. Generate certificates for Repository (ssl.repo) and SOLR (ssl.repo.client) using a CA (alfresco.ca)
  2. Configure Tomcat Repository in order to manage incoming HTTPs requests from SOLR
  3. Configure Alfresco Repository WAR in order to build request to Jetty SOLR
  4. Configure Jetty SOLR in order to manage incoming HTTPs requests from Repository
  5. Configure SOLR WAR in order to build requests to Tomcat Repository

1. Generating certificates

Several certificates are required:

  • alfresco.ca is the public certificate of the CA used to generate ssl.repo and ssl.repo.client certificates
  • ssl.repo is the certificate (private and public) to be used for the Repository
  • ssl.repo.client is the certificate (private and public) to be used for SOLR

Keystore (private keys) and Truststore (public keys) files are required for the Repository and SOLR. Supported formats for these stores are JKS, JCEKS and PKCS12. The contents for every store are described below:

  • Repository Keystore (ssl.keystore) contains ssl.repo private key.
  • Repository Truststore (ssl.truststore) contains alfresco.ca and ssl.repo.client public keys.
  • SOLR Keystore (ssl.repo.client.keystore) contains ssl.repo.client private key.
  • SOLR Truststore (ssl.repo.client.truststore) contains alfresco.ca, ssl.repo and ssl.repo.client public keys.

These files can be generated manually but it's easier to use the Alfresco SSL Generator Tool.

2. Configuring Tomcat Repository

Tomcat Repository is handling secure tracking requests from SOLR WAR, so a new Tomcat Connector must be added to /usr/local/tomcat/conf/server.xml file.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
    connectionTimeout="20000"
    SSLEnabled="true" maxThreads="150" scheme="https"
    keystoreFile="/usr/local/tomcat/alf_data/keystore/ssl.keystore"
    keystorePass="kT9X6oe68t" keystoreType="JCEKS" secure="true"
    truststoreFile="/usr/local/tomcat/alf_data/keystore/ssl.truststore"
    truststorePass="kT9X6oe68t" truststoreType="JCEKS" clientAuth="want" sslProtocol="TLS">
</Connector>

3. Configuring Alfresco Repository WAR

Alfresco Repository WAR requires to be configured in order to build secure requests to Jetty SOLR when performing searching operations. Add following settings to /usr/local/tomcat/shared/classes/alfresco-global.properties file.

solr.port.ssl=8983
solr.secureComms=https

dir.keystore=/usr/local/tomcat/alf_data/keystore
encryption.ssl.keystore.type=JCEKS
encryption.ssl.truststore.type=JCEKS

Inside dir.keystore folder following files are required: ssl.keystore, ssl.truststore, ssl-keystore-password.properties, ssl-truststore-password.properties.

4. Configuring Jetty SOLR

Jetty SOLR is handling secure searching operations from the Repository. Following configuration is required to be added to SOLR starting script solr.in.sh (Linux) or solr.in.cmd (Windows) under folder /opt/alfresco-search-services/

SOLR_SSL_TRUST_STORE=/opt/alfresco-search-services/keystore/ssl.repo.client.truststore
SOLR_SSL_TRUST_STORE_PASSWORD=kT9X6oe68t
SOLR_SSL_TRUST_STORE_TYPE=JCEKS
SOLR_SSL_KEY_STORE=/opt/alfresco-search-services/keystore/ssl.repo.client.keystore
SOLR_SSL_KEY_STORE_PASSWORD=kT9X6oe68t
SOLR_SSL_KEY_STORE_TYPE=JCEKS
SOLR_SSL_NEED_CLIENT_AUTH=true
SOLR_OPTS="$SOLR_OPTS -Dsolr.allow.unsafe.resourceloading=true -Dsolr.ssl.checkPeerName=false -Dsolr.data.dir.root=$DIST_DIR/data -Dsolr.solr.model.dir=$DIST_DIR/data/alfrescoModels"

5. Configuring SOLR WAR

SOLR WAR requires to be configured in order to build secure requests to Tomcat Repository when performing tracking operations. Following lines must be added to both SOLR cores (alfresco and archive) in the following locations:

  • /opt/alfresco-search-services/solrhome/alfresco/conf/solrcore.properties
  • /opt/alfresco-search-services/solrhome/archive/conf/solrcore.properties
alfresco.secureComms=https
alfresco.port.ssl=8443

alfresco.encryption.ssl.truststore.location=/opt/alfresco-search-services/keystore/ssl.repo.client.truststore
alfresco.encryption.ssl.keystore.provider=JCEKS
alfresco.encryption.ssl.truststore.type=
alfresco.encryption.ssl.keystore.location=/opt/alfresco-search-services/keystore/ssl.repo.client.keystore
alfresco.encryption.ssl.truststore.provider=JCEKS
alfresco.encryption.ssl.truststore.passwordFileLocation=/opt/alfresco-search-services/keystore/ssl-truststore-passwords.properties
alfresco.encryption.ssl.keystore.type=
alfresco.encryption.ssl.keystore.passwordFileLocation=/opt/alfresco-search-services/keystore/ssl-keystore-passwords.properties

Troubleshooting

If you are experimenting problems when searching from Alfresco or Share web applications, check steps 3 and 4.

If you are experimenting problems when indexing / tracking from SOLR web applications, check steps 2 and 5.

About the Author
Angel Borroy is Senior Software Engineer in Alfresco. Over the last 15 years, he has been working as a software architect on Java, BPM, document management and electronic signatures. He has been working with Alfresco during the last years to customize several implementations in large organizations and to provide add-ons to the Community based on Record Management and Electronic Signature. He writes (sometimes) on his personal blog http://angelborroy.wordpress.com. He is (proud) member of the Order of the Bee. Angel Borroy is Engineer at Alfresco.
4 Comments
citylights
Member II

Angel,

We are deploying Alfresco ACS as an internal document repository within a larger solution. Can we deploy ACS without encrypted connections between SOLR and ACS ?

 

Rgs

Shaun

angelborroy
Alfresco Employee

Shaun,

Always that your security has been granted, you can use plain connections. But be aware of the risks and prevent the endpoints from being accessed by unwanted users.

Please, check also the following link to understand how to configure the system in a safe way.

https://hub.alfresco.com/t5/alfresco-content-services-blog/alfresco-6-1-is-coming-with-mutual-tls-au...

FrancescoPapini
Partner

Great article man,

I was struggling before to have a working configuration because some concepts were not so clear for me.

Just a small note (for me and people having the same issue):

I had to change from:
alfresco.encryption.ssl.truststore.provider=JCEKS
to:
alfresco.encryption.ssl.truststore.provider=SunJCE

and from:
alfresco.encryption.ssl.truststore.type=
to:
alfresco.encryption.ssl.truststore.type=JCEKS

and also the same thing for the keystore part.

Thanks again for your article :-)

mcanic
Member II

Dear Angel,

I can not make it work, Alfresco-Solr TLS, struggling for few days.

Alfresco Community 7, TOmcat 9 and OpenJDK 11.0.2.

Ive followed all steps:

1. Generated SSL keystore and trusted store with Alfresco SSL Generator, with "classsic" and "community" parameters. (Ive tried the same with generate_keystores.bat, no success as well).

2. Setup Tomcat server.xml:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11AprProtocol"
connectionTimeout="240000"
SSLEnabled="true"
maxThreads="150"
scheme="https"
keystoreFile="C:/Alfresco/certificates/alf_data/keystore/ssl.keystore"
keystorePass="keystore"
keystoreType="JCEKS"
secure="true"
truststoreFile="C:/Alfresco/certificates/alf_data/keystore/ssl.truststore"
truststorePass="truststore"
truststoreType="JCEKS"
clientAuth="want"
sslProtocol="TLS">
</Connector>

3. Setup alfresco-global.properties:

dir.root=C:/Alfresco/certificates
dir.keystore=${dir.root}/alf_data/keystore
dir.license.external=${dir.root}/licenses
encryption.ssl.keystore.type=JCEKS
encryption.ssl.keystore.location=${dir.keystore}/ssl.keystore
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 indexing
solr.secureComms=https
index.subsystem.name=solr6
solr.host=AIS-ECM-APP-CT-DB
solr.port=8983
solr.port.ssl=8983

4. Setup solr.in.cmd:

set SOLR_SSL_KEY_STORE=C:\Alfresco\alfresco-search-services\solrhome\keystore\ssl.repo.client.keystore
set SOLR_SSL_KEY_STORE_PASSWORD=keystore
set SOLR_SSL_KEY_STORE_TYPE=JCEKS
set SOLR_SSL_TRUST_STORE=C:\Alfresco\alfresco-search-services\solrhome\keystore\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=falseset SOLR_SOLR_HOST=AIS-ECM-APP-CT-DB
set SOLR_ALFRESCO_HOST=AIS-ECM-APP-CT-DB

5. Setup solrcore.properties:

alfresco.encryption.ssl.truststore.location=C\:\\Alfresco\\alfresco-search-services\\solrhome\\keystore\\ssl.repo.client.truststore
alfresco.encryption.ssl.keystore.provider=
alfresco.encryption.ssl.truststore.type=JCEKS
alfresco.host=AIS-ECM-APP-CT-DB
alfresco.encryption.ssl.keystore.location=C\:\\Alfresco\\alfresco-search-services\\solrhome\\keystore\\ssl.repo.client.keystore
alfresco.encryption.ssl.truststore.provider=
alfresco.encryption.ssl.truststore.passwordFileLocation=C\:\\Alfresco\\alfresco-search-services\\solrhome\\keystore\\ssl-truststore-passwords.properties
alfresco.encryption.ssl.keystore.passwordFileLocation=C\:\\Alfresco\\alfresco-search-services\\solrhome\\keystore\\ssl-keystore-passwords.properties
alfresco.port=8443
alfresco.encryption.ssl.keystore.type=JCEKS
alfresco.secureComms=https

6. Coppied keystores on both alfresco and solr locations:

On C:\Alfresco\certificates\alf_data\keystore files:

ssl.keystore, ssl.truststore, ssl-keystore-passwords.properties, ssl-truststore-passwords.properties, browser.p12 (left Alfresco's original keystore, used for data encryption)

On C:\Alfresco\alfresco-search-services\solrhome\keystore:

sssl.repo.client.keystore, ssl,repo.client.truststore, ssl-keystore-passwords.properties, ssl-truststore-passwords.properties.

When I log into share, with https, I get this error im tomcat and alfresco logs (below). Looks simple, like keystore password is missing, but I can not relize where and why. I strictrly followed procedure, Iv used default values and I tried, as I said, with both CURRENT option when generating keystores and generate_keystores.bat from ALfresco, no results. On solr side Im getting 403 error when trying to access repository.

Any idea, any hint, looks like Im missing smth, but can not relize what.

Thanks in advance,

Cane

Caused by: org.alfresco.error.AlfrescoRuntimeException: 05170044 Unable to create key manager
at org.alfresco.encryption.AlfrescoKeyStoreImpl.createKeyManagers(AlfrescoKeyStoreImpl.java:337)
at org.alfresco.encryption.ssl.AuthSSLProtocolSocketFactory.createSSLContext(AuthSSLProtocolSocketFactory.java:103)
at org.alfresco.encryption.ssl.AuthSSLProtocolSocketFactory.getSSLContext(AuthSSLProtocolSocketFactory.java:124)
... 109 more
Caused by: java.lang.IllegalArgumentException: password can't be null
at java.base/com.sun.crypto.provider.KeyProtector.<init>(KeyProtector.java:88)
at java.base/com.sun.crypto.provider.JceKeyStore.engineGetKey(JceKeyStore.java:122)
at java.base/java.security.KeyStore.getKey(KeyStore.java:1050)
at java.base/sun.security.ssl.SunX509KeyManagerImpl.<init>(SunX509KeyManagerImpl.java:141)
at java.base/sun.security.ssl.KeyManagerFactoryImpl$SunX509.engineInit(KeyManagerFactoryImpl.java:64)
at java.base/javax.net.ssl.KeyManagerFactory.init(KeyManagerFactory.java:274)
at org.alfresco.encryption.AlfrescoKeyStoreImpl.createKeyManagers(AlfrescoKeyStoreImpl.java:332)
... 111 more